Eu testei dezenas de configurações do Claude Code.
A única coisa que realmente mudou meu resultado: um arquivo de 60 linhas chamado CLAUDE.md.
Guarde este link 🔖
Aqui está exatamente como funciona, por que a maioria das pessoas erra completamente e o template completo que você pode copiar hoje:
O que ninguém te conta sobre o Claude Code
Antes do seu primeiro prompt. Antes de uma única linha de código. Antes de qualquer coisa acontecer na sua sessão.
O Claude lê um arquivo. Apenas um.
CLAUDE.md.
E ele o trata como a verdade absoluta para toda a sessão. Não como uma sugestão. Não como contexto entre outros. Como o briefing definitivo que enquadra cada decisão que ele tomará.
É por isso que este arquivo é a variável mais subestimada de todo o stack do Claude Code.
A maioria das pessoas não tem nenhum. E quem tem, cometeu um de dois erros: ou o arquivo está vazio de substância, ou tem 300 linhas de "seja um engenheiro sênior experiente que pensa passo a passo".
Ambos são inúteis. Por razões diferentes.
Por que a maioria dos arquivos CLAUDE.md não funciona: os 3 verdadeiros motivos
Motivo 1: Muito longo
O Claude consegue seguir de forma confiável cerca de 150 a 200 instruções por sessão. Isso é uma restrição estrutural, não uma questão de boa vontade.
Problema: o prompt de sistema interno do Claude Code já contém cerca de 50 instruções. Isso significa que seu CLAUDE.md na verdade tem de 100 a 150 slots de instrução antes do Claude começar a descartá-los.
Se seu arquivo tem 200 linhas, o Claude não está ignorando suas regras de propósito. Ele as esquece mecanicamente. Você não tem um problema de conformidade. Você tem um problema de orçamento de atenção.
Motivo 2: Conteúdo ruim
A maioria dos arquivos CLAUDE.md é preenchida com coisas que o Claude pode deduzir sozinho ou que não alteram seu comportamento de forma mensurável.
"Aja como um engenheiro sênior." → O Claude já sabe o que isso significa e isso não ancora nenhum comportamento específico. "Pense passo a passo." → Isso já está no treinamento dele. Você está desperdiçando uma linha. "Escreva código limpo e sustentável." → Sem critérios concretos. O Claude não sabe o que "limpo" significa no seu contexto específico.
Cada linha que não evita um erro específico e concreto é uma linha roubada de instruções que realmente importam. O teste é simples: se você deletar esta linha, o Claude vai errar algo específico? Se a resposta for não, a linha não deveria estar lá.
Motivo 3: Zero hierarquia
A maioria das pessoas ignora que existem três níveis de instruções no Claude Code, e eles colocam tudo no mesmo lugar.
~/.claude/CLAUDE.md → Global (aplica-se a todos os seus projetos)
.claude/CLAUDE.md → Projeto (compartilhado com a equipe, no git)
./CLAUDE.local.md → Local (preferências pessoais, ignorado pelo git)
O nível global é para regras que você repetiria em todo projeto. O nível de projeto é para contexto específico do seu stack e equipe. O nível local é para suas preferências pessoais que não precisam ser compartilhadas.
Usar os três níveis corretamente é o que mantém cada arquivo curto, focado e verdadeiramente eficaz. Colocar tudo em um único arquivo é como construir um funil para afogar suas regras importantes em ruído.
As 5 seções que compõem um CLAUDE.md eficaz
Depois de examinar dezenas de arquivos CLAUDE.md em produção — projetos open-source, documentação oficial da Anthropic, repositórios de melhores práticas da comunidade — aqui estão as 5 seções que todos os arquivos eficazes têm em comum:
Seção 1: Comandos críticos
O Claude começa cada sessão sem saber como compilar seu projeto, rodar seus testes ou corrigir erros de lint. Ele vai chutar. E seus chutes vão custar turns.
Diga exatamente o que digitar:
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- caminho/do/arquivo - Full test:
npm test - Lint + fix:
npm run lint:fix - Type check:
npx tsc --noEmit
Curto. Preciso. Diretamente utilizável.
Sem esta seção, o Claude vai tentar npm test quando seu projeto roda com pnpm vitest. Vai gastar três turns depurando um problema de comando que nunca ia funcionar. Três turns que você poderia ter usado em trabalho real.
Seção 2: Mapa da arquitetura
O Claude começa cada sessão com zero conhecimento do seu código. Zero. Ele não sabe onde sua lógica de negócio vive. Não sabe se seus componentes devem ser stateless. Não sabe que suas rotas de API não devem conter lógica de negócio.
Dê a ele um mapa:
Architecture
- src/lib/services/ → toda a lógica de negócio
- src/components/ → apenas componentes de UI stateless
- src/lib/store/ → estado global (Zustand)
- src/app/api/ → rotas de API, sem lógica de negócio aqui
- Acesso ao DB apenas via Server Actions ou rotas de API
Não é uma listagem exaustiva da sua estrutura de árvore. Apenas o suficiente para o Claude saber onde as coisas vivem e, mais importante, onde NÃO devem ir.
Essa distinção... onde vai vs. onde não vai... é o que previne os erros arquiteturais mais frequentes.
Seção 3: Regras rígidas
Esta é a seção mais importante de todo o arquivo. Sem exceção.
Cada regra aqui deve responder a uma única pergunta: "Se eu deletar esta linha, o Claude cometerá um erro concreto?"
Sim → a regra fica. Não → ela não tem nada que estar ali.
Exemplo de regras de alto valor:
Rules
- NUNCA commitar arquivos .env ou segredos
- Todas as chamadas assíncronas devem ser envolvidas em try/catch
- Apenas componentes funcionais, zero componentes de classe
- Prefixos de commit obrigatórios: feat:, fix:, docs:, refactor:
- Cada PR deve passar
npm run verifyantes do merge - Apenas exportação estática, sem SSR (implantado no S3)
- IMPORTANTE: execute type check após toda modificação de código
Duas coisas a observar nesta lista.
Primeiro, regras negativas são tão importantes quanto regras positivas. "Nunca commitar arquivos .env" é uma regra que só parece óbvia até o dia em que o Claude faz isso. Coloque-a.
Segundo, marcadores de ênfase como IMPORTANTE ou VOCÊ DEVE realmente funcionam.
Isso não é anedótico. A Anthropic confirma em sua própria documentação: adicionar IMPORTANTE ou VOCÊ DEVE antes de uma regra melhora mensuravelmente a adesão do Claude a essa regra.
Use-os com moderação: reserve-os para as regras que têm as consequências mais graves se ignoradas.
Mantenha-se abaixo de 15 regras nesta seção. Acima disso, você dilui a atenção nas que importam.
Seção 4: Preferências de fluxo de trabalho
Você já passou por isso. Você pede ao Claude para corrigir uma linha. Ele reescreve três arquivos, renomeia suas funções e refatora uma classe que não tinha nada a ver com seu pedido.
Esta seção evita isso:
Workflow
- Faça perguntas esclarecedoras antes de começar tarefas complexas
- Faça mudanças mínimas, não refatore código não relacionado
- Execute testes após cada mudança, corrija falhas antes de continuar
- Crie commits separados por mudança lógica, não um commit gigante
- Em caso de incerteza entre duas abordagens, explique ambas e deixe-me escolher
Cada linha aqui responde a um ponto de dor concreto. O commit gigante de 47 arquivos. A reescrita completa não solicitada. A decisão arquitetural que o Claude toma sozinho quando deveria ter perguntado a você.
Seção 5: O que NÃO colocar no seu CLAUDE.md
Esta seção é tão importante quanto as outras. Talvez mais.
Do NOT include:
- Instruções de personalidade ("seja um engenheiro sênior")
- Regras de formatação que seu linter já trata
- Importações @ que puxam docs inteiros para cada sessão
- Regras duplicadas (se o global diz "execute testes", o projeto não repete)
- Qualquer coisa que o Claude aprenda sozinho via memória automática
Este último ponto é amplamente subestimado.
O Claude mantém suas próprias anotações em ~/.claude/projects/<projeto>/memory/. Execute /memory na sua sessão para ver o que ele já aprendeu sobre seu projeto. Após algumas sessões, você frequentemente perceberá que o Claude já capturou informações que você ia escrever manualmente no seu CLAUDE.md.
Não desperdice suas instruções limitadas em coisas que o Claude já lembrou sozinho.
O template completo em menos de 60 linhas, pronto para uso
Delete seções que não se aplicam ao seu projeto. O objetivo não é preencher tudo. O objetivo é manter apenas o que muda o comportamento do Claude de forma mensurável.
As linhas que tiveram mais impacto no meu resultado: resultados concretos
Depois de testar dezenas de configurações, aqui estão as cinco linhas que fizeram a diferença mais visível:
IMPORTANTE: execute type check após toda modificação de código → Impede que o Claude entregue código com tipos quebrados que ele não detecta sem ser explicitamente instruído a verificar.
Faça mudanças mínimas, não refatore código não relacionado → Impede a reescrita completa e não solicitada de arquivos inteiros.
Crie commits separados por mudança lógica, não um commit gigante → Impede o commit monstro ilegível de 47 arquivos misturados.
Em caso de incerteza entre duas abordagens, explique ambas e deixe-me escolher → Impede que o Claude tome decisões arquiteturais sozinho que deveriam ser suas.
Apenas exportação estática, sem SSR → Impede que o Claude adicione código de servidor em um projeto implantado estaticamente no S3.
O que essas cinco linhas têm em comum: cada uma previne um erro específico, frequente e custoso em tempo de depuração.
Este é o teste definitivo para cada linha do seu CLAUDE.md.
O erro fundamental e por que ele é tão difundido
As pessoas tratam seu CLAUDE.md como uma lista de desejos ou um prompt de personalidade.
"Seja sênior." "Seja minucioso." "Pense como um especialista."
Isso não é um briefing. É pensamento mágico.
Seu CLAUDE.md deve ser um documento técnico, não um discurso motivacional. Stack, comandos, arquitetura, regras concretas, fluxo de trabalho. Todo o resto é ruído que compete com as instruções que realmente importam.
Mantenha o arquivo com menos de 80 linhas. Revise-o toda vez que o Claude cometer um erro que você poderia ter prevenido.
E acima de tudo: entenda o que este arquivo se torna com o tempo.
Um bom CLAUDE.md no primeiro mês economiza tempo em cada sessão. No terceiro mês, ele já capturou suas convenções e stack com precisão suficiente para que o Claude funcione quase como um membro da equipe.
No sexto mês, ele contém todos os erros que o Claude já cometeu neste projeto e os previne todos automaticamente.
O arquivo capitaliza. Melhora a cada correção. Progressivamente, torna-se o melhor briefing de integração que você já escreveu.
Não para o Claude. Para você.
