Claude CodeAtualizado em 29 de setembro de 20265 min de leitura

CLAUDE.md: como dar instruções permanentes ao Claude Code

Todo projeto tem coisas que você cansa de repetir: como rodar os testes, onde ficam as rotas, qual padrão de código seguir. O CLAUDE.md é o arquivo onde você escreve isso uma vez só. O Claude Code lê esse arquivo no começo de toda sessão e segue as instruções sem você precisar pedir de novo.

Este guia mostra onde colocar o CLAUDE.md, o que escrever nele e como organizar as instruções quando o projeto cresce.

O que colocar no CLAUDE.md

Escreva ali o que você explicaria para uma pessoa nova no time:

• Comandos: como instalar, rodar, testar e fazer o lint.
• Estrutura: onde fica cada parte do código.
• Convenções: padrão de nomes, indentação, idioma dos comentários.
• Regras: o que sempre fazer e o que nunca fazer.

Uma boa regra prática: se o Claude errou a mesma coisa duas vezes, ou se você digitou a mesma correção em duas sessões, isso vai para o CLAUDE.md.

Onde colocar o arquivo

O Claude Code carrega os arquivos da pasta onde você abriu a sessão e das pastas acima dela, e junta todos. Arquivos CLAUDE.md em subpastas entram quando o Claude lê arquivos daquela subpasta.

Crie o primeiro com /init

Dentro do projeto, abra o Claude Code e rode:

/init

O Claude analisa o código e cria um CLAUDE.md com os comandos de build e de testes e as convenções que encontrou. Se o arquivo já existe, ele sugere melhorias. Depois, use /memory para abrir e editar.

Um exemplo pronto

Um CLAUDE.md para uma API em Node.js, para você adaptar:

# API da loja

API da loja em Node.js 22 com Express e PostgreSQL.

## Comandos
- Instalar: `npm ci`
- Rodar local: `npm run dev` (porta 3000)
- Testes: `npm test` (rode antes de todo commit)
- Lint: `npm run lint`

## Estrutura
- Rotas em `src/rotas/`, um arquivo por recurso
- Regras de negócio em `src/servicos/`
- Migrações em `db/migracoes/`: nunca edite uma migração já aplicada

## Convenções
- Código e comentários em português
- Indentação de 2 espaços
- Datas em UTC no banco; converta para o horário de Brasília só na resposta
- Valores em centavos, como inteiros, nunca como número decimal

## Cuidados
- Nunca faça commit do arquivo `.env`
- Chamadas a serviços externos passam por `src/clientes/`, sempre com timeout

Como escrever instruções que funcionam

• Seja específico. "Use indentação de 2 espaços" funciona melhor que "formate bem o código". "Rode npm test antes de todo commit" é melhor que "teste suas mudanças".
• Seja curto. Mire em menos de 200 linhas por arquivo. O CLAUDE.md entra no contexto de toda sessão: arquivo grande gasta tokens e dilui as instruções importantes.
• Organize. Use títulos e listas, como no exemplo.
• Tire as contradições. Se duas regras dizem coisas diferentes, o Claude pode seguir qualquer uma. Revise de vez em quando.
• Deixe notas só para humanos em comentários HTML, como <!-- revisar em outubro -->. O Claude Code remove esses comentários antes de ler o arquivo, então eles não gastam tokens.

Importe outros arquivos

Em vez de copiar conteúdo, o CLAUDE.md pode importar outros arquivos com @ seguido do caminho:

Visão geral do projeto em @README.md e scripts disponíveis em @package.json.

# Fluxo de Git
- @docs/git.md

O caminho é relativo ao arquivo que faz a importação, e um arquivo importado pode importar outros, até quatro níveis. Um caminho entre crases não é importado: serve para só citar o arquivo.

Regras por pasta em projetos grandes

Quando as instruções crescem, divida em arquivos dentro de .claude/rules/, um por assunto. Uma regra pode valer só para certos arquivos, com o campo paths no começo:

---
paths:
  - "src/rotas/**/*.ts"
---

# Regras das rotas

- Toda rota valida a entrada antes de chamar o serviço
- Erros usam o formato padrão de resposta

Essa regra só entra no contexto quando o Claude trabalha com arquivos de src/rotas/. Regras sem paths valem sempre.

E o AGENTS.md?

Se o projeto já tem um AGENTS.md, usado por outras ferramentas de programação, as versões recentes do Claude Code leem esse arquivo quando não há um CLAUDE.md. Para usar os dois, importe o AGENTS.md de dentro do CLAUDE.md com @AGENTS.md.

Quando o Claude não segue o CLAUDE.md

1. Confira se o arquivo foi carregado. O comando /context lista os arquivos de memória em uso.
2. Confira o lugar do arquivo, pela tabela acima.
3. Deixe a instrução mais específica e tire as contradições.
4. Para regras que precisam rodar sempre, como formatar o código antes de todo commit, use um hook do Claude Code, que executa um comando em momentos fixos, em vez de uma instrução.