Claude Code funciona bem pronto para usar, mas se torna notavelmente mais eficaz quando conhece as convenções do seu projeto e quando você adota alguns hábitos de prompt. Este guia cobre ambos.
Parte 1 — CLAUDE.md: a memória do seu projeto
O que é
CLAUDE.md é um arquivo markdown simples que Claude lê automaticamente no início de cada sessão naquele diretório. Pense nele como o briefing que você daria a um novo colega capaz no primeiro dia: como o time faz as coisas, o que evitar e onde as peças importantes vivem.
Você não precisa referenciá-lo em prompts ou anexá-lo manualmente. Se o arquivo existe, Claude já o leu.
Onde fica
Claude procura em alguns lugares e mescla o que encontra, do amplo para o específico:
Localização | Escopo | Bom para |
| Cada projeto na sua máquina | Preferências pessoais (por exemplo, "uso pnpm, não npm" ou "sempre sugira testes"). |
| Este projeto | Arquitetura, convenções e comandos. Este é o principal. |
| Aquele subdiretório (carregado sob demanda quando Claude lê arquivos naquele diretório, não no início da sessão) | Regras específicas do módulo (por exemplo, convenções diferentes em |
A maioria dos times precisa apenas do arquivo na raiz do projeto. Faça commit no git para que todo o time se beneficie.
Como é carregado (e quanto custa)
Os arquivos no seu diretório de trabalho e acima dele são lidos no início da sessão e entregues ao Claude como uma mensagem do usuário imediatamente após o prompt do sistema (não incorporados dentro do prompt do sistema em si). Arquivos CLAUDE.md de subdiretórios são carregados sob demanda depois, quando Claude lê arquivos naquele subdiretório. Não há resumo ou truncamento, e não é relido do disco a cada turno. Se você editar o arquivo durante a sessão, a mudança é detectada na próxima vez que você executar /compact ou abri-lo via /memory; caso contrário, entra em vigor na sua próxima sessão.
Para clientes Claude for Enterprise, o quadro de custos é melhor do que "carregado a cada requisição" poderia sugerir. Claude Code aplica cache de prompt do Anthropic ao CLAUDE.md. A primeira requisição em uma sessão paga o preço total de tokens de entrada do arquivo; requisições subsequentes dentro de aproximadamente cinco minutos uma da outra atingem o cache e são cobradas à taxa muito mais baixa de leitura de cache. O cache é endereçado por conteúdo, então qualquer mudança no CLAUDE.md o invalida e a próxima requisição paga preço total novamente.
Na prática, isso significa que um CLAUDE.md considerável custa tokens completos uma vez por sessão, mais uma vez após qualquer intervalo ocioso longo o suficiente para o cache expirar, em vez de uma vez por mensagem. Ainda vale a pena manter o arquivo enxuto para espaço de janela de contexto e relação sinal-ruído, mas você não precisa racionar linhas puramente para controlar gastos por mensagem. No painel de uso Enterprise, a pegada do arquivo aparecerá quase inteiramente como tokens de leitura de cache em vez de tokens de entrada padrão.
Começando: execute /init
Em qualquer projeto, digite /init. Claude explorará a base de código e rascunhará um CLAUDE.md para você, cobrindo comandos de build, comandos de teste, uma visão geral da estrutura e quaisquer convenções que detectar. Revise o rascunho, remova qualquer coisa imprecisa e faça commit. Isso leva cerca de cinco minutos e compensa permanentemente.
O que realmente pertence a ele
Procure por um arquivo curto e denso em sinal — com aproximadamente 200 linhas ou menos. Cada linha é carregada em contexto a cada requisição, então cada uma deve valer seu custo.
Vale a pena incluir:
Comandos — como fazer build, testar, lint e executar localmente. Claude executará estes, então a precisão importa.
Convenções — nomeação, tratamento de erros, layout de arquivo e decisões "usamos X, não Y".
Arquitetura em três frases — quais são as peças principais e como se comunicam.
Restrições rígidas — por exemplo, "nunca escreva no banco de dados de produção a partir de testes," "todas as rotas de API precisam de middleware de autenticação," ou "não edite
generated/."Armadilhas conhecidas — os problemas em que cada novo engenheiro tropeça.
Não vale a pena incluir:
Documentação completa de API (Claude pode ler o código diretamente).
Changelogs ou histórico.
Qualquer coisa que já seja óbvia na árvore de arquivos.
Regras aspiracionais que o time não segue realmente.
Com que frequência atualizá-lo
Trate-o como um documento de onboarding vivo, não como uma especificação.
Depois de
/init— revise uma vez para limpar o rascunho gerado.Quando Claude erra algo duas vezes — esse é o sinal de que uma regra está faltando. Adicione uma linha para resolvê-lo.
Quando convenções mudam — por exemplo, um novo framework, test runner ou conjunto de regras de lint.
Revisão trimestral — delete qualquer coisa obsoleta, já que instruções desatualizadas são piores que nenhuma.
Você também pode adicionar durante a sessão: abra /memory para editar o arquivo diretamente, ou apenas peça ao Claude para "lembrar" de uma regra e ele a anexará ao CLAUDE.md correto para você.
Parte 2 — Hábitos de prompt que compensam em Claude Code
Estes não são dicas genéricas de engenharia de prompt; são os hábitos que mais importam especificamente quando Claude está lendo e editando uma base de código real.
1. Declare o resultado, não os passos
Claude pode explorar a base de código por si mesmo. Diga-lhe o que você quer e por quê, e deixe-o descobrir onde.
❌ "Abra userService.ts, encontre a função validate, adicione uma verificação nula na linha 42."
✅ "Usuários sem email estão travando a etapa de validação. Faça-a lidar com isso graciosamente e adicione um teste."
2. Dê-lhe o erro, textualmente
Cole o rastreamento de pilha completo em vez de resumi-lo. O nome exato do arquivo, número da linha e mensagem são o que permite ao Claude encontrar o local certo rapidamente.
3. Escopo de tarefas grandes com Plan Mode primeiro
Para qualquer coisa tocando mais de um par de arquivos, pressione Shift+Tab duas vezes para entrar em plan mode (o primeiro pressionamento entra em acceptEdits) e pergunte:
"Planeje como você adicionaria rate limiting à API pública. Não mude nada ainda."
Revise o plano, ajuste-o na conversa, depois mude de modo e diga "faça o passo 1." Isso detecta mal-entendidos antes que se transformem em um diff de doze arquivos.
4. Aponte para arquivos quando você já os conhece
Claude pode pesquisar a base de código por conta própria, mas se você já conhece o arquivo relevante, diga — é mais rápido e usa menos tokens. Use @ para referenciar caminhos, por exemplo @src/auth/login.ts.
5. Diga como "pronto" se parece
Exemplos incluem "testes passam," "corresponde ao estilo dos outros handlers," ou "sem novas dependências." Declarar critérios de aceitação antecipadamente é mais eficiente do que várias rodadas de revisão.
6. Uma tarefa por conversa; /clear entre elas
Sessões longas acumulam ruído. Quando você muda de "corrigir o bug de login" para "refatorar o módulo de faturamento," execute /clear e comece do zero. Seu CLAUDE.md carrega o contexto durável para frente, então o histórico de chat não precisa.
7. Corrija-o como um colega, não como um mecanismo de busca
Se a primeira resposta estiver errada, você não precisa reformular toda a requisição. Simplesmente diga o que está errado — por exemplo, "Isso muda a API pública; mantenha a assinatura igual." Claude manterá tudo mais e ajustará apenas esse ponto.
Referência rápida
Quer… | Faça isto |
Gere um |
|
Veja que memória Claude está usando |
|
Adicione uma regra durante a sessão | Abra |
Comece do zero mas mantenha a memória do projeto |
|
Referencie um arquivo específico em um prompt |
|