Ideia principal

Dizer que o código é a fonte de verdade do produto soa espontaneamente como "a documentação não serve mais". A oposição está mal colocada: ela não é entre o código e os documentos, é entre duas funções que os documentos cumprem e que não distinguimos.

Um artefato que descreve diz o que o produto faz: uma página de suporte sobre uma funcionalidade, um changelog, uma especificação funcional do estado atual, uma documentação comercial sobre o que é possível. Tudo isso é dedutível do repositório, portanto regenerável, portanto sem interesse em manter.

Um artefato que explica diz por quê: as conversas e os raciocínios que levaram a uma escolha, a decisão de produto e as alternativas descartadas, a razão pela qual uma decisão substitui outra. Nada disso está no código, e nada vai recuperar. A isso se soma o que não se deduz de nenhum repositório porque vem de fora: um compromisso contratual, uma restrição regulatória, um documento externo.

O critério de triagem não é, portanto, a forma do artefato nem seu autor, é a pergunta à qual ele responde. Aliás, um mesmo documento pode pertencer aos dois, e então deve ser cortado em vez de classificado.

O corte é feito até dentro de uma ficha. Numa ficha de objeto de produto, o corpo descreve a realidade tal como ela está no código e é regenerado; o bloco dos desvios carrega o julgamento — o que diverge do que gostaríamos — e é mantido. A regra que mantém os dois separados é absoluta e cabe numa frase: um desvio nunca modifica o corpo da ficha. Sem essa fronteira escrita, a primeira regeneração leva embora a parte que custou caro para produzir, já que é a única que não se encontra em lugar nenhum.

Camada trazida por "Escrevi a ontologia de um produto. Três vezes, achei que tinha terminado." (2026-08-11).

Por que isso importa

É isso que torna o deslocamento para o código operável sem destruição. Sem essa linha, você escolhe entre guardar tudo — e pagar a divergência — e jogar tudo fora — e perder o porquê, cuja falta só aparece no momento em que alguém reabre uma decisão.

Isso também dá um teste para aplicar a qualquer documento de produto antes de decidir seu destino: ele contém uma frase que nenhuma leitura do repositório permitiria escrever?

Nuances e limites

O corte é mais nítido na teoria do que na leitura de um documento real: uma especificação mistura o tempo todo o comportamento esperado e o motivo que o fez ser escolhido, muitas vezes na mesma frase.

E o que explica não está livre de caducidade. Um raciocínio guardado continua preso a um contexto de época; ele não diverge do produto como uma descrição, ele simplesmente fica menos pertinente sem que nada sinalize isso.

Questões em aberto

• O que, numa organização, capta as explicações no momento em que elas acontecem, se elas são ditas em reunião e em revisão de código em vez de escritas?