CLAUDE.md e AGENTS.md: o que são, o que escrever neles e por que o agente ignora regras

O que são CLAUDE.md e AGENTS.md

São arquivos Markdown comuns na raiz do repositório, que o agente carrega automaticamente no contexto no início da sessão. Por meio deles você comunica o que o agente não consegue deduzir sozinho pelo código: como subir o ambiente, quais comandos usar para verificar o trabalho, quais regras do projeto não se discutem e onde ficam os documentos detalhados.

CLAUDE.md é o arquivo que o Claude Code lê. AGENTS.md é um formato aberto com a mesma ideia, suportado por muitos agentes de programação. Se a equipe usa mais de um agente, vale manter o conteúdo principal em AGENTS.md e fazer o CLAUDE.md apontar para ele. O Claude Code permite importar outro arquivo com o símbolo @:

# CLAUDE.md
@AGENTS.md

Assim, as regras ficam em um só lugar e não divergem entre dois arquivos.

Como o agente lê esses arquivos

O conteúdo do arquivo de instruções entra na janela de contexto do modelo junto com o prompt de sistema e permanece ali durante toda a sessão. Daí decorrem três consequências importantes.

• Cada linha ocupa espaço no contexto.O arquivo é lido por inteiro a cada execução, mesmo que a tarefa atual precise de um décimo dele.
• É texto, não uma regra executável.O modelo leva o conteúdo em consideração como qualquer outro contexto, e nada garante 100% de obediência. Proibições rígidas precisam de mecanismos de apoio: verificações, hooks e permissões de acesso.
• Os arquivos podem ser aninhados.O Claude Code carrega o CLAUDE.md da raiz do projeto e o da pasta do usuário ~/.claude/; arquivos em subpastas são carregados quando o agente trabalha com arquivos dessas pastas. Assim, as regras de um módulo podem ficar ao lado do próprio módulo.

O que escrever no CLAUDE.md e no AGENTS.md

Um bom arquivo de instruções é um mapa, não um livro-texto. Ele responde às perguntas que o agente faria a um colega experiente no primeiro dia.

1. Como montar e verificar o projeto

É a seção mais valiosa: os comandos concretos que o agente é obrigado a rodar antes de dizer «pronto». Testes, linter, checagem de tipos, subir o ambiente. Sem eles, o agente verifica o próprio trabalho «a olho».

2. Restrições rígidas

Uma lista curta do que não pode ser violado em hipótese alguma: invariantes de segurança e de dados. Escreva como invariantes, e não como instruções de implementação: «todas as consultas SQL são parametrizadas» é melhor do que «use tal função naquele arquivo».

3. Mapa do projeto

Onde está cada coisa: algumas linhas sobre a estrutura de pastas e onde procurar detalhes. Para cada tema grande, um link para um documento próprio, que o agente abre apenas quando for trabalhar nele.

4. Onde fica o estado do trabalho

Para onde olhar para retomar do ponto em que a sessão anterior parou: arquivo de plano, diário de progresso, backlog. Isso trata a «amnésia» do agente entre sessões.

O que não escrever

• O que o agente lê no código.A lista de dependências está em package.json ou pyproject.toml, e a estrutura das classes está no próprio código.
• Conselhos genéricos.«Escreva código limpo» ou «seja cuidadoso» não mudam o comportamento e só ocupam espaço.
• Histórico do projeto e anotações pontuais.«Em março migramos do MySQL 5.7» não ajuda a tarefa atual.
• Instruções detalhadas para tarefas raras.O procedimento de deploy ou de migração de dados é necessário uma vez por semana; mova-o para um documento separado ou para uma skill.
• Segredos.O arquivo fica no repositório e vai inteiro para o modelo. Tokens e senhas ficam apenas em variáveis de ambiente.

Por que o agente ignora uma regra escrita no arquivo

A história costuma ser esta: o agente erra, alguém acrescenta uma regra. Ele erra de novo, acrescenta-se outra. Depois de alguns meses, o arquivo tem centenas de linhas, e uma regra de segurança crítica é violada como se não existisse. Normalmente há quatro causas, e elas atuam ao mesmo tempo.

Arquivo inchado

Um arquivo de 600 linhas equivale a algo como 10 a 20 mil tokens. A janela de contexto parece enorme, mas o código, a saída dos comandos e o histórico da conversa disputam o mesmo espaço. Quanto mais as instruções ocupam, menos atenção cada regra recebe e menos espaço sobra para a tarefa.

Regra no meio do texto

Modelos de linguagem usam pior as informações do meio de um texto longo do que as do início e do fim. A regra na linha 300 de 600 cai justamente na posição mais fraca.

Ausência de prioridades

Uma proibição inegociável e uma observação passageira sobre estilo estão escritas do mesmo jeito: uma linha em uma lista. O agente não tem como saber o que é mais importante. Se há três regras de estilo que se contradizem, o comportamento vira aleatório de uma execução para outra.

