Crie três arquivos de especificação antes de passar trabalho para o Claude Code ou Codex

Segunda-feira de manhã eu passava a mesma tarefa para o Claude Code: refatorar a camada de serviço de autenticação. Na terça, mesma tarefa, mesmo modelo, mesmo projeto. Na segunda, ele entregou a estrutura certa, tipos corretos, testes passando. Na terça, ignorou dois arquivos de dependência, sobrescreveu um helper que não devia tocar e gerou nomes de função que entravam em conflito com a convenção do projeto.

Passei semanas atribuindo isso à aleatoriedade do modelo. Depois percebi que o problema estava antes de qualquer prompt: eu não tinha definido a intenção de forma que o agente conseguisse usar.

O que acontece quando o agente não tem contexto estruturado

Agentes de IA não têm memória de sessão para sessão. Cada vez que você abre uma janela nova no Claude Code ou no Codex, o agente começa do zero. Sem estrutura de especificação, ele infere o contexto a partir do código que encontra, dos arquivos abertos e da linguagem do seu prompt.

Essa inferência funciona às vezes. Quando funciona, parece mágico. Quando falha, o agente toma decisões que fazem sentido local mas quebram algo que ele não sabia que existia.

O problema não é que o agente seja burro. Ele não tem acesso à intenção que ficou na sua cabeça. Sabe o que o código faz agora, não o que você está tentando que ele faça depois.

Pesquisadores da Universidade de Stanford publicaram em 2024 o que chamaram de “Curse of Instructions”: agentes de codificação performam muito abaixo do potencial quando recebem tarefas sem contexto estruturado de projeto. O estudo mediu que agentes com acesso a especificações de projeto bem formatadas completavam 40% mais tarefas corretamente na primeira tentativa, comparado com agentes operando apenas com prompts de linguagem natural. O que mais surpreendeu foi que a qualidade da especificação importava mais do que o tamanho do modelo usado.

A solução que encontrei depois de muita iteração são três camadas de arquivos que existem antes de qualquer sessão de agente começar.

Camada 1: CLAUDE.md como constituição do projeto

O CLAUDE.md não é um README. Ele é o documento que define as regras que nunca mudam, independente da tarefa.

O que vai nele: estrutura de pastas com o motivo de cada decisão, padrões de nomenclatura com exemplos reais, ferramentas de build e por que foram escolhidas, convenções de teste, e a lista curta de coisas que o agente não deve fazer. Esse último item é o mais importante porque agentes sem restrições explícitas tendem a otimizar pelo caminho mais rápido, que frequentemente quebra contratos implícitos da codebase.

Meu CLAUDE.md atual tem 47 linhas. Comecei com 200 e fui cortando tudo que o agente conseguia inferir do código por conta própria. Esse processo de corte foi mais útil do que a escrita inicial, porque me forçou a identificar o que realmente era implícito demais para ser descoberto sozinho.

Um detalhe prático: coloque o CLAUDE.md na raiz do projeto, não em subpastas. O agente o lê no início da sessão. Se ele está enterrado, há chance de ser ignorado.

Camada 2: SPEC.md para capturar o quê e o porquê, não o como

Quando uma tarefa tem mais de um arquivo envolvido ou afeta alguma fronteira de sistema, eu escrevo um SPEC.md antes de passar para o agente. Essa foi a mudança com maior impacto individual no meu fluxo de trabalho.

O SPEC.md tem cinco seções fixas:

Contexto descreve o estado atual em duas ou três frases. Não a história do projeto, só o ponto de partida relevante para esta tarefa.

Objetivo define o resultado esperado em termos de comportamento observável. Não “refatorar o serviço”, mas “depois desta mudança, a função getUser() deve retornar null em vez de lançar exceção quando o ID não existe”.

Restrições lista o que não pode mudar. Arquivos fora do escopo, APIs que outros times consomem, comportamentos que testes de integração dependem.

Perguntas em aberto é a seção que eu mais subutilizava no começo. Agora é onde documento incertezas reais antes de iniciar. Se não sei se o cache deve ser invalidado neste fluxo, escrevo isso. O agente frequentemente resolve a pergunta durante a implementação e eu aprendo algo que não sabia que não sabia.

Critérios de aceitação são três a cinco verificações concretas. Não “código limpo” ou “boa performance”, mas “os testes em auth.test.ts passam”, “o endpoint /api/users/:id retorna 200 para IDs válidos e 404 para inválidos”, “nenhuma importação nova foi adicionada em utils/shared.ts”.

