CLAUDE.md e AGENTS.md: o arquivo que ensina o agente sobre o seu projeto

Todo agente de código começa uma sessão sem saber nada sobre o seu projeto. Ele lê arquivos, roda comandos e deduz, mas não tem como deduzir o que não está escrito em lugar nenhum: a regra que a equipe combinou de boca, o comando que só funciona com uma flag, o erro de produção que já aconteceu uma vez e ninguém quer repetir. O arquivo de instruções do projeto existe para isso. No Claude Code ele se chama CLAUDE.md; no padrão aberto adotado por várias ferramentas, AGENTS.md. O nome muda, a ideia é a mesma: um texto na raiz do repositório que o agente lê no começo de toda sessão.

Este artigo faz parte da trilha Aprenda IA construindo software e usa como exemplo o arquivo real que orienta o desenvolvimento deste site. Os trechos citados estão no repositório e foram escritos à medida que os problemas apareceram.

O que esse arquivo resolve

Sem instrução, o agente repete os mesmos erros a cada sessão. Ele não lembra que o build do frontend precisa de um passo de pré-renderização, não sabe que existe uma regra sobre quem faz commit, não sabe que uma rota nova precisa ser registrada em cinco lugares. Você corrige, a sessão termina, e na próxima o erro volta. O arquivo de instruções é a memória do projeto que sobrevive entre sessões e entre pessoas: serve ao agente e serve ao desenvolvedor que chega depois.

Ele não substitui documentação de arquitetura nem README. A diferença é o leitor: o README explica o projeto para um humano que vai decidir se usa; o arquivo de instruções diz a quem vai mexer no código como trabalhar sem quebrar nada.

O que colocar

1. Os comandos que provam que o trabalho está pronto

O primeiro bloco do arquivo deste site lista os comandos e, principalmente, qual deles é o portão de qualidade. Um trecho:

npm run check   # build:frontend + test:backend
                # rodar antes de considerar uma tarefa concluída

E logo depois, uma frase que evita meia hora de busca: não existe suíte de teste no frontend; o portão é a checagem de tipos mais o validador de links internos. Sem essa linha, um agente bem-intencionado procura testes que não existem ou cria um framework de testes que ninguém pediu.

2. A arquitetura que não está óbvia no código

O agente consegue ler a estrutura de pastas. O que ele não consegue ver é a decisão por trás dela. Aqui, os artigos em português vêm do banco de dados, inseridos por migration, e as páginas em inglês são componentes estáticos mantidos em código. Quem olha só um dos lados conclui que o outro funciona igual. Uma frase no arquivo resolve: são pipelines separados, e criar conteúdo nos dois idiomas exige mexer nos dois.

3. As armadilhas, com o sintoma

Esta é a seção mais valiosa e a que mais cresce com o tempo. O exemplo mais claro deste projeto é a regra dos cinco registros de uma rota nova:

Rota nova só funciona ponta a ponta depois de cinco edições:
1. App.tsx (a rota)
2. i18n/routes.ts (o par PT e EN)
3. scripts/prerender.mjs
4. allowlist do nginx.conf  -- sem isso a rota dá 404 em produção
5. findSitemapPaths() no backend

Essa regra nasceu de um 404 em produção. A página funcionava no ambiente de desenvolvimento, passava em todas as checagens, e só quebrava no servidor, porque o nginx tem uma lista de rotas permitidas. O detalhe importante está no texto do arquivo: ele descreve o sintoma ao lado da regra. Quem vê um 404 em produção e procura por 404 no arquivo encontra a causa.

Outro exemplo do mesmo arquivo: nenhuma página em inglês entra no sitemap, por decisão explícita. Isso parece bug para quem confere uma rota nova e vê só a versão em português no XML. O arquivo avisa que não é, e evita que alguém corrija o que não está quebrado.

4. As regras de trabalho

Regras que não têm a ver com código, mas com o processo. Neste projeto, uma delas é curta e inegociável: commit e push são feitos exclusivamente pelo dono do repositório, e o agente não faz nenhum dos dois sem pedido explícito. Outra: toda documentação nova vai para a pasta documentacao/. Sem isso escrito, cada sessão inventa um lugar diferente.

O que não colocar

• Segredos. Nada de chave de API, senha ou token. O arquivo vai para o repositório e é lido por ferramentas externas. Diga onde o segredo fica (variável de ambiente, cofre), nunca o valor.
• O que o código já diz. Lista de arquivos, assinatura de funções, cópia do schema. Fica desatualizado na primeira refatoração e passa a mentir.
• Histórico. Quem mudou o quê e quando já está no git. O arquivo guarda a regra que ficou, não a história de como se chegou nela.
• Instruções vagas. Escreva código limpo não muda comportamento nenhum. Rode npm run check antes de dizer que terminou muda.

Como o arquivo cresce

O melhor momento para escrever uma linha no arquivo é logo depois de um erro. O fluxo que funciona aqui é simples: algo quebrou, a causa foi encontrada, e a pergunta seguinte é se esse erro pode acontecer de novo com outra pessoa ou outra sessão. Se pode, vira uma linha, com o sintoma e a regra. A regra dos cinco registros, a nota sobre o sitemap e o aviso sobre a ausência de testes no frontend nasceram assim.

Também vale o caminho inverso: quando uma regra deixa de fazer sentido, ela sai. Um arquivo de instruções com regra morta ensina o agente a obedecer o que ninguém mais quer.

Um arquivo por projeto, e às vezes mais de um

Em um repositório com partes muito diferentes, como backend e app mobile, faz sentido ter um arquivo na raiz com o que vale para tudo e arquivos menores nas pastas com o que vale só ali. O app Diário do Professor, contado no artigo Agente de código na prática, tem o próprio arquivo com os princípios do produto (funcionar offline, sem conta, sem login) e as lições específicas de publicação na Google Play.

Erros comuns

• Escrever o arquivo uma vez, no início, e nunca mais tocar. Ele precisa crescer com o projeto.
• Transformar o arquivo em manual de cem páginas. O agente lê tudo em toda sessão; texto longo demais ocupa contexto que faria falta na tarefa.
• Escrever regra sem motivo. Uma regra com o porquê permite que o agente e o colega julguem os casos que a regra não previu.
• Duplicar a mesma instrução em vários lugares, que depois divergem.

Checklist para começar o seu

• Liste os comandos de build, teste e execução, e diga qual deles é o portão de qualidade.
• Escreva em duas ou três frases a decisão de arquitetura que mais confunde quem chega.
• Registre as regras de processo: quem faz commit, onde ficam os documentos, o que precisa de aprovação.
• Crie uma seção de armadilhas, mesmo vazia, e preencha a cada erro que se repetir.
• Releia a cada poucos meses e apague o que morreu.

Para continuar

O arquivo de instruções é a versão permanente de uma boa especificação. Para a parte de pedir uma tarefa bem descrita, veja como usar IA para transformar uma ideia em especificação técnica. Para o que fazer com o código que o agente entrega, veja como revisar código gerado por IA antes do deploy. E para documentar o restante do sistema, como usar IA para documentar processos e sistemas.