Spec-Driven Development e Harness Engineering: o início da MINHA saga

Eu comecei a me aprofundar mais nos estudos de IA e, com isso, conheci vários termos, frameworks, tecnologias e métodos diferentes, o que me fez inicialmente surtar porque foi uma chuva de informações, até que eu decidi focar no que realmente faz sentido no meu dia a dia e nas coisas em que eu trabalho.

Daí surgiu o meu interesse em Harness Engineering. À primeira vista, eu entendi que era “só” você criar uns agentes e colocar no seu projeto que assim a mágica da programação feita 100% por IA iria acontecer e eu finalmente conseguiria tirar todas as minhas ideias do papel… só que não. Descobri que pra isso acontecer, você precisa também do Spec-Driven Development (SDD) para a IA não viajar e saber das especificações de negócio também. Mas como que amarra tudo?!

Resolvi estudar sobre os assuntos, de onde vêm, pra que existem e então eu descobri que sim, é um pouquinho complexo, mas a lógica é simples de entender (eu acho). Deixa eu explicar primeiro com as minhas palavras e aí no final eu deixo uns links para você ler mais em detalhe.

Spec-Driven Development (SSD): o quê e pra quê

O SDD é o upstream do projeto. Ou seja, é aqui que você vai incluir toda a documentação, especificações, PRDs, RFCs, diagramas, modelagens e tudo o que ajudar a IA a entender como entregar melhor o que for desenvolvido.

Por exemplo, o projeto é construir uma casa, então o SDD vai ter as plantas baixas da construção, definição do material de construção, quais pisos serão colocados, quais as cores das paredes, e por aí vai.

Nesse upstream, o principal objetivo é garantir que a IA não vá alucinar, então deve-se garantir que todas as especificações estejam megaestruturadas e com zero possibilidade de equívocos antes de escrever qualquer linha de código.

Ou seja, em vez de histórias em texto livre, são feitas as specs em formatos padronizados (como Markdown ou YAML) com cenários BDD (Given-When-Then), contratos OpenAPI e critérios explícitos de Definition of Done (DoD).

Se for colocar o SDD em um checklist, seria a estrutura com:

Regras de negócio e comportamento com cenários de uso escritos de forma estruturada, preferencialmente em BDD.
Contratos de interface/API com o desenho de como os sistemas conversam, geralmente escritos em OpenAPI (Swagger) com formatos de saídas, entradas e código de erro.
Modelagem de dados com a estrutura onde essas informações ficarão. Podem ser em formato de schemas, dicionário de dados ou diagramas.
Requisitos não funcionais e DoD com regras de segurança, expectativas de performance, cobertura de testes.

No repositório, essa estrutura ficaria no .spec/ ou em docs/spec/. Ficaria algo assim:

thing-project-validation/
├── .spec/                             # UPSTREAM: Fonte Única da Verdade pra IA
│   ├── features/
│   │   └── check_thing_exists.feature # Regras de Negócio BDD (Gherkin)
│   ├── contracts/
│   │   └── check_thing_api.yaml       # Contrato formal da API (OpenAPI 3.0)
│   └── guidelines/
│       └── architecture_rules.md      # Padrões, DoD e tratamento de erros

Ok, agora vamos para a segunda parte que é o harness.

Harness Engineering: o quê e pra quê

O Harness Engineering é o downstream do projeto. Se o SDD é o projeto arquitetônico e o planejamento da construção da casa, o Harness Engineering vai ser o conjunto de andaimes, redes de proteção e os inspetores de obra.

Na prática, é a infraestrutura de automação (o CI/CD turbinado) que testa, valida e avalia o código gerado pela IA antes que um humano precise revisá-lo ou que ele vá para produção. Numa analogia mais fácil que a da casa, imagine que você comprou um carro autônomo. O SDD é você colocando o endereço exato no mapa. O Harness Engineering é o sensor de colisão, os freios automáticos e o leitor de faixas. Se o carro (a IA) tentar desviar da rota ou subir na calçada (alucinar código), os freios (quality gates) são acionados na mesma hora, impedindo o acidente.

Ah, mas o que são quality gates, minha senhora?

Calma, eu te explico, pequenu gafanhotu.

No parágrafo acima, eu falei que o harness é o que possui o CI/CD turbinado do seu projeto e vai testar e validar o código. Então os quality gates são as “prendas” que devem ser pagas para garantir que está tudo funcionando. Se alguma dessas prendas não for paga, o teste para e não continua, forçando a IA a fazer a correção necessária no código antes de tentar testar de novo.

