Documente no dia do marco, em prosa, ou o porquê da decisão some

Documentação, no senso comum, é tarefa de fechamento. O projeto termina, sobra uma tarde, alguém escreve o que foi feito: adicionamos X, corrigimos Y, migramos Z. É um changelog, a lista de mudanças. E o changelog tem um mérito real: é rápido de escrever e não atrapalha quem está com a mão no código.

Só que ele guarda uma coisa e perde outra. Guarda o que mudou. Perde por que valeu a pena mudar. E o porquê é justamente o que ninguém consegue reconstruir meses depois — nem quem escreveu, nem o agente novo que entra no projeto e precisa decidir o próximo passo.

Pense numa decisão que parecia óbvia e não funcionou. Uma mudança de rota no meio do caminho, tomada às onze da noite com o prazo em cima. Se isso não é escrito na hora, em prosa, some. O changelog do fim do projeto vai dizer "trocamos a abordagem A pela B" e mais nada. Por isso eu documento no dia do marco, como quem conta o que aconteceu, e não no fim, em lista.

O arquivo de status carrega o dado; a narrativa carrega o julgamento

No meu sistema são dois arquivos, e não por capricho. O PROJECT_STATUS.md é o de status técnico: métricas, o hash do último commit, a lista de arquivos alterados, o que está bloqueado. O narrative.md é o de narrativa: a decisão que estava na mesa, por que o caminho óbvio não deu certo, o que eu aprendi, o momento em que a rota mudou.

A regra de bolso para separar os dois é simples. Se um parágrafo poderia entrar no arquivo de status, ele pertence lá, e não se repete na narrativa. Métrica é dado, e dado vai para o status. A narrativa fica com a causalidade e com o julgamento humano, que nenhum histórico de commits reconstrói.

Quem dispara essa separação é uma rotina automatizada no Claude Code, que roda a cada marco. São nove passos encadeados. Os que importam aqui são estes: ler o estado atual via git, atualizar o arquivo de status técnico, sobrescrever o arquivo de handoff para o próximo agente, acrescentar um capítulo de narrativa, registrar a lição se uma lição apareceu, atualizar os itens pendentes do backlog, fazer o commit e subir tudo. Eu não escolho se vou documentar. A rotina escolhe por mim.

Escreva o capítulo para quem vai ler a frio daqui a seis meses

Um capítulo de narrativa é prosa corrida. Não tem bullets. Não enumera: explica o que causou o quê. O molde "fizemos X, depois Y, depois Z" é proibido — se o capítulo cabe nele, é um changelog com parágrafos.

O changelog registra o que mudou. A narrativa registra por que valeu a pena mudar.

O alvo de leitura está declarado na rotina: alguém que não é especialista consegue ler o capítulo a frio em uns 90 segundos e sair sabendo o que aconteceu, por que importou e o que foi feito a respeito. Na prática, esse alguém sou eu, seis meses depois. Em português corrente, sem o vocabulário de changelog que só faz sentido para quem estava lá.

Cada capítulo tem de 3 a 5 parágrafos, algo entre 500 e 900 palavras, e vai sempre no fim do arquivo. Nunca reescrevo capítulos anteriores. Se uma decisão de um capítulo antigo se mostrou errada, o capítulo novo conta isso; o antigo continua lá, com a confiança que eu tinha na época. Esse é o registro que interessa: o que eu achava antes de saber.

A disciplina não pode depender de lembrar

Sem uma rotina executável, o que acontece é previsível. Quem termina um trabalho pula a atualização da documentação. Escreve uma lição sem classificar direito. Esquece de atualizar o arquivo de handoff, e o próximo agente começa a sessão às cegas. Ou usa um comando de git genérico demais e leva junto um arquivo que não devia entrar no commit. Nenhum desses erros é de má vontade; todos são de memória.

A saída foi transformar a rotina numa sequência fixa de passos, não numa lembrança. Isso torna a disciplina não opcional, e tem um custo que prefiro declarar: rodar a sequência a cada marco é uma pausa no ritmo. Parar de programar, revisar o que mudou, escrever prosa. É exatamente essa pausa que se pula quando o prazo aperta. Eu pulava. A rotina não deixa.

Antes de juntar as partes, testei cada passo isolado, contra um caso concreto. Um desses testes pegou um filtro de diretório frouxo demais: a comparação era por substring, e dispararia para qualquer caminho que contivesse o nome do projeto, inclusive subpastas de sandbox que não deveriam contar. Num changelog, isso viraria uma linha: "corrigido filtro de diretório". Na narrativa, é o parágrafo que explica por que eu testo cada passo separado antes de confiar na sequência inteira.

O teste é simples de rodar. Pegue um capítulo de narrativa de seis meses atrás e leia a frio. Se ele explica por que a decisão foi tomada, e não só o que foi feito, a disciplina está funcionando. Se o único jeito de reconstruir a decisão é perguntar para quem estava lá, ou adivinhar, a documentação virou um changelog disfarçado de narrativa.

Eu mudo de ideia no dia em que um "fizemos X, depois Y, depois Z" bastar para reconstruir uma decisão de meses atrás sem contexto extra. Ainda não aconteceu. Até acontecer, o capítulo se escreve no dia do marco, não no dia em que sobra tempo.