# CLAUDE.md: como criar instruções para o Claude Code Crie um CLAUDE.md conciso com contexto, convenções e verificações do projeto e entenda sua diferença para memória automática e permissões. Autoria: Angelo Sebastião Silva Goncalves Publicado: 2026-11-08T14:00:00.000Z Revisado: 2026-10-27T22:11:33.782Z URL canônica: https://nextags.com.br/blog/claude-md-como-criar-instrucoes-para-o-claude-code/ 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](https://code.claude.com/docs/en/memory) 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: ```text 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](https://code.claude.com/docs/en/permissions), 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](https://nextags.com.br/integracoes/claude/) pode ser avaliada separadamente; esse arquivo do Code não configura o agente do AI Hub. ## Fontes - [Instruções e memória do Claude Code](https://code.claude.com/docs/en/memory) - [Controles de permissão no Code](https://code.claude.com/docs/en/permissions)