CLAUDE.md é um arquivo de texto em Markdown que o Claude Code, agente de código da Anthropic, usa como memória de instruções. Você escreve ali o que o agente deve saber sobre o projeto, e ele carrega o conteúdo ao iniciar uma sessão.
É o lugar certo para regras que você não quer repetir toda hora.
Como funciona
O arquivo costuma ficar na raiz do repositório. Ao abrir uma sessão naquela pasta, o Claude Code lê o conteúdo e o inclui no contexto. Para detalhes de locais e comportamento, consulte a documentação oficial do Claude Code, que pode mudar com o tempo.
O que vale a pena colocar:
- comandos de build, teste e lint;
- padrões de código e de nomes;
- arquitetura resumida do projeto;
- regras de segurança, como arquivos que não podem ser alterados;
- fluxo de trabalho esperado, como "rode os testes antes de concluir".
Mantenha o texto enxuto. Instruções longas e vagas consomem contexto e perdem efeito.
Exemplo prático
Seu projeto usa pnpm e um padrão de commits específico. Em vez de explicar isso toda vez:
# Projeto Loja
## Comandos
- Instalar: pnpm install
- Testar: pnpm test
## Regras
- Mensagens de commit em português, no imperativo.
- Não altere a pasta /migrations sem avisar.
- Componentes novos ficam em src/components.Daí em diante, cada sessão já começa alinhada com essas regras.
Para que serve
- Consistência: o agente segue as mesmas convenções sempre.
- Economia de tempo: você não repete o contexto do projeto.
- Segurança: define limites claros para o que o agente pode mexer.
- Colaboração: o arquivo vai para o Git e todo o time se beneficia.
Quem usa o Claude Code dentro de um squad de agentes, como no bridgecode, ganha em manter esse arquivo atualizado, pois todos os agentes compartilham o mesmo projeto.
Diferença entre CLAUDE.md e AGENTS.md
Os dois têm a mesma função: guiar agentes de código com instruções do projeto. O CLAUDE.md é o nome associado ao Claude Code. O AGENTS.md é um nome mais neutro, adotado por outras ferramentas. Confira qual arquivo sua ferramenta lê.
Um bom truque: quando o agente errar duas vezes na mesma coisa, adicione uma linha ao arquivo explicando o certo. Com o tempo, ele vira um guia sob medida do seu projeto.