Como escrever CLAUDE.md: template prático para Claude Code

O pull request volta pela terceira vez com o mesmo comentário. O Claude Code alterou a funcionalidade certa, mas ignorou o comando de teste do repositório, mexeu em uma migração fora do escopo ou esqueceu a conferência no celular. Repetir um prompt maior a cada sessão não corrige esse problema de operação.

Um CLAUDE.md útil entrega ao Claude Code poucas decisões duradouras antes do início do trabalho. Ele não precisa explicar a empresa inteira nem reproduzir o README. Este guia mostra o que deve entrar no arquivo, quais limites precisam ser impostos em outro lugar e como testar o resultado com um verificador Node.js funcional.

Resposta curta

O arquivo CLAUDE.md deve reunir comandos, limites de edição e critérios de revisão que valem para a maioria das tarefas dentro do seu escopo. Comece com estas cinco regras:

• CLAUDE.md é uma orientação persistente para o Claude Code, não um sistema de controle de acesso.
• Regras compartilhadas ficam na raiz do repositório, notas pessoais em CLAUDE.local.md e regras específicas de caminho em .claude/rules/.
• Procure manter menos de 200 linhas. Caminhos, comandos e condições de aprovação valem mais que longas explicações de contexto.
• Restrições de segurança devem ser impostas por permissions e hooks, em vez de depender de um aviso escrito.
• Teste uma nova instrução em uma tarefa real e pequena antes de transformá-la em regra da equipe.

Não tente criar o arquivo perfeito no primeiro dia. Reúna os comentários dos três pull requests mais recentes e mantenha apenas as decisões que provavelmente serão necessárias outra vez.

O que delegar ao Claude Code e o que uma pessoa deve decidir

Um arquivo de orientação e uma barreira de permissão resolvem problemas diferentes. O Claude Code pode investigar o código existente, fazer uma alteração delimitada, executar verificações nomeadas e resumir o diff. Uma pessoa continua responsável por política de produto, aprovação de produção e decisões relacionadas a clientes, dinheiro, privacidade ou obrigações legais.

Decisão	Delegar ao Claude Code	Manter com uma pessoa
Investigação	Encontrar arquivos, padrões e testes relacionados	Decidir se dados de clientes ou contratos podem ser examinados
Implementação	Alterar código e testes dentro do escopo informado	Aprovar mudanças de preço, autorização, questões legais e políticas visíveis ao cliente
Verificação	Executar lint, checagem de tipos, testes e build	Avaliar critérios de aceite e autorizar a publicação
Manutenção	Relatar arquivos alterados e riscos pendentes	Adicionar ou remover regras permanentes do repositório

Na prática, CLAUDE.md diz: “verifique estes pontos nesta ordem”. O arquivo não garante que um comando destrutivo jamais será executado. Use regras de negação de permissão ou um hook PreToolUse quando for preciso bloquear de verdade git push --force, acesso ao banco de produção ou arquivos com segredos. O guia de permissões do Claude Code trata essa camada de proteção separadamente.

Escolha o escopo correto antes de escrever

O local do arquivo controla onde a orientação se aplica. Um CLAUDE.md na raiz é apropriado para regras compartilhadas do projeto. ~/.claude/CLAUDE.md vale para os projetos do usuário. CLAUDE.local.md serve para notas privadas da máquina e deve ser ignorado pelo Git. Arquivos aninhados e regras por caminho evitam que repositórios grandes carreguem instruções irrelevantes o tempo todo.

repo/
  CLAUDE.md                  # short rules shared by the team
  CLAUDE.local.md            # personal notes; add to .gitignore
  .claude/
    rules/
      api.md                 # rules needed only for API files
  packages/
    admin/
      CLAUDE.md              # added when Claude reads this subtree

Na inicialização, o Claude Code lê os arquivos aplicáveis no diretório atual e nos diretórios acima dele. Um CLAUDE.md aninhado é carregado quando Claude lê arquivos daquela subárvore. Por isso, regras de um pacote devem ficar perto do pacote, em vez de todas serem acumuladas no arquivo da raiz.

Um import como @docs/project-map.md ajuda a organizar as instruções, mas não economiza contexto. O conteúdo importado também é carregado na inicialização. Mantenha em CLAUDE.md a decisão que precisa estar sempre disponível e aponte para materiais detalhados que serão lidos somente quando necessários. No Windows, o Claude Code lê CLAUDE.md, não AGENTS.md; portanto, importar @AGENTS.md explicitamente é mais confiável do que depender de um link simbólico.

