CLAUDE.md é o arquivo de instruções que você escreve para orientar o Claude Code no projeto. Ele deve registrar contexto e regras úteis para decisões recorrentes, com clareza suficiente para serem mantidos pela equipe. Um bom arquivo explica como trabalhar naquele código; não tenta substituir a revisão da entrega ou os controles de permissão.
Comece pelas correções que você repete nas sessões: convenções, limites de escopo e verificações que costumam ser esquecidas. Essas informações oferecem um ponto de partida melhor do que copiar um arquivo extenso preparado para outro repositório.
O que pertence ao arquivo
A documentação de memória do Claude Code distingue o CLAUDE.md, escrito pelo usuário, da memória automática de aprendizados. São formas de contexto com funções e responsáveis diferentes.
Salve em ./CLAUDE.md ou ./.claude/CLAUDE.md. Na sessão, /context mostra os carregados em Memory files; /memory permite abrir e editar.
No arquivo mantido pela equipe, priorize orientações que devem continuar verdadeiras entre tarefas. Uma regra sobre a origem de comandos de verificação pode permanecer útil. O estado temporário de uma investigação costuma precisar de outro lugar.
Use perguntas concretas para selecionar o conteúdo. O que alguém precisa saber antes de alterar o projeto? Quais decisões não podem ser tomadas silenciosamente? Como reconhecer uma entrega revisável?
Se uma frase não ajuda a responder nenhuma dessas perguntas, considere removê-la. A utilidade do arquivo não cresce necessariamente com seu tamanho.
Estruture por decisões, não por advertências genéricas
Uma organização prática pode separar contexto, limites e verificação. Cada parte deve orientar uma ação reconhecível.
| Parte | Informação útil |
|---|---|
| Contexto | Finalidade do projeto e termos que afetam a interpretação do código |
| Escopo | O que precisa de análise antes de mudar |
| Convenções | Padrões realmente adotados pela equipe |
| Verificação | Onde localizar comandos e quais evidências registrar |
| Entrega | Como explicar arquivos alterados, dúvidas e limitações |
Evite regras vagas como “faça tudo com qualidade”. Elas não ajudam a escolher entre duas soluções. Uma instrução mais útil pede que o relatório relacione cada alteração ao comportamento solicitado.
Também não registre uma preferência pessoal como convenção consolidada sem discutir com quem mantém o projeto. O arquivo deve representar o trabalho da equipe, não uma disputa escondida em instruções.
Escreva uma primeira versão curta
O exemplo autoral abaixo mostra um corpo de instruções que pode ser adaptado. Ele evita pressupor tecnologias e comandos que precisam ser confirmados no repositório:
Contexto
Trabalhe a partir do comportamento solicitado e dos arquivos existentes.
Explique as dúvidas que não podem ser resolvidas pela leitura.
Escopo
Antes de ampliar a mudança, justifique a relação com o pedido.
Preserve decisões do produto documentadas no projeto.
Não transforme uma hipótese comercial em regra implementada sem confirmação.
Verificação
Localize as verificações mantidas pelo projeto e explique quais são pertinentes.
Diferencie o que foi executado do que apenas foi recomendado.
Registre falhas ou etapas não concluídas com o motivo observado.
Entrega
Relacione os arquivos alterados ao resultado solicitado.
Informe pendências que a próxima pessoa precisa conhecer.
A adaptação deve acrescentar informações verificadas sobre o seu projeto. Se existe uma convenção importante, mostre onde ela aparece ou explique quem a mantém.
Revise o arquivo junto com o processo
Faça a revisão das instruções a partir das tarefas da equipe. Evite que orientações de uma parte específica dominem trabalhos sem relação com ela.
Quando uma regra mudar, identifique a versão anterior e o motivo. Uma instrução desatualizada pode continuar influenciando novas atividades mesmo depois de a equipe ter adotado outro procedimento.
Revise também as repetições. Se dois trechos descrevem a mesma condição com palavras diferentes, escolha a formulação mais clara. Se há uma contradição, resolva a decisão antes de acrescentar outra exceção.
Não trate o arquivo como bloqueio técnico
Segundo o guia de permissões, os controles de acesso pertencem ao ambiente. O texto do CLAUDE.md não é uma barreira técnica por si só.
Uma regra que pede análise antes de uma alteração pode ser útil para o procedimento, mas deve coexistir com o modo de permissão adequado ao trabalho. Separe instrução, autorização e revisão.
Essa distinção também ajuda a investigar falhas. Quando uma ação ocorreu fora do escopo, examine a clareza da tarefa e a configuração disponível, em vez de concluir que basta escrever uma proibição mais longa.
Como avaliar se a orientação está funcionando
Escolha uma tarefa representativa e observe quais instruções foram úteis à entrega. A explicação relacionou os arquivos ao pedido? As verificações foram identificadas corretamente? As dúvidas continuaram visíveis?
Registre correções específicas e ajuste o arquivo quando elas revelarem uma regra duradoura. Não acrescente cada detalhe de uma única sessão ao contexto permanente.
Ao final, a equipe deve conseguir ler o CLAUDE.md e reconhecer como pretende trabalhar naquele projeto. Para a parte de atendimento, a integração Claude da Nextags pode ser avaliada separadamente; esse arquivo do Code não configura o agente do AI Hub.
Fontes e referências
Regras e recursos dos canais podem mudar. Confira as condições atuais nas fontes oficiais antes de colocar sua operação no ar.
Conteúdo de Angelo Sebastião Silva Goncalves. Preparado com apoio de IA. Consulte as fontes e os critérios editoriais. Conheça nossos critérios editoriais e como solicitar uma correção.
