# Crie três arquivos de especificação antes de passar trabalho para o Claude Code ou Codex > Author: Tony Lee > Published: 2026-03-12 > URL: https://tonylee.im/pt/blog/three-spec-files-before-ai-agent-coding/ > Reading time: 8 minutes > Language: pt > Tags: ai-agents, claude-code, context-engineering, developer-tools, spec-driven-development ## Canonical https://tonylee.im/pt/blog/three-spec-files-before-ai-agent-coding/ ## Rollout Alternates en: https://tonylee.im/en/blog/three-spec-files-before-ai-agent-coding/ ko: https://tonylee.im/ko/blog/three-spec-files-before-ai-agent-coding/ ja: https://tonylee.im/ja/blog/three-spec-files-before-ai-agent-coding/ zh-CN: https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ zh-TW: https://tonylee.im/zh-TW/blog/three-spec-files-before-ai-agent-coding/ ## Description Depois de quase um ano de desenvolvimento assistido por agentes de IA, descobri que arquivos de especificação estruturados resolviam o problema de inconsistência muito melhor do que qualquer técnica de prompt. ## Summary Crie três arquivos de especificação antes de passar trabalho para o Claude Code ou Codex is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - O que acontece quando o agente não tem contexto estruturado - Camada 1: CLAUDE.md como constituição do projeto - Camada 2: SPEC.md para capturar o quê e o porquê, não o como - Camada 3: plan.md como sequência de tarefas atômicas - Sessões curtas são melhores do que sessões longas - O modelo de maturidade que uso para avaliar onde estou - Por onde começar hoje ## Content 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. ## 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/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/pt/blog/codex-folder-structure-why-config-breaks/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/pt/blog/three-spec-files-before-ai-agent-coding/ ## 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.