# Crie três arquivos de especificação antes de usar Claude Code e Codex > Author: Tony Lee > Published: 2026-03-19 > URL: https://tonylee.im/pt/blog/create-three-spec-files-before-using-claude-code-codex/ > Reading time: 5 minutes > Language: pt > Tags: ai, claude-code, codex, ai-agents, spec-driven-development, developer-tools ## Canonical https://tonylee.im/pt/blog/create-three-spec-files-before-using-claude-code-codex/ ## Rollout Alternates en: https://tonylee.im/en/blog/create-three-spec-files-before-using-claude-code-codex/ ko: https://tonylee.im/ko/blog/create-three-spec-files-before-using-claude-code-codex/ ja: https://tonylee.im/ja/blog/create-three-spec-files-before-using-claude-code-codex/ zh-CN: https://tonylee.im/zh-CN/blog/create-three-spec-files-before-using-claude-code-codex/ zh-TW: https://tonylee.im/zh-TW/blog/create-three-spec-files-before-using-claude-code-codex/ ## Description Passei um ano tendo resultados erráticos com Claude Code e Codex. Três arquivos de especificação, cada um com um papel distinto, resolveram o problema. ## Summary Crie três arquivos de especificação antes de usar Claude Code e Codex is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Três camadas que mudaram o resultado - Por que colocar tudo em um único arquivo não funciona - CLAUDE.md funciona melhor quando mantido enxuto - Arquivos de spec se concentram no quê e no porquê, deixando o como para o agente - Separação de sessões é a prática mais ignorada - O modelo de maturidade aponta para a spec como fonte de verdade ## Content 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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/pt/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/pt/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/pt/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/pt/blog/create-three-spec-files-before-using-claude-code-codex/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/pt/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.