Em termos gerais, qualquer verificação determinística que um humano faria manualmente deve ser convertida em um comando automatizado na esteira de CI/CD. Se colocássemos em uma checklist básica desses quality gates, teriam essas validações:

Gate 1 – Sintaxe e formatação que verificam se o código está bonito e padronizado.
Gate 2 – Checagem de tipagem que vai garantir que variáveis e funções estão recebendo os tipos certos de dados.
Gate 3 – Testes funcionais e unitários que vão simular o uso do sistema e conferir se o resultado bate com as regras de negócio.
Gate 4 – Cobertura de código que vai medir a porcentagem do código que o Gate 3 testou.
Gate 5 – Segurança que vai varrer o código em busca de brechas de segurança conhecidas, como uma SQL injection.

Resumindo, o harness vai garantir que os agentes de IA façam e ajam como deve ser, sem que eles saiam do roteiro proposto lá no upstream.

No repositório, essa estrutura ficaria no .src/ e em .tests/:

├── src/                               # DOWNSTREAM: Código gerado/mantido pela IA
│   ├── controllers/
│   │   └── thing_controller.py
│   ├── services/
│   │   └── thing_service.py
│   └── repositories/
│       └── thing_repository.py
├── tests/                             # DOWNSTREAM: Testes automatizados
│   ├── unit/
│   └── integration/
├── .github/
│   └── workflows/
│       └── quality_gates.yml          # HARNESS: Pipeline de CI/CD
└── .cursorrules/opencode/CLAUDE.md    # Instruções globais para os Agentes de IA

Tá, entendeu tudo agora? A lógica, eu espero que sim. Mas aí, como que amarra tudo isso.

Orquestração End-to-End

Basicamente, você vai amarrar as especificações do upstream aos quality gates do downstream por meio de uma orquestração automatizada.

O fluxo prático ficaria dessa maneira:

O Product Manager valida a tarefa (no Jira, ou em alguma plataforma de projetos).
Um agente de IA (via MCP) lê o card, consulta a pasta .spec/ no repositório e cria a branch com a funcionalidade e os testes.
A esteira de CI/CD aciona automaticamente os 5 quality gates. Se houver falha, o erro retorna para a IA corrigir de forma autônoma.
O desenvolvedor realiza a revisão humana final focando exclusivamente na arquitetura e nas regras de negócio.

Possível desafio cultural com o time

Acredito que um dos principais obstáculos na adoção não é a tecnologia, mas a mudança de hábitos. Desenvolvedores habituados a ficarem 80% do tempo escrevendo sintaxe costumam ter mais resistência por medo de perder o controle.

A chave da liderança é ajustar o papel do time: eles deixam de ser “digitadores de código” para se tornarem “arquitetos e avaliadores de software”. Deixam de receber demanda e passam a olhar para a solução e a entrega de valor.

Aqui tem uma oportunidade de incentivar o time a exercitar o pensamento de nível superior. Diante de um bug ou uma nova demanda, a primeira pergunta do dev não deve ser “Como digito este código?”, mas sim “A especificação em .spec/ estava clara o suficiente ou faltou algum limite para a IA?”.

Projeto fictício

Em um projeto fictício de validar se o e-mail do usuário já existe na base, a estrutura ficaria assim:

projeto-validador-email/
├── .spec/                             # UPSTREAM
│   ├── features/
│   │   └── check_email_exists.feature # Regras de Negócio (BDD)
│   ├── contracts/
│   │   └── check_email_api.yaml       # Contratos (OpenAPI)
│   └── guidelines/
│       └── architecture_rules.md      # Padrões, DoD e tratamento de erros
├── src/                               # DOWNSTREAM: Código feito/mantido por IA
│   ├── controllers/
│   │   └── user_controller.py
│   ├── services/
│   │   └── user_service.py
│   └── repositories/
│       └── user_repository.py
├── tests/                             # DOWNSTREAM: Testes automatizados
│   ├── unit/
│   └── integration/
├── .github/
│   └── workflows/
│       └── quality_gates.yml          # HARNESS: Pipeline de CI/CD
└── .cursorrules / CLAUDE.md           # Instruções globais para os Agentes de IA

Visualização do Harness (.github/workflows/quality_gates.yml)

