Guia completo do CLAUDE.md: a arma secreta do Claude Code que você está subutilizando

Por que isso importa agora

O Claude Code se tornou uma das ferramentas de desenvolvimento assistido por IA mais usadas por engenheiros em 2026, ao lado do GitHub Copilot e Cursor. Mas há uma diferença crucial: enquanto outras ferramentas dependem de contexto inferido do código, o Claude Code tem uma arma secreta que muitos usuários subutilizam — o arquivo CLAUDE.md.

Se você usa Claude Code no dia a dia e nunca personalizou seu CLAUDE.md, está deixando performance na mesa. Este guia cobre tudo: da estrutura básica às técnicas avançadas que times de engenharia estão usando em produção.

Prós e Contras

✅ O que você ganha

• Contexto persistente: instruções que o Claude carrega automaticamente em toda sessão, sem precisar repetir
• Padronização de equipe: um CLAUDE.md compartilhado garante que todos os membros recebam as mesmas diretrizes de código
• Redução de alucinações: especificar convenções do projeto (framework, padrões de nomenclatura, estrutura de diretórios) reduz drasticamente código incorreto
• Configuração de segurança: defina quais comandos podem ou não ser executados automaticamente
• Customização por projeto: CLAUDE.md no repositório + CLAUDE.md local na home (~/.claude/CLAUDE.md) — camadas que se complementam
• Memória institucional: novos devs recebem todo o contexto do projeto imediatamente ao abrir o Claude Code

⚠️ O que você NÃO ganha

• Não substitui documentação completa do projeto — é um complemento, não o README inteiro
• Não resolve problemas de lógica complexa — o CLAUDE.md orienta comportamento, não adiciona capacidade de raciocínio
• Arquivos muito longos (>500 linhas) podem diluir o contexto e piorar a qualidade das respostas

Tabela de requisitos

Estrutura do CLAUDE.md

O CLAUDE.md é um arquivo Markdown que pode existir em três níveis:

1. Global (~/.claude/CLAUDE.md): preferências pessoais que se aplicam a todos os projetos
2. Projeto (./CLAUDE.md na raiz do repo): regras específicas do projeto, compartilhadas com a equipe via Git
3. Subdiretório (./subdir/CLAUDE.md): instruções específicas para partes do projeto

O Claude Code carrega e mescla todos os níveis automaticamente ao iniciar.

Seções recomendadas

# CLAUDE.md

## Comandos úteis
# Build, teste, lint — comandos que o Claude pode executar
- Build: `npm run build`
- Test: `npm test -- --coverage`
- Lint: `npx eslint . --fix`
- Tipo: `npx tsc --noEmit`

## Convenções de código
# Padrões que o Claude DEVE seguir
- Use React 18+ Server Components como padrão
- Nomes de arquivo em kebab-case para componentes
- Testes com Jest + React Testing Library
- Prefira async/await a Promises encadeadas
- CSS Modules para estilização (não Tailwind neste projeto)

## Arquitetura do projeto
# Como o código está organizado
- `src/components/` — componentes React reutilizáveis
- `src/app/` — rotas Next.js App Router
- `src/lib/` — funções utilitárias e serviços
- `src/hooks/` — hooks React personalizados
- `prisma/` — schema e migrações do banco de dados

## Regras de segurança
# Comandos bloqueados
- NUNCA execute `rm -rf` sem confirmação explícita
- NUNCA modifique arquivos em `.git/` ou `node_modules/`
- NUNCA faça commit sem revisão humana
- NUNCA exponha chaves de API, use variáveis de ambiente

## Estilo de código
- 2 espaços para indentação (não tabs)
- Ponto e vírgula obrigatório
- Strings com aspas simples
- Máximo 80 caracteres por linha

6 padrões avançados

1. Instruções condicionais por tipo de arquivo

Você pode instruir o Claude a aplicar regras diferentes dependendo da extensão do arquivo que está editando:

## Regras por tipo de arquivo
- Para arquivos *.tsx: use React.memo() em componentes que recebem props
- Para arquivos *.test.ts: use describe/it, não test()
- Para arquivos de migração Prisma: sempre adicione comentário explicando o propósito

2. Templates de commit

Padronize como o Claude gera mensagens de commit:

## Mensagens de commit
Use conventional commits:
- feat: nova funcionalidade
- fix: correção de bug
- refactor: alteração de código sem mudança funcional
- docs: documentação
- chore: manutenção, dependências

Exemplo: `feat(auth): adiciona login com Google OAuth`

3. Guardrails de deploy

Impeça que o Claude execute comandos perigosos em produção:

## Regras de deploy
- Antes de qualquer deploy, confirme: branch atual, ambiente alvo, changelog
- Staging: permitido com `--dry-run` primeiro
- Produção: NUNCA faça deploy direto — apenas abra PR e aguarde revisão
- Rollback: mantenha sempre o último deploy funcional como fallback

4. Referências externas

