SDD e Harness Design: o fluxo profissional com IA

O salto que importa

O problema central de trabalhar com IA em software não é escolher “o modelo da semana”. Modelos mudam rápido. A pergunta difícil é: como transformar uma intenção humana em software confiável sem perder controle, qualidade e responsabilidade no caminho.

Vibe coding, a prática de construir pela conversa com o modelo, mostrou que IA consegue gerar muito código a partir de linguagem natural. Isso é poderoso para protótipos. Mas, em ambiente corporativo, entregar software não termina quando o código aparece. A entrega também envolve alinhar escopo, preservar arquitetura, proteger dados, validar comportamento, revisar mudanças, auditar decisões e manter o sistema saudável depois do deploy.

É aqui que entram duas ideias que precisam andar juntas:

• SDD, ou Spec-Driven Development: escrever e evoluir especificações que funcionam como um contrato verificável de intenção.
• Harness Design: desenhar o sistema de trabalho em volta do agente para que ele tenha contexto, ferramentas, limites, validação e governança.

Separadas, essas ideias ajudam. Juntas, elas mudam o padrão da entrega.

O que é SDD

SDD significa Spec-Driven Development, desenvolvimento guiado por especificação.

Neste contexto, uma spec, ou especificação, não é um PDF gigante nem um retorno ao waterfall, aquele modelo pesado em que tudo parece precisar estar fechado antes de começar. É um artefato vivo, versionado e revisável que responde:

• qual problema estamos resolvendo;
• para quem isso importa;
• o que está dentro e fora do escopo;
• quais comportamentos precisam existir;
• quais restrições técnicas, legais ou de produto precisam ser respeitadas;
• quais critérios provam que a entrega está correta;
• quais riscos precisam de revisão humana.

A mudança central é simples: o agente não implementa “a ideia que ficou implícita na conversa”. Ele implementa contra uma referência explícita, revisável e verificável.

O que é Harness Design

Harness Design é o desenho do ambiente operacional do agente.

Se SDD responde “o que precisa ser verdade?”, o harness responde “como criamos um sistema onde o agente consegue executar, validar e melhorar sem depender de memória informal, sorte ou contexto perdido na conversa?”.

Um harness pode incluir:

• instruções persistentes, como AGENTS.md, CLAUDE.md ou .cursor/rules/;
• documentação versionada de arquitetura, produto e domínio;
• templates de spec, PRD (documento de requisitos de produto), plano e revisão;
• ferramentas disponíveis ao agente, como terminal, GitHub, navegador, logs e MCP servers, que conectam o agente a ferramentas externas;
• limites de permissão e pontos de aprovação humana;
• comandos de validação, CI, lint, typecheck, testes e checagens de segurança;
• padrões de PR, responsáveis, rollback e auditoria;
• loops de aprendizado para transformar falhas em regras, testes ou docs.

O ponto não é criar uma prisão para o agente. É criar trilhos. Bons trilhos não impedem movimento; eles tornam o movimento previsível, revisável e seguro.

Exemplo aplicado: login único corporativo

Imagine que uma empresa precisa adicionar SSO, ou login único, para clientes corporativos.

Fluxo amador

Alguém pede ao agente: “implementa SSO com Google”. O agente cria uma integração, adiciona dependências, muda autenticação, passa no build e a tela abre. Parece progresso.

Mas ninguém respondeu:

• quais provedores são suportados;
• como mapear domínio para organização;
• o que acontece com usuários existentes;
• quem pode configurar SSO;
• como auditar login;
• como reverter se o provedor cair;
• quais testes provam que permissões não vazam.

Isso não é engenharia corporativa. É uma demo vestida de entrega.

Fluxo SDD + Harness

Pessoa de produto ou PM escreve a intenção: clientes corporativos precisam autenticar usuários pelo provedor SSO configurado por organização.

Liderança técnica ou tech lead transforma isso em spec: fluxos, estados, permissões, limites, schemas, endpoints e riscos.

QA deriva cenários: usuário sem domínio permitido, provedor indisponível, convite expirado, organização sem SSO, usuário existente com e-mail igual.

Segurança define restrições: tokens não podem ir para armazenamento inseguro; logs não podem conter segredos; o callback do provedor precisa validar estado.

Agente recebe spec, contexto do módulo de autenticação, regras do projeto e comandos de validação.

Harness executa os gates de validação, ou checagens obrigatórias: typecheck, lint, testes unitários, testes de integração, build, revisão de diff e checklist de segurança.

PR traz evidências: o que mudou, quais comandos rodaram, quais riscos permanecem e como fazer rollback.

Se algo falha, o time não só pede “tenta de novo”. Ele pergunta: faltou critério de aceite? Faltou teste? Faltou regra? Faltou ferramenta? A resposta vira melhoria no harness.

Como começar sem burocratizar

Você não precisa montar um laboratório de agentes antes de usar isso. Comece com uma mudança real, de risco médio, boa o suficiente para revelar onde o processo atual é frágil.

Comece pequeno:

1. Crie um template simples de spec para features com risco médio.
2. Escreva um AGENTS.md curto com comandos, arquitetura e regras essenciais.
3. Defina o “mínimo aceitável” antes de aceitar PR: diff revisado, lint, typecheck, testes e critérios de aceite.
4. Para cada erro recorrente do agente, escolha uma ação: melhorar spec, adicionar teste, atualizar regra ou criar script.
5. Revise o harness uma vez por sprint ou por entrega importante.

O objetivo não é burocracia. O objetivo é reduzir improviso onde improviso custa caro.