Como escrever um bom `Claude.md`

• Um LLM é uma função sem estado, então o CLAUDE.md funciona como o documento central que apresenta a base de código ao Claude em cada sessão
• O arquivo deve resumir de forma concisa o WHAT (estrutura), o WHY (objetivo) e o HOW (modo de funcionamento) do projeto, e excesso de comandos desnecessários leva à queda de desempenho
• O Claude pode ignorar o conteúdo de CLAUDE.md se considerar que ele tem baixa relevância, de acordo com as instruções da mensagem de sistema
• Um arquivo eficaz inclui apenas informações curtas e universalmente aplicáveis, e diretrizes detalhadas devem ser separadas em documentos distintos para serem gerenciadas com Progressive Disclosure
• O CLAUDE.md é o ponto de maior impacto no harness do agente, portanto deve ser escrito manualmente com cuidado, em vez de ser gerado automaticamente

---

A ausência de estado dos LLMs e o papel do CLAUDE.md

• LLMs usam pesos fixos no momento da inferência e não mantêm aprendizado nem memória entre sessões
  • Portanto, para o modelo entender a base de código, todas as informações precisam ser fornecidas como tokens de entrada
• Agentes de programação como o Claude Code precisam gerenciar memória de forma explícita, e o CLAUDE.md é o único arquivo incluído automaticamente em todas as conversas
• Por isso, os três pontos a seguir são essenciais
  1. No início de uma sessão, o Claude não sabe nada sobre a base de código
  2. As informações necessárias precisam ser reapresentadas em toda sessão
  3. O meio padrão para isso é o CLAUDE.md

Onboarding da base de código: WHAT, WHY, HOW

• O CLAUDE.md funciona como um documento de onboarding para ajudar o Claude a entender o projeto
  • WHAT: fornece um mapa do código, como stack técnica, estrutura do projeto e organização do monorepo
  • WHY: explica o propósito e a função de cada componente
  • HOW: descreve como executar tarefas reais, como build, testes e typecheck
• Ainda assim, listar todos os comandos é ineficiente, e o ideal é incluir apenas o mínimo necessário de informação

Por que o Claude ignora o CLAUDE.md

• O Claude Code insere o seguinte lembrete de sistema na mensagem do usuário

  IMPORTANT: this context may or may not be relevant...
  

  • Por isso, o Claude pode ignorar esse contexto se julgar que ele não é relevante para a tarefa atual
• Quanto mais instruções não universais houver no arquivo, maior a chance de ele ser ignorado
• Presume-se que a Anthropic tenha adicionado isso porque a qualidade dos resultados melhorou quando instruções desnecessárias eram ignoradas

Princípios para escrever um bom CLAUDE.md

Less (instructions) is more

• Um LLM consegue seguir de forma estável cerca de 150 a 200 instruções
  • Quanto menor o modelo, mais abrupta é a queda de desempenho, e menos adequado ele é para tarefas em múltiplas etapas
• O prompt de sistema do Claude Code já inclui cerca de 50 instruções
  • Portanto, o CLAUDE.md deve conter apenas o mínimo de instruções universais e essenciais
• À medida que o número de instruções aumenta, a qualidade de execução de todas elas se degrada de forma uniforme

Tamanho do arquivo e escopo de aplicação

• LLMs funcionam melhor com contexto focado e altamente relevante
• Como o CLAUDE.md é incluído em todas as sessões, ele deve manter somente informações universalmente aplicáveis
• Em geral, recomenda-se mantê-lo com menos de 300 linhas, e de preferência ainda menor
  • O arquivo de exemplo da HumanLayer tem menos de 60 linhas

Progressive Disclosure

• Em projetos grandes, é difícil colocar tudo em um único arquivo, então recomenda-se a abordagem de Progressive Disclosure
  • Diretrizes detalhadas devem ser separadas em arquivos Markdown dentro da pasta agent_docs/
  • Ex.: building_the_project.md, running_tests.md, code_conventions.md etc.
• O CLAUDE.md deve conter apenas a lista desses arquivos, uma breve descrição e a instrução para que o Claude os leia quando necessário
• Em vez de snippets de código, use referências file:line para manter a atualidade
• Isso é semelhante ao conceito de Claude Skills, mas com foco em gerenciamento de instruções, e não em uso de ferramentas

Claude não é um linter

• Incluir diretrizes de estilo de código no CLAUDE.md é ineficiente
  • LLMs têm custo alto, são lentos e são menos determinísticos do que um linter
• Regras de estilo são aprendidas naturalmente a partir dos padrões do código existente, então instruções separadas são desnecessárias
• Para formatação, use linters com correção automática (como Biome) e passe ao Claude apenas o resultado das correções
• Se necessário, use Stop Hook ou Slash Command para automatizar formatação e validação

Não gere automaticamente

• Não se recomenda um CLAUDE.md criado com o comando /init ou recursos de geração automática
  • Isso porque o arquivo é um ponto de alta alavancagem que afeta todas as sessões e resultados
• Uma única linha de instrução errada pode causar efeitos em cadeia negativos em toda a qualidade do código
• Por isso, cada frase deve ser revisada com cuidado e escrita manualmente

Conclusão

• O CLAUDE.md é um documento para fazer o onboarding do Claude na base de código, e deve definir com clareza WHY, WHAT e HOW
• As instruções devem ser minimizadas, contendo apenas conteúdo universal e conciso
• Com Progressive Disclosure, apenas as informações necessárias são fornecidas gradualmente
• Não use o Claude como linter; em vez disso, combine ferramentas dedicadas, hooks e comandos
• Em vez de geração automática, é preciso redação manual cuidadosa para maximizar a qualidade de todo o harness