Comece com este template de CLAUDE.md

Comandos e regras de mudança devem caber em uma tela. O template abaixo evita instruções vagas como “escreva código limpo”. Ele informa caminhos, verificações, exclusões e o relatório final esperado do agente.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

O arquivo pode ser escrito no idioma usado pela equipe. Precisão importa mais que idioma. Substitua “teste adequadamente” por npm test. Troque “siga a arquitetura” por algo verificável, como “respostas de API usam src/lib/api-response.ts”. Quem revisa deve conseguir dizer se a instrução foi cumprida sem adivinhar seu significado.

Três casos de uso reais

Os fluxos a seguir separam entrada, saída e revisão humana. Antes de registrar um aprendizado no arquivo permanente, execute uma tarefa pequena e confira se a instrução muda um resultado observável.

Caso de uso 1: reduzir comentários repetidos em uma agência

Uma agência web pode adotar convenções de CSS, tamanhos de imagem e navegadores-alvo diferentes em cada projeto de cliente. Copiar o manual completo da agência para todos os repositórios esconde as regras importantes. Guarde apenas as três a cinco verificações que valem para aquele cliente e aquela base de código.

Entrada: As três últimas discussões de revisão, os arquivos dentro do escopo e os comandos existentes de lint e build.

Saída: Um relatório do diff que nomeie componentes reutilizados, páginas alteradas, comandos executados e condições de navegador ainda não verificadas.

Revisão humana: Intenção visual, direitos das imagens, texto do CTA e layout móvel final. Compare a quantidade de devoluções em dez tarefas antes e dez depois da mudança; esse sinal é melhor que o tamanho bruto do CLAUDE.md.

Caso de uso 2: alterar com segurança um formulário de SaaS

Um formulário pode parecer correto mesmo com validação do servidor, e-mail de notificação ou tratamento de erro quebrados. A orientação do projeto deve nomear os arquivos e testes que precisam mudar juntos sempre que o formulário for alterado.

Entrada: Componente do formulário, esquema de validação, handler da API, template de e-mail e testes existentes.

Saída: Testes do caminho de sucesso e de entrada inválida, erros mostrados ao usuário e lista de configurações alteradas. O relatório final também confirma que dados pessoais não foram gravados em logs.

Revisão humana: Campos coletados, política de retenção, destinatários da notificação e liberação em produção. Além da taxa de conversão, acompanhe envios com falha e tempo de atendimento.

Caso de uso 3: evitar publicação incompleta de conteúdo

Uma página MDX pode ter um texto correto e ainda ser publicada sem description, link interno, imagem de capa ou bloco de código utilizável no celular. Uma lista curta de publicação oferece ao agente uma linha de chegada observável.

Entrada: Arquivo MDX, esquema do frontmatter, destinos dos links internos, comando de build e URL de produção.

Saída: Tamanho da description, resultado da checagem de links, conferência dos blocos de código, status do build e URLs abertas no navegador.

Revisão humana: Precisão factual, intenção de busca, posição dos anúncios, legibilidade e autorização da publicação. Analise semanalmente cliques de busca, leitura engajada e cliques no CTA, em vez de julgar o resultado apenas por pageviews.

Execute este verificador de CLAUDE.md

O script Node.js abaixo verifica a quantidade de linhas, títulos obrigatórios e alguns padrões de alto sinal para segredos. Salve-o como check-claude-md.mjs e execute com Node.js 20 ou mais recente.

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

O comando é simples o bastante para uso local e na integração contínua:

node check-claude-md.mjs CLAUDE.md
# Ao usar títulos H2 em português
node check-claude-md.mjs CLAUDE.md "Comandos|Regras de alteração|Lista de revisão"

Esse verificador não substitui um scanner completo de segredos. Combine-o com o secret scanning do GitHub ou uma ferramenta especializada. Se uma credencial for detectada, remova-a do histórico quando necessário e revogue-a; apagar somente a linha visível não basta.

Armadilhas, causas e correções

Armadilha 1: o arquivo cresce depois de cada revisão. A causa é transformar todo comentário em regra permanente antes de saber se ele vai se repetir. Inclua apenas decisões recorrentes, apague primeiro os comandos antigos e leve detalhes específicos de pacote para perto do pacote.

