Spec-driven development com Claude Code e Codex, do PRD ao merge

Tem um ponto em todo projeto tocado com IA onde a coisa vira. Nos primeiros dias você pede, o agente entrega, e parece mágica. Aí o projeto cresce, chega no quinto ou sexto arquivo, e começa aquilo: o agente refaz o que já estava pronto, esquece a decisão que vocês tomaram ontem, inventa uma estrutura nova toda sessão. A sensação é de que ele ficou burro, mas não ficou. O que mudou foi que o projeto passou do tamanho que cabe numa conversa.

O nome disso, quando você resolve, é spec-driven development. É o oposto de vibe coding, e não porque vibe coding seja errado, é porque vibe coding é uma fase. Serve muito bem pra descobrir o que você quer construir, e serve muito mal pra construir. Vou te mostrar o processo que eu uso todo dia com Claude Code e Codex, do PRD até o merge, com os arquivos que ficam no disco e os gates que eu não abro mão.

O que é spec-driven development na prática, sem o jargão?

Spec-driven development é parar de conversar com o agente e começar a dar documento pra ele. Simples assim. Em vez de a decisão viver no histórico de chat, que some quando você fecha a janela, ela vira arquivo versionado no repositório.

A diferença prática aparece no segundo dia. No vibe coding, você abre uma sessão nova e o agente não sabe nada, então você reexplica, e ele reconstrói o entendimento de um jeito ligeiramente diferente do de ontem. No spec-driven, você abre a sessão, ele lê os arquivos, e continua de onde parou. O contexto não mora na conversa, mora no projeto.

Tem um efeito colateral que eu não esperava quando comecei: os documentos ficam bons pra mim também. Quando eu volto num projeto depois de três semanas, eu leio o PRD e o DECISIONS.md antes de olhar código, exatamente como o agente faz.

Quais artefatos o projeto precisa ter no disco, e para que serve cada um?

Essa é a estrutura que eu chego hoje, depois de errar bastante pra chegar nela. Não é a única que funciona, é a que sobreviveu ao uso.

/docs
├── PRD.md              o que estamos construindo e por que
├── ARCHITECTURE.md     como as peças se encaixam
├── DATABASE.md         schema, relações, migrations
├── API.md              contratos de entrada e saída
├── SECURITY.md         o que é sensível e como é tratado
├── DECISIONS.md        o que já foi decidido e o que foi descartado
└── features/
    └── autenticacao/
        ├── SPEC.md       o comportamento esperado dessa feature
        ├── TASKS.md      as tasks atômicas pra chegar lá
        └── TEST-PLAN.md  como saber que ficou pronto
AGENTS.md               como o agente deve trabalhar neste repo
CLAUDE.md               o mesmo, na convenção do Claude Code

O que cada um resolve, em uma linha:

PRD.md responde “o que” e “por quê”. Sem ele o agente otimiza pra elegância técnica em vez de pro problema do usuário.

ARCHITECTURE.md responde “onde as coisas moram”. É o que impede o agente de criar uma pasta nova toda vez que precisa de um lugar pra botar um arquivo.

DECISIONS.md é o mais subestimado da lista. Ele guarda o que foi descartado e por quê. Sem isso, você vai reviver a mesma discussão a cada duas semanas, e o agente vai te propor de novo aquela abordagem que vocês já tinham rejeitado.

SPEC.md, TASKS.md e TEST-PLAN.md ficam por feature, não na raiz. Isso é de propósito: o agente que está mexendo em autenticação lê a pasta de autenticação, e não carrega o projeto inteiro pra fazer uma coisa pequena.

Qual é a diferença entre AGENTS.md e CLAUDE.md, e por que ter os dois?

São a mesma ideia com dois nomes, e isso é bobo, mas é a realidade hoje. O Claude Code lê CLAUDE.md, o Codex lê AGENTS.md. Se você só tem um dos dois, um dos agentes trabalha cego.

O que eu faço é manter os dois com o mesmo conteúdo essencial e uma seção específica em cada. O tronco comum é: qual é a stack, como rodar os testes, qual é a convenção de nome, o que nunca fazer neste repositório. A parte específica é o que cada ferramenta faz melhor.

Um detalhe que economiza dor de cabeça: esses arquivos precisam dizer o que não fazer, não só o que fazer. “Não crie migration nova, use a que já existe em /db/migrations” evita um tipo de estrago que “siga as boas práticas” não evita.

Qual é a ordem das fases, e por que pular uma custa caro?

O fluxo, do zero ao merge:

Ideia
  → Discovery (o que existe, o que já foi tentado)
  → PRD.md
  → ARCHITECTURE.md
  → AGENTS.md / CLAUDE.md
  → Epic
  → Tasks atômicas com acceptance criteria
  → worktree por raia
  → agente executa
  → o outro agente revisa
  → testes
  → quality gates
  → merge
  → atualiza a documentação

A fase que todo mundo pula é o Discovery, e é a que mais custa. Discovery é olhar o que já existe antes de mandar construir. Metade das vezes que eu vi agente produzir código redundante, a causa foi essa: ninguém disse pra ele que aquilo já estava resolvido em outro canto do repositório.