[GN⁺]

Comentários do Hacker News

• O Claude às vezes tende a ignorar as instruções em CLAUDE.md
  Quanto mais informação sem relação com a tarefa específica houver no arquivo, menos o Claude segue essas instruções
  Um amigo pediu ao Claude para chamá-lo de “Mr Tinkleberry”, e toda vez que o Claude esquecia isso dava para perceber que ele estava ignorando o arquivo

• Eu já uso há algum tempo a abordagem de índice
  Separo as instruções por tarefa em arquivos markdown diferentes, e no CLAUDE.md deixo só a lista e uma breve descrição
  Isso ajuda a manter a janela de contexto limpa
  Meu arquivo de exemplo pode ser visto aqui

  • Eu também tentei esse mesmo método, mas os resultados foram inconsistentes
    O Claude quase nunca realmente lia os outros arquivos de documentação

• Sinto que, quando dou contexto demais ao Claude, a qualidade acaba piorando
  Por isso sempre mantenho duas versões do código

  1. o código original, sem comentários e sem espaços em branco
  2. o código com comentários
     Para o LLM, só entrego a primeira versão
     Acho que a relação entre compute e informação é o ponto principal. A capacidade de processamento é limitada
  • Tive uma experiência parecida, mas colocar conteúdo repetitivo em um arquivo de notas do Claude aumentou a eficiência
    Não precisa colocar tudo, mas incluir a informação essencial teve um ROI alto
    O Claude funciona bem em projetos comuns, mas frequentemente se confunde com frameworks ou ferramentas novas
  • Você disse que mantém duas versões do código; tenho curiosidade sobre como gerencia essa consistência
    Queria perguntar se usa algum script para remover comentários e espaços em branco depois das alterações
  • Acho que, dentro dos arquivos de documentação, é preciso manter alta a densidade de informação
  • Você disse que não entrega ao LLM a versão com comentários, mas fiquei curioso sobre como isso é implementado na prática
  • No fim, a atenção é finita. Se você coloca contexto demais, o foco se dispersa

• Na verdade, existe uma solução mesmo sem toda essa configuração complexa
  É simplesmente documentar o código com clareza
  Se cada arquivo explicar de forma concisa o que faz, isso por si só já funciona como prompt
  Basta usar README.md de forma ativa
  Como o LLM já foi treinado com informação pública, não há necessidade de inventar algo novo

  • Mas, ao escrever documentação para IA, é preciso uma abordagem diferente da documentação para leitores humanos
    O conselho genérico de “documente bem o código” não se encaixa nesse contexto
  • Também acho que a comunidade de IA às vezes reinventa a roda desnecessariamente
    README é ótimo, mas CLAUDE.md tem outro propósito
    Por exemplo, Claude/agents.md tem a função de ser inserido automaticamente no contexto ao acessar certos diretórios
    Em codebases complexas, o gerenciamento de contexto é muito mais importante
  • CLAUDE.md não é apenas um documento simples, e sim uma forma de customizar o prompt inicial do modelo
    Por isso, o conselho “escreva o prompt adequadamente” erra o ponto central
  • Por exemplo, onde você colocaria a regra “consultas ao banco de dados devem sempre usar índices”?
    Se colocar no README, ele acaba assumindo o mesmo papel do CLAUDE.md
    O objetivo do CLAUDE.md é fornecer antecipadamente a informação essencial para que o Claude não precise reler toda a documentação a cada vez
    Humanos lembram, mas o Claude esquece a cada tarefa, então é preciso uma estrutura que reduza esse reonboarding

• Sinceramente, se eu tiver que montar toda essa infraestrutura de IA nesse nível, sinto que é melhor eu mesmo programar

  • Mas configurações de estilo podem ser feitas uma vez só e depois reutilizadas
    Eu separo e gerencio regras comuns e regras específicas de cada projeto
  • A configuração mencionada no artigo leva só algumas horas
    Não usar IA é simplesmente uma perda de produtividade
  • A maior parte da configuração inicial também pode ser delegada ao próprio LLM
  • Na verdade, não exige tanto esforço assim. O problema é tentar otimizar demais as ferramentas
  • O importante é saber se o custo é recorrente ou pontual
    Se a configuração só precisa ser feita uma vez, vale perfeitamente o investimento
    Dizer “configurar é chato” parece a desculpa de quem evita configurar um depurador

• Eu simplesmente copio o código necessário e colo na janela de conversa, usando de forma conversacional
  Hoje em dia os modelos melhoraram bastante, então mesmo sem arquivos .md eles já dão resultados bem bons
  Esses arquivos talvez tragam alguma melhora, mas não acho que sejam uma mágica de produtividade 100x

  • Mas esse é um caso de uso diferente
    O que está sendo discutido aqui é quando o Claude executa a implementação completa de uma funcionalidade ou a correção de um bug por conta própria
  • Minha experiência foi parecida. Já criei um CLAUDE.md uma vez, mas hoje não uso mais
    Só dar o contexto necessário já funciona bem o suficiente. Parece um pouco bikeshedding
  • Ainda assim, se você organizar com antecedência a lista de tabelas e colunas do banco de dados, dá para reduzir repetições

• Eu faço o Claude escrever o próprio CLAUDE.md
  Se você disser “README.md é para os usuários, CLAUDE.md é para você”,
  ele também atualiza automaticamente instruções como “sempre verifique a documentação da API”
  Não preciso conhecer nenhum prompt mágico, desde que o resultado final saia bem

  • Mas fico em dúvida se existe alguma evidência de que instruções escritas pela própria IA sejam melhores do que as escritas por humanos
    Não parece haver motivo para achar que a IA sabe se promptar melhor do que qualquer outra pessoa