Armadilha 2: as instruções não podem ser verificadas. “Mantenha a qualidade” e “siga o design existente” não definem uma condição de aprovação. Informe caminho-alvo, comando, código de saída esperado, largura do navegador ou nome do teste. Uma pessoa nova na equipe deve chegar à mesma conclusão que o autor.

Armadilha 3: a segurança depende de texto. Escrever “nunca toque em produção” não cria uma barreira. Coloque padrões perigosos nas regras de negação de permissão e use um hook PreToolUse quando uma operação tiver de ser interrompida de modo determinístico. Deixe no CLAUDE.md o motivo e a alternativa aprovada.

Armadilha 4: imports viram um depósito oculto de conhecimento. A causa é imaginar que arquivos importados não consomem contexto. Eles são carregados na inicialização. Mantenha uma regra de decisão curta no arquivo da raiz e forneça um caminho ou URL para detalhes que Claude só precisa ler na tarefa correspondente.

Manutenção sem deixar a documentação envelhecer

Trate uma mudança em CLAUDE.md como mudança de código. Abra o diff, execute o verificador e teste uma tarefa representativa. Remova uma regra quando o comando, caminho ou arquitetura que ela descreve deixar de existir.

Uma revisão mensal leve pode responder a quatro perguntas:

1. Qual comentário de revisão apareceu mais de uma vez?
2. Qual instrução foi ignorada ou interpretada de duas maneiras?
3. Qual comando ou caminho ficou desatualizado?
4. Qual aviso deve ser imposto por permission ou hook?

A métrica útil não é o total de tokens nem o tamanho do documento. Acompanhe devoluções de revisão, falhas detectadas antes do merge e minutos gastos repetindo o básico do repositório. Se esses números não melhorarem, reescreva ou remova a regra.

Perguntas frequentes

Qual deve ser o tamanho do CLAUDE.md?

Não existe um limite rígido de conteúdo, mas a orientação oficial recomenda mirar menos de 200 linhas. Começar perto de 100 deixa espaço para mapa do projeto, comandos, limites e critérios de revisão. Material restrito a um pacote deve ir para arquivos aninhados ou .claude/rules/.

O arquivo continua valendo depois de /compact?

O CLAUDE.md da raiz é inserido novamente no contexto depois da compactação. Instruções aninhadas e específicas de caminho voltam a ser carregadas quando Claude lê arquivos correspondentes. Registre decisões duradouras em arquivos, em vez de depender de uma conversa que pode ser compactada.

Qual é a diferença para o Auto Memory?

CLAUDE.md contém instruções escritas e mantidas por pessoas. Auto Memory contém notas locais que Claude registra durante o trabalho, como descobertas de depuração e preferências. Comandos e limites compartilhados pertencem ao CLAUDE.md; descobertas locais permanecem no Auto Memory até que uma pessoa decida promovê-las a regra da equipe.

O que deve entrar na primeira versão?

Comece pelos comandos de instalação, teste e build, uma lista de áreas protegidas e os itens exigidos no relatório final. Execute uma tarefa real e acrescente somente a decisão ausente que provocou retrabalho observável.

Monte o template do seu projeto com os materiais do curso

Escrever CLAUDE.md é apenas uma parte de um fluxo confiável. Permissões, testes, passagem de contexto e revisão também precisam estar alinhados. O catálogo de produtos do ClaudeCodeLab reúne checklists e exercícios reutilizáveis para transformar essas peças em um template operacional específico para o projeto.

O que foi testado de fato

Em 22 de julho de 2026, o código de check-claude-md.mjs deste artigo foi executado com dois arquivos temporários. Uma amostra válida de 10 linhas retornou código de saída 0 e a mensagem de aprovação. Uma amostra negativa com um título ausente e um token de teste retornou código de saída 1 e exatamente três achados: o título ausente e dois padrões de segredo correspondentes.

A revisão do artigo também conferiu sintaxe JavaScript, URLs das fontes oficiais, links internos, frontmatter, a seção final de resultados e a presença de um único CTA comercial principal. Comece executando o verificador no seu próprio CLAUDE.md e corrija o primeiro item relatado. O comportamento do produto foi confrontado com a documentação oficial do Claude Code sobre Memory, janela de contexto, Settings e Hooks.