Algo que acelerou muito a escrita de SPEC.md foi adotar o hábito de entrevistar o agente antes de implementar. Você abre uma sessão, descreve o problema e pergunta: “Que informações você precisaria para implementar isso sem fazer suposições?” As perguntas que o agente devolve são exatamente o que pertence ao SPEC.md. Passei de escrever specs em 20 minutos para escrever em 7, porque o agente me mostra os buracos antes de eu precisar encontrá-los.

Camada 3: plan.md como sequência de tarefas atômicas

Com CLAUDE.md e SPEC.md prontos, o plan.md é a decomposição da tarefa em passos que o agente pode executar um de cada vez.

A regra de tamanho que uso: cada tarefa deve levar entre dois e cinco minutos para um agente executar. Mais que isso e a tarefa provavelmente pode ser quebrada. Menos que isso e a granularidade está excessiva.

Cada item do plan.md inclui o arquivo exato a ser modificado (caminho completo), o comportamento esperado após a mudança, e o teste ou verificação que confirma que funcionou. Essa última parte é o que transforma o plan.md em um protocolo TDD estruturado: o agente sabe que precisa escrever o teste antes de escrever a implementação, porque o item do plano especifica “escreva o teste para X, depois escreva a implementação que passa esse teste”.

Quando o plan.md está bem escrito, sessões de agente se tornam previsíveis. Eu passo um item, o agente executa, verifico o critério, passo o próximo. A variabilidade que me custava horas de debugging caiu para retrabalho ocasional em um item específico, não em toda a tarefa.

Um problema real que tive: planos longos demais fazem o agente perder o fio. Descobri isso depois de um plan.md com 23 itens onde o agente começou a tomar atalhos por volta do item 15. Agora queino planos com mais de 10 itens em sessões separadas, cada uma com um SPEC.md próprio.

Sessões curtas são melhores do que sessões longas

Isso vai contra a intuição inicial. Parece mais eficiente passar tudo de uma vez e deixar o agente trabalhar. Na prática, sessões longas acumulam contexto que não é mais relevante, e o agente começa a tomar decisões com base em coisas que já foram resolvidas ou descartadas.

Eu divido o trabalho em sessões de 30 a 45 minutos com checkpoints explícitos. No final de cada sessão, documento o estado atual no SPEC.md (“a camada de repositório está pronta, próximo passo é a camada de serviço”). Isso cria continuidade sem depender da memória de sessão que não existe.

A divisão também me força a validar o que foi feito antes de continuar. Já peguei problemas no item 3 que teriam comprometido os itens 4 a 12 se eu tivesse continuado sem parar.

O modelo de maturidade que uso para avaliar onde estou

Descobri que a maioria dos times que trabalha com agentes de codificação se encontra em um de três níveis:

No Nível 1, as pessoas passam tarefas diretamente em linguagem natural, sem documentação de suporte. Os resultados variam muito. Quando funciona, parece sortudo. Quando falha, não há forma de diagnosticar por quê.

No Nível 2, existe um CLAUDE.md (ou equivalente) razoavelmente atualizado, mas as tarefas ainda são passadas sem specs. O agente tem contexto de projeto mas não tem intenção específica. Os resultados melhoram, mas a inconsistência ainda está lá.

No Nível 3, as três camadas existem e são mantidas como parte do fluxo de desenvolvimento. Specs são escritas antes de código. Planos são decompostos antes de serem passados. Sessões são curtas e têm checkpoints. Esse nível muda a relação com o agente de “ferramenta que às vezes funciona” para “colaborador que precisa de briefing adequado”.

A transição do Nível 1 para o Nível 2 leva um dia. Do Nível 2 para o Nível 3 leva algumas semanas de ajuste, porque o hábito de escrever specs antes de agir é difícil de construir. Ainda escorrego no Nível 2 quando estou com pressa, e invariavelmente pago o preço depois.

Por onde começar hoje

Se você passa tarefas para Claude Code ou Codex sem estrutura de especificação, comece com o CLAUDE.md. Uma hora de trabalho, 30 a 50 linhas, focada no que o agente não consegue inferir do código.

Depois, na próxima tarefa com mais de um arquivo envolvido, escreva o SPEC.md antes de abrir a sessão. Use o formato de cinco seções. Não precisa ser longo: duas a três frases por seção é suficiente para tarefas médias.

O plan.md vem naturalmente depois que você tem os dois primeiros. A decomposição em tarefas atômicas com caminhos de arquivo e critérios de verificação fica fácil quando o objetivo e as restrições já estão documentados.

O investimento de 15 a 20 minutos escrevendo especificação antes de uma sessão de agente me economiza consistentemente 40 a 90 minutos de debugging e retrabalho depois. Não é um número estimado: é o que meço desde que adotei esse fluxo em outubro de 2025.