Spec-Driven Development: o ciclo SDD → RPI → Harness

Quem trabalhou numa fábrica japonesa nos anos 80 reconhece o padrão: você não começa a montar o carro sem o procedimento. O procedimento é elaborado, debatido, simulado, revisado. Quando chega ao chão de fábrica, montar é mecânico, porque a inteligência está no procedimento, não no trabalhador.

O Sistema Toyota de Produção¹ transformou isso em método. Quarenta anos depois, a mesma lógica reaparece na engenharia de software com IA. E a piada é que resistíamos porque “spec é cerimônia”. Spoiler: a spec é justamente o que deixa o resto barato.

Este post descreve o ciclo que tenho rodado, que chamo de SDD → RPI → Harness, e por que ele faz a IA em paralelo funcionar.

SDD: a spec como documento canônico

Spec-Driven Development é simples na ideia: você não pede ao agente de IA que escreva código. Pede que escreva a spec do código: o que o código vai fazer, a entrada, a saída, os casos de borda, as decisões de arquitetura e o porquê.

A spec é texto. Markdown. Versionada no Git, no mesmo repositório do código. Revisada por humanos (ou por outro agente de IA, no papel de crítico). Depois de aprovada, vira o documento canônico de tudo o que vem depois.

A spec não é um requisito vago como “implementar autenticação”. É algo assim:

# Spec: auth/email-magic-link

## Goal
Allow passwordless login via a single-use link sent by email.

## Behavior
1. POST /auth/request-link {email} → generates token, sends email.
2. GET /auth/verify?token=X → validates, creates session, redirects.
3. Token expires in 15min, single-use, idempotent on GET (clicking 2x doesn't log in 2x).

## Constraints
- Token generated via Web Crypto, 32 random bytes, base64url.
- Storage: Redis with a 15min TTL, key = sha256(token).
- Email via Resend; template in src/emails/magic-link.tsx.

## Out of scope
- Password recovery (there's no password).
- 2FA (separate spec).

## Acceptance criteria
- [ ] Link delivered in < 30s for 99% of cases.
- [ ] Clicking an expired link returns 410 Gone.
- [ ] The same email can have at most 3 active links.

Dá para ler isso e prever o que o código vai fazer. Mais que isso: o agente que vai implementar consegue ler e produzir código que faz exatamente isso, sem adivinhar.

RPI: o plano reverso

Reverse Plan Implementation é o passo intermediário entre a spec e o código. O agente que vai implementar, diferente do que escreveu a spec, lê a spec e produz um plano de implementação. Uma lista de tarefas pequenas, cada uma com:

• Arquivos a criar ou modificar.
• Código suficiente para reproduzir a tarefa sem ler o resto.
• Um critério de aceite específico (normalmente um teste).

O plano é revisado antes de qualquer código ser escrito. Se o plano está errado, é barato corrigir. Se está certo, executar é mecânico.

A inversão importante aqui: o plano não sai da mesma cabeça que escreveu a spec. É outro agente. Isso quebra duas coisas:

1. Viés do autor: o agente que escreveu a spec sabe demais sobre as próprias decisões. Não vai pegar as ambiguidades. Um leitor novo pega.
2. Deriva de contexto: se o mesmo agente escreve spec e plano, o plano tende a “tapar os buracos da spec” sem registrar. Um plano novo expõe o que a spec não disse.

Harness: a malha de validação

Harness é a peça que torna o ciclo seguro. É o conjunto de testes (automatizados, mas também checagens de qualidade, lint, type check, build) que precisa passar antes de uma mudança ser considerada pronta.

No SDD, o harness é escrito junto com a spec. Os critérios de aceite da spec viram, mecanicamente, os testes do harness. Quando o agente de implementação termina, o harness roda. Passou, a tarefa está pronta. Falhou, o agente vê a falha e itera.

O ponto crucial: o harness é o árbitro objetivo. Não é o agente decidindo se acertou. É um sistema externo e determinístico que diz sim ou não.

Sem harness, IA é teatro: o agente diz “implementei e funciona” e você acredita. Com harness, IA é engenharia: o agente diz “implementado”, o harness diz “passa”, e você confia no harness.

Por que esse ciclo paraleliza

Fui atrás dessa estrutura por um motivo prático: queria rodar 5 agentes em paralelo sem um pisar no outro. Com IA em série (um agente fazendo uma coisa por vez), dá para improvisar. Com IA em paralelo, a falta de spec é fatal.

Cada agente, em paralelo, lê a sua spec. Implementa. O harness valida. O harness é o único que dá o veredito. Não há revisão humana travando o pipeline: a revisão humana aconteceu na revisão da spec. O código é só a tradução mecânica.

Isso não é ficção científica. É como a Ford rodava a linha de montagem em 1913. O gênio não estava no trabalhador, estava na engenharia da linha.

Onde a Anthropic entra nessa história

A documentação de subagentes do Claude Code descreve uma versão desse pipeline: agentes especializados (planejador, implementador, revisor) que cooperam em ciclo. O texto da Anthropic sobre sistemas multiagente mostra resultados em bases de código reais. A Cognition publicou as próprias notas técnicas sobre a arquitetura do Devin, com lógica parecida.

Tudo aponta na mesma direção: IA boa em escrever código não é IA que escreve código bem. É IA que entende a spec. O resto é mecânica.

Para quem quer começar

Três passos práticos que funcionam até em projeto pequeno:

1. Antes de pedir código, peça a spec. Em Markdown. Curta. Com uma seção de critérios de aceite.
2. Antes de implementar, peça o plano. A outro agente, em outra sessão. Ou a você mesmo, lendo a spec com olhos de leitor.
3. Antes de aceitar, rode o harness. Nem que seja só npm test && npm run build. O que importa é ter um árbitro objetivo.

Funciona num projeto de uma pessoa. Funciona num de 50. A única diferença é o número de specs simultâneas.