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 e a especificidade. Instruções vagas dao margem a interpretacao e são seguidas de forma inconsistente. Compare: formatar o código direito não diz nada verificavel, enquanto usar duas casas de indentacao e 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 adesao dispara.

A razão e simples: o CLAUDE.md entra no contexto como orientacao, não como código executavel, então o agente precisa interpretar o que você quis dizer. Quanto menos espaço para interpretacao, mais fiel o resultado. Uma boa pergunta ao escrever cada linha e duas pessoas diferentes fariam a mesma coisa lendo isto? Se a resposta for não, a instrução ainda esta vaga e vale reescrever. Esse rigor de tornar cada regra verificavel e 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 e 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 adesao: quanto mais coisa, mais o essencial se dilui e menos o agente segue cada ponto. A recomendação prática e mirar menos de cerca de 200 linhas. Se o seu arquivo está crescendo demais, e 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 le um documento organizado como um leitor humano le: títulos que separam assuntos e listas que destacam pontos são muito mais fáceis de seguir que paragrafos 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ó estetica; e o que permite ao agente localizar rapidamente a regra certa para a situação. Um CLAUDE.md bem diagramado, curto e com cabecalhos claros, e seguido com muito mais consistencia que um bloco corrido de texto.

Por fim, um detalhe de higiene: evite contradicoes. Como todos os níveis e regras se somam no contexto, duas orientacoes 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 la, inclusive em arquivos de subpasta e nos níveis de usuário e organização. Revisar o CLAUDE.md periodicamente, tirando o que envelheceu, mantem o arquivo confiavel. Um documento enxuto, específico, estruturado e coerente e o que faz o agente trabalhar de verdade do seu jeito.

Começar com o comando de inicializacao

Você não precisa escrever o CLAUDE.md do zero, encarando uma página em branco. O Claude Code tem um comando de inicializacao que gera um rascunho analisando o seu projeto: ele descobre comandos de build e teste, convencoes e o layout, e monta um primeiro CLAUDE.md com isso. Se já existir um, ele sugere melhorias em vez de sobrescrever. Esse rascunho e 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 inicializacao, 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 pedacos 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.