A segunda mais pulada é atualizar a documentação depois do merge. Parece burocracia, só que é o que mantém o ciclo funcionando. Documento desatualizado é pior que documento inexistente, porque o agente confia nele.

Como quebrar epic em tasks atômicas com acceptance criteria?

Task boa pra agente tem três propriedades: cabe numa sessão, não depende de outra task rodando ao mesmo tempo, e tem um critério objetivo de pronto.

O teste que eu uso é simples: se eu não consigo escrever a frase “está pronto quando ___” sem usar “funcionar bem” ou “estar correto”, a task ainda está grande demais ou vaga demais.

Um exemplo de task ruim: “implementar autenticação”. Um exemplo de task boa: “o endpoint POST /login devolve 200 com um JWT válido de 15 minutos quando as credenciais batem, e 401 sem corpo quando não batem, com teste cobrindo os dois casos”.

A segunda é chata de escrever, eu sei. Só que é ela que permite você aceitar ou rejeitar o trabalho do agente em dez segundos em vez de ler o diff inteiro.

Como manter Claude Code e Codex no mesmo repositório sem conflito?

Aqui o que resolve é git worktree. Cada agente trabalha numa cópia própria do repositório, na sua própria branch, e eles nunca escrevem no mesmo arquivo ao mesmo tempo.

O erro que eu cometi no começo foi achar que dava pra rodar os dois na mesma pasta se as tasks fossem diferentes. Não dá. Um roda um comando que mexe em node_modules, o outro está no meio de um build, e você perde os dois trabalhos.

A regra que eu sigo hoje é uma raia por worktree, e as raias são desenhadas na hora de quebrar as tasks, não depois. Se duas tasks tocam o mesmo arquivo, elas não são paralelas, ponto. Vão em sequência mesmo que dê vontade de acelerar.

Que quality gates rodar antes de aceitar o diff do agente?

Gate é o que roda sozinho e diz sim ou não, sem eu precisar julgar. A minha lista mínima:

Typecheck e lint. Óbvio, e mesmo assim é onde mais pega coisa. Agente escreve código que parece certo e não compila com mais frequência do que se imagina.

Testes, incluindo o que a task prometeu. Se o acceptance criteria falava em 401 sem corpo, tem que existir teste do 401 sem corpo.

Diff de escopo. O agente mexeu só nos arquivos que a task previa? Quando ele encosta em arquivo fora do escopo, quase sempre é sinal de que entendeu outra coisa.

Revisão pelo outro agente. Esse é o que mais rende. Eu mando o Codex revisar o que o Claude Code escreveu, e vice-versa. Eles erram de jeitos diferentes, então um pega o que o outro deixou passar. Não substitui a minha leitura, reduz o quanto eu preciso ler.

O que é context engineering, e por que ele importa mais que o prompt?

Context engineering é decidir o que entra na janela do agente e o que fica de fora. Prompt é o que você pede, contexto é o que ele sabe na hora de atender.

A intuição errada é achar que mais contexto é melhor. Não é. Contexto demais dilui: o agente lê trinta arquivos, dois deles são relevantes, e a atenção dele se espalha nos outros vinte e oito. Eu já vi resultado piorar por eu ter dado documentação demais.

O que funciona é contexto curado. A pasta da feature, o ARCHITECTURE.md, o DECISIONS.md, e só. Se ele precisar de mais, ele pede, e aí você dá o pedaço específico.

É por isso que a estrutura de arquivos lá de cima importa tanto. Ela não é organização por estética, é o mecanismo que permite entregar pouco e certo em vez de muito e vago.

Quando essa disciplina toda é exagero?

Sendo honesto: na maior parte das vezes que você abre o editor.

Script de uma vez, protótipo pra validar ideia, ajuste de CSS, automação pessoal que só você usa. Nada disso precisa de PRD. Botar processo ali é desperdiçar tempo e dar razão pra quem acha que isso é burocracia.

O corte, na minha experiência, é mais ou menos assim: se o projeto vai durar mais de uma semana, se mais de uma pessoa vai encostar nele, ou se ele vai pra produção com dado de gente de verdade, aí compensa. Abaixo disso, vibe coding é a ferramenta certa.

A parte difícil é perceber a hora da virada, porque ela não avisa. Ela se manifesta como aquele cansaço de reexplicar a mesma coisa pro agente pela terceira vez. Quando você sentir isso, o projeto já passou do ponto faz uns dias.

Por onde começar amanhã?

Não monte a estrutura inteira de uma vez, você vai abandonar. Comece por dois arquivos: DECISIONS.md e AGENTS.md (mais o CLAUDE.md com o mesmo conteúdo).

O DECISIONS.md porque é o que dá retorno na primeira semana, você para de rediscutir. O AGENTS.md porque é o que faz o agente parar de inventar convenção.

PRD e a árvore de features você acrescenta quando doer a falta. E vai doer, na hora em que uma feature ficar grande o suficiente pra você não conseguir descrever numa mensagem.