O CLAUDE.md pode referenciar outros arquivos de documentação para manter o arquivo principal enxuto:

## Documentação adicional
- Para padrões de API REST, veja: [docs/api-standards.md](./docs/api-standards.md)
- Para o guia de design system, veja: [docs/design-system.md](./docs/design-system.md)
- Para políticas de revisão de código, veja: [CONTRIBUTING.md](./CONTRIBUTING.md)

5. Contexto de negócio

Inclua informações sobre o domínio do produto para que o Claude entenda o “porquê” por trás do código:

## Contexto do produto
- Nosso app é um SaaS B2B de gestão financeira para PMEs brasileiras
- Usuário principal: contador ou dono de pequena empresa (não técnico)
- Monetização: assinatura mensal (R$49-R$199) com 14 dias de trial
- Stack: Next.js 14 + Prisma + PostgreSQL + AWS (ECS + RDS)
- ~15 mil empresas ativas, ~200 requests/segundo no pico

6. Instruções para debugging

Orientar o Claude sobre como abordar bugs no seu projeto:

## Abordagem de debugging
1. Leia os logs relevantes em `logs/` primeiro
2. Verifique se há testes cobrindo o comportamento esperado
3. Use `git bisect` para encontrar commits suspeitos
4. Reproduza o bug em ambiente isolado antes de propor correção
5. SEMPRE adicione um teste de regressão com a correção

Casos de uso reais

1. Onboarding de novos desenvolvedores: um CLAUDE.md bem escrito reduz de dias para horas o tempo até o primeiro commit produtivo
2. Manutenção de código legado: documente padrões obscuros e “por que está assim” para o Claude navegar código antigo com contexto histórico
3. Refatoração em larga escala: instrua o Claude a seguir novas convenções ao migrar um codebase (ex: JavaScript → TypeScript, REST → GraphQL)
4. Revisão de código automatizada: configure o CLAUDE.md com as regras do seu linter e guia de estilo — o Claude aplica na geração antes mesmo do CI rodar
5. Segurança em times terceirizados: restrinja quais comandos e operações o Claude pode executar quando usado por devs externos
6. Multi-repo consistency: compartilhe um CLAUDE.md base entre repositórios do mesmo ecossistema via template de organização

Troubleshooting: 5 erros comuns

1. ❌ CLAUDE.md não está sendo carregado: verifique se está no diretório raiz do projeto e se o nome está exato (case-sensitive: CLAUDE.md, não claude.md ou CLAUDE.MD)
2. ❌ Instruções são ignoradas: instruções muito genéricas ou contraditórias são diluídas pelo modelo. Seja específico: “use React.memo() em componentes com mais de 3 props” em vez de “escreva código performático”
3. ❌ Arquivo grande demais piora respostas: CLAUDE.md acima de 500 linhas consome janela de contexto que poderia ser usada para código. Extraia seções para arquivos referenciados
4. ❌ Conflito entre CLAUDE.md global e do projeto: o Claude Code mescla os dois, mas instruções contraditórias causam comportamento imprevisível. Revise ambos periodicamente
5. ❌ Segredos no CLAUDE.md: se o arquivo está versionado no Git, nunca coloque chaves de API ou tokens nele. Use variáveis de ambiente

FAQ

1. CLAUDE.md funciona com a API do Claude ou só com Claude Code? Funciona nativamente com Claude Code. Para a API, você precisaria implementar a injeção de contexto manualmente.
2. Posso ter múltiplos CLAUDE.md no mesmo projeto? Sim, um na raiz e outros em subdiretórios. O Claude Code carrega o mais próximo do arquivo sendo editado + o da raiz.
3. Qual o tamanho ideal? Entre 50 e 300 linhas. Menos que isso é subutilizado; mais que isso começa a competir com o código pelo contexto.
4. Funciona com outros modelos da Anthropic? O mecanismo CLAUDE.md é específico do Claude Code, mas o conceito de instruções de sistema em Markdown funciona com qualquer modelo Anthropic via API.
5. Posso usar emoji no CLAUDE.md? Sim, mas com moderação. Emojis consomem tokens e podem ser processados de forma inconsistente.
6. CLAUDE.md substitui o README? Não. README é para humanos; CLAUDE.md é instruções operacionais para o Claude. Mantenha-os separados e com propósitos distintos.

O futuro: agentes que leem documentação

O CLAUDE.md é um exemplo inicial do que está se tornando uma tendência maior em 2026: agentes de IA que recebem contexto estruturado sobre o projeto antes de começar a trabalhar. O GitHub Copilot já anunciou um mecanismo similar com “Copilot Instructions”, e o Cursor tem suas “rules”. A diferença do CLAUDE.md é a simplicidade: é só Markdown, versionado com o código, sem DSL proprietária.

Times que investem 30 minutos para escrever um bom CLAUDE.md colhem ganhos de produtividade por meses. Se você ainda não tem um no seu projeto, a melhor hora para criar era quando instalou o Claude Code. A segunda melhor hora é agora.