Crie três arquivos de especificação antes de usar Claude Code e Codex

Depois de quase um ano usando agentes de codificação com IA todo dia, o que mais me incomodava não era código alucinado nem APIs erradas. Era a inconsistência. A mesma tarefa, formulada de forma ligeiramente diferente, produzia um resultado limpo em um dia e uma bagunça no seguinte. Sessões longas pioravam tudo: o agente esquecia acordos feitos vinte mensagens antes.

A causa era estrutural. Eu não tinha nenhum framework para comunicar intenção ao agente entre sessões. Cada conversa começava do zero e derivava em direções imprevisíveis.

Três camadas que mudaram o resultado

Dividir as instruções em três arquivos, cada um com um papel distinto, resolveu o problema de inconsistência quase que imediatamente.

Camada 1, CLAUDE.md carrega automaticamente a cada sessão. Contém as constantes do projeto: comandos de build, versões do stack, estrutura de pastas, convenções de código e limites comportamentais (sempre fazer X, perguntar antes de Y, nunca fazer Z).

Camada 2, SPEC.md captura o quê e o porquê de uma funcionalidade específica. Propósito, requisitos, critérios de sucesso, restrições técnicas e limites de escopo. Nada sobre detalhes de implementação.

Camada 3, plan.md decompõe uma spec em tarefas executáveis de dois a cinco minutos, com caminhos de arquivo explícitos, ordem TDD e pontos de commit.

Por que colocar tudo em um único arquivo não funciona

A pesquisa sobre seguimento de instruções em LLMs chama isso de “Maldição das Instruções”. À medida que o número de diretivas em um único contexto cresce, a conformidade com cada diretiva individual cai drasticamente. Verifiquei isso diretamente: um arquivo único com regras do projeto, specs de funcionalidades e listas de tarefas fazia o agente ignorar cerca de metade das instruções perto do final do documento.

Separar por papel resolveu. O agente lê regras universais da camada 1, intenção da funcionalidade da camada 2, e passos de execução da camada 3. Cada arquivo fica curto o suficiente para o modelo dedicar atenção completa a ele.

CLAUDE.md funciona melhor quando mantido enxuto

Como esse arquivo carrega a cada sessão, ele precisa conter apenas o que se aplica universalmente. Comandos de build, versões do stack, organização de pastas, convenções de nomenclatura. Adicione um limite em três níveis: coisas para sempre fazer, coisas sobre as quais perguntar primeiro, coisas para nunca fazer.

A abordagem que funcionou melhor foi começar com o mínimo e adicionar regras de forma incremental sempre que eu percebia o agente repetindo um erro. Tentar escrever um CLAUDE.md completo de uma vez levava a um arquivo inchado que disparava a mesma queda de conformidade que eu estava tentando evitar.

Algumas armadilhas específicas: não coloque chaves de API nem trechos de código aqui porque ficam obsoletos rápido. Não duplique regras que o seu linter já aplica. E mova qualquer coisa específica de uma única funcionalidade para a camada 2.

Arquivos de spec se concentram no quê e no porquê, deixando o como para o agente

A diferença em relação a um PRD tradicional é que essas specs são estruturadas para consumo pelo agente. Cinco seções são suficientes: propósito, requisitos, critérios de sucesso, restrições técnicas e limites de escopo.

Deixe as decisões de implementação para o agente. Ele consegue analisar o código existente e escolher a abordagem certa. Quando tentei ditar o como, o agente ou seguia às cegas entrando em conflito com os padrões existentes, ou ignorava completamente.

Uma alternativa a escrever specs manualmente: peça para o agente te entrevistar. Defina duas regras: uma pergunta por vez e múltipla escolha sempre que possível. As specs resultantes tinham menos lacunas do que as que eu escrevia do zero.

Salve specs concluídas em docs/specs/YYYY-MM-DD-topico.md e faça commit no Git. Isso dá ao agente acesso ao histórico de specs via git diff, e fornece aos revisores um registro da intenção por trás das mudanças de código.

Separação de sessões é a prática mais ignorada

Brainstorming e perguntas e respostas durante a escrita de uma spec consomem uma parte significativa da janela de contexto. Pular direto para a implementação na mesma sessão faz o agente ir perdendo acesso ao contexto anterior gradualmente.

Reestruturei em três sessões: a sessão 1 produz SPEC.md, a sessão 2 cria plan.md, a sessão 3 em diante executa tarefas uma a uma. A melhora em precisão foi perceptível dentro da primeira semana.

Três hábitos que fizeram isso funcionar: escrever caminhos de arquivo explícitos em cada tarefa para o agente parar de adivinhar, fixar a ordem TDD (teste primeiro, implementação, verificação, commit) no plan.md, e iniciar uma nova sessão sempre que o uso do contexto chegar em torno de 50%.

O modelo de maturidade aponta para a spec como fonte de verdade

O time de Martin Fowler definiu recentemente um modelo de maturidade para desenvolvimento de software baseado em agentes com três níveis. Nível 1: escrever uma spec, implementar, descartar a spec. Nível 2: manter a spec como documento vivo junto ao código. Nível 3: a spec se torna a única fonte de verdade, e o código é um artefato gerado.

A maioria dos times e indivíduos que conheço ainda não chegou ao nível 1. Eles mandam prompts avulsos na esperança de que dê certo, e quando falha não há como diagnosticar o motivo.

Passar do nível 1 para o nível 2 exige um único hábito: fazer commit dos arquivos de spec no Git. Passar do nível 2 para o nível 3 significa atualizar a spec antes de modificar o código. O menor passo que você pode dar hoje é criar um CLAUDE.md para seu projeto e escrever um SPEC.md antes da sua próxima funcionalidade.