Testei dezenas de configurações do Claude Code.
A única coisa que realmente mudou meu resultado: um arquivo de 60 linhas chamado CLAUDE.md.
Mantenha isto marcado 🔖
Aqui está exatamente como funciona, por que a maioria das pessoas perde 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 molda cada decisão que ele tomará.
É por isso que este arquivo é a variável mais subestimada em toda a stack do Claude Code.
A maioria das pessoas não tem nenhum. E quem tem cometeu um de dois erros: ou o arquivo é 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 motivos reais
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á-las.
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 está cheia de coisas que o Claude pode deduzir sozinho ou que não mudam seu comportamento de forma mensurável.
"Aja como um engenheiro sênior." → O Claude já sabe o que isso significa e não ancora nenhum comportamento específico. "Pense passo a passo." → Isso 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 previne 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 ali.
Motivo 3: Hierarquia zero
A maioria das pessoas ignora que existem três níveis de instruções no Claude Code, e elas enfiam tudo no mesmo lugar.
~/.claude/CLAUDE.md → Global (aplica-se a todos os seus projetos)
.claude/CLAUDE.md → Projeto (compartilhado com o time, no git)
./CLAUDE.local.md → Local (preferências pessoais, ignorado pelo git)
O nível global é para regras que você repetiria em todos os projetos. O nível de projeto é para contexto específico da sua 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 arquivo é como construir um funil para afogar suas regras importantes sob ruído.
As 5 seções que compõem um CLAUDE.md eficaz
Depois de vasculhar 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 te custar turnos.
Diga exatamente o que digitar:
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- path/to/file - 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 tentará npm test quando seu projeto roda em pnpm vitest. Ele gastará três turnos depurando um problema de comando que nunca ia funcionar. Três turnos 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. Ele não sabe se seus componentes devem ser stateless. Ele 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, nenhuma 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 elas 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?"
Se sim → a regra fica. Se não → ela não tem motivo para estar ali.
Exemplo de regras de alto valor:
Rules
- NUNCA commitar arquivos .env ou segredos
- Todas as chamadas assíncronas devem ser envolvidas em um try/catch
- Apenas componentes funcionais, zero componentes de classe
- Prefixos de commit obrigatórios: feat:, fix:, docs:, refactor:
- Todo PR deve passar em
npm run verifyantes do merge - Apenas exportação estática, sem SSR (implantado no S3)
- IMPORTANTE: execute a verificação de tipos após cada modificação de código
Duas coisas para 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 regras que têm as consequências mais graves se ignoradas.
Mantenha-se abaixo de 15 regras nesta seção. Além 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 para o Claude corrigir uma linha. Ele reescreve três arquivos, renomeia suas funções e refatora uma classe que não tinha nada a ver com sua solicitação.
Esta seção previne isso:
Workflow
- Faça perguntas esclarecedoras antes de iniciar 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 te perguntado.
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
- Imports @ que puxam documentos inteiros para cada sessão
- Regras duplicadas (se o global diz "rode 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 notas em ~/.claude/projects/<project>/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 usar
Delete as 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 a verificação de tipos após cada 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 monstruoso e 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 completo." "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 seu 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. Ele melhora a cada correção. Ele progressivamente se torna o melhor briefing de integração que você já escreveu.
Não para o Claude. Para você.