Etapa	Comando Executado	Ação em Caso de Falha
Gate 1: Formatação	`ruff check src/`	Bloqueia o PR e notifica IA sobre erros de sintaxe.
Gate 2: Tipagem	`mypy src/`	Impede funções com parâmetros sem tipo estático.
Gate 3: Testes BDD	`pytest tests/`	Valida se os cenários do `.feature` foram cumpridos.
Gate 4: Cobertura	`pytest --cov=src --cov-fail-under=90`	Barra o PR se a cobertura for inferior a 90%.
Gate 5: Segurança	`bandit -r src/`	Interrompe o processo se houver vulnerabilidade (ex: SQLi).

O arquivo .github/copilot-instructions.md deve ser colocado exatamente dentro da pasta .github/ localizada na raiz do repositório do seu projeto, diferente dos arquivos .cursorrules / CLAUDE.md que ficariam direto na raiz.

projeto-validador-email/
├── .github/
│   ├── copilot-instructions.md   <-- AQUI (Lido automaticamente pelo Copilot)
│   └── workflows/
│       └── quality_gates.yml
├── .spec/                        # UPSTREAM (Specs, BDD, OpenAPI)
├── src/                          # DOWNSTREAM (Código da aplicação)
├── tests/                        # DOWNSTREAM (Testes automatizados)
└── README.md

Mapeamento por Assistente de IA

GitHub Copilot (VS Code / JetBrains): Reconhece nativamente o caminho .github/copilot-instructions.md.
Cursor / Windsurf / Claude Code: Caso a squad utilize esses editores no futuro, o mesmo conteúdo pode ser espelhado na raiz do projeto (/) com o nome .cursorrules ou CLAUDE.md.

Extras: Spec-Kit

Existe o repositório GitHub Spec Kit que se encaixa nessa estrutura de spec-driven development no upstream do projeto, o que pode facilitar bastante a criação das especificações e garantir que a IA gere os códigos com mais precisão e barre as alunicações, falha de tipagem ou erro nos testes.

E aí, o projeto ganharia uma pasta específica para ele, o que deixaria com a estrutura abaixo, ainda considerando o meu projeto de validação de e-mail:

projeto-validador-email/
├── .specify/                      # UPSTREAM: via Spec-Kit CLI
│   ├── constitution.md            # Regras e princípios de arquitetura
│   ├── templates/                 # Moldes para especificações, planos e tarefas
│   └── specs/                     # Funcionalidades organizadas por escopo
│       └── 001-check-email/
│           ├── spec.md            # Requisitos de negócio, BDD e cenários
│           ├── plan.md            # Arquitetura, modelo de dados e contratos
│           └── tasks.md           # Checklist em ordem de execução para a IA
├── .github/
│   ├── copilot-instructions.md    # Aponta o Copilot para ler a pasta .specify/
│   └── workflows/
│       └── quality_gates.yml      # DOWNSTREAM: Pipeline de testes e validação
├── src/                           # DOWNSTREAM: Código-fonte gerado
│   ├── controllers/
│   ├── services/
│   └── repositories/
├── tests/                         # DOWNSTREAM: Testes automatizados
│   ├── unit/
│   └── integration/
└── README.md                      # Visão geral do projeto e comandos locais

Resumindo: Spec-Driven Development & Harness Engineering

Eu não coloquei nada em prática – AINDA.

O engajamento do time é o primeiro passo e enxergo que estou conseguindo construir isso com eles. Escolhemos um projeto pequeno para fazermos essa mudança e iniciarmos os primeiros testes de como funciona toda a orquestração.

Eu escrevi esse post para criar uma série com nossos aprendizados, o que deu bom, o que bugou no meio do caminho, onde a gente teve dificuldades. Acredito que para outros Squads Lead / Líderes de Tecnologia que também estão buscando melhorar a performance do time com uso de IA, pode ser bem útil.

E se você já sabe como fazer tudo isso, fico muito agradecida se pudermos bater um papo!

Espero poder ajudar você e outros nessa jornada. Vai ser divertido.

Links úteis e referências

Diving Into Spec-Driven Development With GitHub Spec Kit – Microsoft for Developers
Spec-Driven Development: A Spec-First Approach to AI-Native Engineering – Microsoft for Developers
Agent Skills Marketplace | Codex & Claude Skills | SkillsMP
Gemini Aprendizado Guiado: muito do que eu aprendi foi usando o modelo de Aprendizado Guiado do Gemini.