Apodrecimento

Acrescentar uma regra é de graça, mas remover dá medo: «e se algo depende dela?». Por isso o arquivo cresce monotonamente e a proporção de linhas úteis cai. Dá para medir isso pela relação sinal/ruído: quantas linhas são de fato necessárias para uma tarefa típica e quantas não são.

Como corrigir: um roteador em vez de um texto enorme

Corrigir uma única causa não basta: se você encurtar o arquivo sem organizá-lo, as regras continuam misturadas. Funciona um conjunto de medidas.

1. Transforme o arquivo de entrada em um roteador.Entre 50 e 150 linhas: comandos de verificação, restrições rígidas, mapa do projeto e links para documentos temáticos.
2. Mova os temas para arquivos separados.Por exemplo, docs/agents/deploy.md e docs/agents/database.md. O agente os abre quando precisa. No Claude Code, skills são ótimas para procedimentos repetitivos, pois só são carregadas quando necessárias.
3. Coloque o crítico no topo.As restrições rígidas no início do arquivo, em um bloco curto marcado com MUST.
4. Elimine contradições.Para cada tema, uma única regra. Se houver exceção, escreva-a ao lado da regra.
5. Reforce a regra com um mecanismo.Se a violação é inaceitável, o texto não basta. É preciso uma verificação que pegue a infração: linter, teste, hook de pre-commit, hook do agente ou uma restrição de permissão de acesso.
6. Revise com regularidade.Defina um limite de linhas e, a cada acréscimo, pergunte o que pode ser removido ou movido para outro lugar.

Regra ou verificação?

Exemplo de AGENTS.md enxuto

# AGENTS.md — backend de pagamentos (FastAPI, PostgreSQL)

## MUST — não violar
- Valores monetários são int, em centavos; nunca float
- SQL apenas parametrizado, sem f-strings
- Não alterar migrations já aplicadas; só adicionar novas
- Segredos são lidos apenas de variáveis de ambiente

## Verificação antes de dizer «pronto»
docker compose up -d     # ambiente
make lint                # ruff + mypy
make test                # pytest
make e2e                 # cenário de compra
Testes unitários verdes sem e2e não significam «pronto».

## Mapa
- app/payments/   — cálculo de valores, descontos, webhooks do provedor
- app/api/        — endpoints HTTP
- tests/e2e/      — cenários do usuário
Detalhes: docs/agents/architecture.md, docs/agents/database.md

## Estado do trabalho
- PLAN.md      — objetivo atual, critérios de conclusão, próximo passo
- PROGRESS.md  — o que foi feito e como foi verificado, becos sem saída
- BACKLOG.md   — o que foi notado «de passagem»: anotar aqui, não corrigir agora

No fim da sessão, atualize PROGRESS.md e o próximo passo no PLAN.md.

Repare no que não está lá: não há lista de bibliotecas, dicas de estilo nem histórico do projeto. Ou isso se deduz do código, ou é garantido por verificações, ou está em documentos temáticos.

Amnésia entre sessões: arquivo de instruções mais arquivo de plano

O arquivo de instruções descreve como trabalhar no projeto, mas não o que está acontecendo agora. Para isso é preciso um arquivo de estado separado, que o agente lê no início e atualiza no fim da sessão. Nele ficam: o objetivo, o que foi feito com a indicação de como foi verificado, as decisões com seus motivos, as alternativas descartadas e um único próximo passo. A verificação da qualidade é simples: abra uma sessão nova, escreva «continue» e veja se o agente começa um trabalho útil sem fazer perguntas.

Não misture os dois arquivos. As instruções mudam raramente e valem para todas as tarefas. O plano muda a cada sessão e vale só para a tarefa atual. Se você misturar, o arquivo de instruções logo se enche de notas desatualizadas.

Como saber se o arquivo funciona

O arquivo de instruções também precisa ser testado. Escolha algumas tarefas típicas, como correção de bug, pequena funcionalidade e refatoração, e observe o que o agente faz sem dicas: roda os comandos certos? Abre o documento temático adequado? Respeita as restrições rígidas? Se uma regra for violada, pergunte primeiro: ela está visível? Há outra regra que a contradiz? Dá para trocá-la por uma verificação automática? Acrescentar uma linha é o último recurso.

Conclusão

CLAUDE.md e AGENTS.md são a porta de entrada do agente no projeto. Eles funcionam quando continuam sendo um mapa curto: comandos de verificação, restrições rígidas no topo, links para os detalhes e para o arquivo de plano. Se uma regra é ignorada, o motivo quase sempre é um arquivo inchado e sem estrutura, e as regras realmente críticas precisam ser reforçadas por verificações e hooks. Como montar as instruções e o estado do agente é explicado na prática no curso de harness engineering.