Ideia principal

Um arquivo CLAUDE.md colocado na raiz de um projeto diz ao agente como trabalhar: as convenções do repositório, os formatos permitidos, o que ele nunca deve fazer. É fácil tomá-lo pela memória do projeto, já que ele está ali, persiste, e o agente o lê toda vez.

Mas ele não é. Esse arquivo enuncia o que deve valer sempre; não diz o que aconteceu. Ele não contém nem o bug encontrado na sexta, nem a correção tentada e depois abandonada, nem a decisão tomada no meio da sessão porque a primeira abordagem não parava de pé. Nada do que aconteceu se deposita ali, e nada ali envelhece.

Dois objetos, dois regimes de escrita. A regra é redigida uma vez, a frio, e vale até que seja mudada. O diário é escrito ao longo do caminho, a quente, e só é verdadeiro na data em que foi registrado. Querer manter os dois em um único arquivo dá ou regras poluídas de anedotas, ou um diário que se acha doutrina.

Por que isso importa

É a falta que ninguém enxerga, porque algo já ocupa o lugar. Um projeto que tem seu arquivo de regras se acha equipado, e mesmo assim se vê reexplicando toda segunda-feira o que foi feito na semana anterior.

O diagnóstico serve além do trabalho com um agente: uma documentação de time, uma carta, um referencial de convenções sofrem exatamente do mesmo ponto cego.

Nuances e limites

A fronteira se move. Uma decisão tomada durante uma sessão e confirmada três vezes vira regra — e o diário é justamente o que permite perceber isso.

E um arquivo de regras mal mantido sempre contém rastros de história: proibições escritas depois de um incidente, que ninguém mais sabe datar.

Questões em aberto

• A partir de quando uma decisão registrada em um diário deve subir para as regras?