CLAUDE.md: onde colocar, o que escrever e como ele convive com o AGENTS.md

O que é o CLAUDE.md

O Claude Code começa cada sessão sem lembrar da anterior. O CLAUDE.md é a forma de dar a ele o contexto de que um colega novo precisaria: é lido na inicialização e enviado ao Claude como uma mensagem depois do system prompt. Isso o torna contexto, não configuração obrigatória. O Claude costuma segui-lo, mas o que precisa acontecer sempre ou nunca pertence a hooks ou a regras de permissão.

• Markdown simples, sem campos obrigatórios: títulos e tópicos curtos funcionam melhor.
• Os arquivos são combinados, não sobrescritos: todo CLAUDE.md aplicável é carregado, então linhas contraditórias deixam o Claude escolher uma.
• Confira o que foi carregado com /context all, em Memory files.

Onde ficam os arquivos CLAUDE.md e em que ordem carregam

O Claude Code os carrega do mais amplo ao mais específico, então o arquivo mais próximo de onde você iniciou é lido por último. Ele também sobe a partir do seu diretório de trabalho e carrega o CLAUDE.md de cada diretório pai.

Como escrever um CLAUDE.md que funciona

1. Comece com /init

   Execute /init no seu projeto. O Claude Code lê o código e escreve um CLAUDE.md inicial; se já existir um, sugere melhorias em vez de sobrescrevê-lo. Ele também aproveita .cursorrules e as instruções do Copilot.

2. Deixe só o que o Claude não descobre sozinho

   Mantenha os comandos exatos de build, teste e lint (incluindo como rodar um único teste), os pontos em que o código engana, as decisões que não estão escritas em lugar nenhum e tudo o que você precisou corrigir duas vezes. Tire árvores de arquivos e a arquitetura que o Claude consegue ler no repositório. A Anthropic sugere ficar abaixo de 200 linhas.

   # Comandos
   - Instalar: pnpm install
   - Um único arquivo de teste: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Convenções
   - Lance erros com os helpers de src/lib/errors.ts, nunca com strings soltas.
   - src/legacy/ ainda está em uso, mas não copie os padrões dele.
   
   # Armadilhas
   - Os testes de integração precisam de DATABASE_URL (veja .env.example).

3. Seja específico, sem gritar

   Escreva "Use indentação de 2 espaços", não "Formate o código direito". A documentação atual diz que IMPORTANT e CAIXA ALTA são um conselho ultrapassado: fazem o Claude aplicar uma regra demais. Se uma linha continua sendo ignorada, encurte o arquivo ou transforme a regra em um hook.

4. Divida com imports e regras

   @path/to/file importa outro arquivo (relativo ao arquivo que importa, até quatro níveis de profundidade); um @ dentro de crases continua literal. As regras que valem para uma parte do código vão em .claude/rules/ com um glob paths, e carregam só quando o Claude mexe em arquivos que combinam.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - Todo handler valida a entrada com o schema de src/api/schemas/.

5. Leve os procedimentos para skills

   Fluxos de várias etapas, como fazer um release, pertencem a uma skill (.claude/skills/<name>/SKILL.md), que carrega só quando é relevante. O CLAUDE.md é lido em toda tarefa, então cada linha custa atenção.

6. Mantenha atualizado

   Adicione uma linha quando o Claude repetir um erro ou uma revisão apontar algo, e edite o arquivo com /memory ou pedindo ao Claude que o atualize. O /doctor sugere cortes quando o arquivo cresce demais.

Fonte: documentação do Claude Code, How Claude remembers your project

CLAUDE.md vs AGENTS.md

O AGENTS.md é um formato aberto de instruções para agentes de programação, usado por Codex, Cursor, Gemini CLI, o agente de código do GitHub Copilot, opencode e muitos outros. O Claude Code agora também o lê, mas por padrão só quando o projeto não tem CLAUDE.md.

Um único arquivo para Claude Code e Codex

Se a sua equipe usa os dois agentes, deixe as instruções compartilhadas no AGENTS.md e faça o CLAUDE.md importá-lo, com as notas só do Claude embaixo. Ele nunca carrega duas vezes. Um symlink (ln -s AGENTS.md CLAUDE.md) também funciona, mas não para quem usa Windows, e um CLAUDE.md que só diz "leia o AGENTS.md" em palavras não é confiável.

• O repositório deste próprio site faz exatamente isso: o CLAUDE.md dele é a linha única @AGENTS.md.
• O Codex lê os arquivos AGENTS.md da raiz do repositório até o seu diretório de trabalho e limita o tamanho combinado a 32 KiB por padrão.

Limites e armadilhas

• Um CLAUDE.md carregado na inicialização é lido inteiro até 4 MiB; um arquivo maior é ignorado.
• Arquivos carregados sob demanda, como os CLAUDE.md de subdiretórios e as regras por caminho, são cortados acima de um limite por arquivo (40.000 caracteres com uma janela de contexto de 200K).
• Imports organizam um arquivo, mas não economizam contexto: o texto importado carrega do mesmo jeito.
• Imports de fora do projeto pedem aprovação uma vez; comentários HTML <!-- --> são removidos e não custam nada.
• O CLAUDE.md da raiz do projeto é lido de novo depois do /compact.
• "Lembre disto" vai para a auto memory (~/.claude/projects/<project>/memory/), não para o CLAUDE.md.

O CLAUDE.md diz como trabalhar. O Crewmark diz em que trabalhar e quando.

Um bom CLAUDE.md faz cada sessão do Claude Code começar bem informada, mas a sessão continua esperando a sua próxima mensagem. O Crewmark transforma uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro.

1. Transforme uma sessão em funcionário

   Escolha um papel, como engenheiro de software ou especialista em SEO, escreva a meta dele como um número e execute o comando de configuração no seu projeto, onde o seu CLAUDE.md já está.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como tornar o Claude Code proativo. Vários podem compartilhar um repositório, como em vários agentes do Claude Code.

3. Atribua issues e responda às mensagens

   Coloque o trabalho no quadro; o funcionário pega, comenta pelo caminho e avisa você quando precisa de uma decisão. Leia o que é um funcionário de IA.

Perguntas frequentes sobre o CLAUDE.md