Dê contexto ao Claude: CLAUDE.md e prompts melhores

Claude Code funciona bem pronto para uso, 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.

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 em seu 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.

Claude procura em alguns lugares e mescla o que encontra, do amplo para o específico:

A maioria dos times precisa apenas do arquivo na raiz do projeto. Faça commit dele no git para que todo o time se beneficie.

CLAUDE.md é lido uma vez, no início da sessão, e colocado verbatim no prompt do sistema do Claude. Não há resumo ou truncamento, e não é relido do disco a cada turno; o mesmo conteúdo permanece em contexto para toda a conversa. Se você editar o arquivo no meio da sessão, a mudança não entra em vigor até que você inicie uma nova sessão.

Para clientes Claude for Enterprise, o panorama de custos é melhor do que "carregado a cada requisição" poderia sugerir. Claude Code aplica cache de prompt do Anthropic ao prompt do sistema, que inclui 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 em 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.

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.

Procure por um arquivo curto e denso em sinal — algumas centenas de linhas no máximo. Cada linha é carregada em contexto a cada requisição, então cada uma deve valer seu custo.

Vale a pena incluir:

Não vale a pena incluir:

Trate-o como um documento de onboarding vivo, não como uma especificação.

Você também pode adicionar a ele no meio da sessão: digite # seguido de uma instrução (por exemplo, # sempre use async/await, nunca .then()) e Claude oferecerá anexá-lo ao CLAUDE.md correto para você.

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.

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."

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.

Para qualquer coisa tocando mais de um par de arquivos, pressione Shift+Tab para entrar em Plan Mode 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.

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.

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.

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.

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.