Escrevendo um bom CLAUDE.md

Específico vence vago

A qualidade da escrita determina o quanto o agente segue o CLAUDE.md, e o fator número um é a especificidade. Instruções vagas dão margem a interpretação e são seguidas de forma inconsistente. Compare: formatar o código direito não diz nada verificável, enquanto usar duas casas de indentação é uma regra clara, que o agente cumpre e você confere. O mesmo vale para testar as mudanças contra rodar determinado comando antes de commitar, e para manter tudo organizado contra os manipuladores de rota ficam em tal pasta. Troque adjetivos por fatos e a adesão dispara.

A razão é simples: o CLAUDE.md entra no contexto como orientação, não como código executável, então o agente precisa interpretar o que você quis dizer. Quanto menos espaço para interpretação, mais fiel o resultado. Uma boa pergunta ao escrever cada linha é duas pessoas diferentes fariam a mesma coisa lendo isto? Se a resposta for não, a instrução ainda está vaga e vale reescrever. Esse rigor de tornar cada regra verificável é o que separa um CLAUDE.md que o agente respeita de um que ele mais ignora do que segue.

Conciso e bem estruturado

Depois da especificidade, vem o tamanho. O CLAUDE.md é lido no início de toda sessão e ocupa espaço na janela de contexto, aquele limite de memória de trabalho do modelo. Um arquivo enorme gasta contexto e, curiosamente, reduz a adesão: quanto mais coisa, mais o essencial se dilui e menos o agente segue cada ponto. A recomendação prática é mirar menos de cerca de 200 linhas. Se o seu arquivo está crescendo demais, é sinal de que parte dele deveria virar regra por tipo de arquivo ou skill, temas da próxima aula, para carregar só quando for relevante.

A estrutura também importa. O agente lê um documento organizado como um leitor humano lê: títulos que separam assuntos e listas que destacam pontos são muito mais fáceis de seguir que parágrafos densos e longos. Agrupe as instruções por tema, como comandos, estilo de código, arquitetura, com um título para cada bloco. Isso não é só estética; é o que permite ao agente localizar rapidamente a regra certa para a situação. Um CLAUDE.md bem diagramado, curto e com cabeçalhos claros, é seguido com muito mais consistência que um bloco corrido de texto.

Por fim, um detalhe de higiene: evite contradições. Como todos os níveis e regras se somam no contexto, duas orientações opostas para o mesmo caso deixam o agente sem norte, e ele pode seguir qualquer uma. Ao adicionar uma regra nova, cheque se ela não briga com algo que já estava lá, inclusive em arquivos de subpasta e nos níveis de usuário e organização. Revisar o CLAUDE.md periodicamente, tirando o que envelheceu, mantém o arquivo confiável. Um documento enxuto, específico, estruturado e coerente é o que faz o agente trabalhar de verdade do seu jeito.

Começar com o comando de inicialização

Você não precisa escrever o CLAUDE.md do zero, encarando uma página em branco. O Claude Code tem um comando de inicialização que gera um rascunho analisando o seu projeto: ele descobre comandos de build e teste, convenções e o layout, e monta um primeiro CLAUDE.md com isso. Se já existir um, ele sugere melhorias em vez de sobrescrever. Esse rascunho é um ótimo ponto de partida, mas não o ponto final. A partir dele, você refina, adicionando o que o agente não teria como adivinhar: decisões de arquitetura, o que evitar, as suas regras do tipo sempre.

Com um bom CLAUDE.md escrito, específico, conciso, estruturado e nascido do comando de inicialização, você já colhe grande parte do valor da memória de projeto. A próxima aula mostra como escalar isso em projetos maiores, com regras por tipo de arquivo, que carregam só quando o agente toca em certos arquivos, e imports, que quebram o conteúdo em pedaços organizados. São ferramentas para quando o essencial no CLAUDE.md não basta e você precisa de contexto específico sem estourar o tamanho recomendado do arquivo principal.