Ideia principal

Em volta de um produto de software gravita uma família de artefatos: a especificação, o mockup no Figma, o changelog, a documentação de suporte, a documentação comercial. Nenhum deles diz o que o produto faz hoje. Eles dizem o que alguém quis que ele fizesse, ou o que ele fazia no momento em que alguém os escreveu.

O código, por sua vez, não pode errar sobre o estado do produto: ele é esse estado. Um comportamento presente no repositório é um comportamento do produto, tenha sido especificado ou não; um comportamento escrito numa especificação e ausente do repositório não existe para ninguém.

Isso não faz do código um bom suporte de leitura, nem um substituto dos outros artefatos. Isso só fixa uma hierarquia de confiabilidade: quando o repositório e um documento discordam, é o documento que está errado.

A mesma classificação vale para os artefatos de coordenação: um ticket e uma especificação se dessincronizam um do outro e do produto assim que a implementação começa, e a única realidade duradoura continua sendo o que foi entregue — o código, o comportamento observável e a documentação mantida a partir deles.

Camada trazida por "O backlog não é um depósito de lixo: é uma ferramenta de ação" (2026-06-03).

Fazer fé sobre o estado do produto não equivale a descrevê-lo. O código estabelece como o produto funciona — os campos, os valores possíveis, os processamentos — e deixa de fora o que o torna utilizável: a regra enunciada em uma frase, quando a sua verificação está espalhada por cinco arquivos; os casos particulares de um objeto; as palavras usadas pelos usuários; o alcance de uma noção quando duas aplicações colocam um sentido diferente atrás do mesmo termo. Aliás, essas quatro informações não estão no mesmo lugar: elas se dividem entre o núcleo do código, o banco de dados, as telas e as traduções. A hierarquia de confiabilidade continua verdadeira; ela não dispensa escrever o sentido por cima.

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

A hierarquia também se confirma no caso em que é levada ao limite. Numa ferramenta interna construída sem especificação prévia — alguém começa, constrói, mostra, recebe pedidos, ajusta —, nenhum documento jamais descreveu a intenção, e mesmo assim o produto funciona. O inverso não existe: não há produto que funcione sem código. Nem por isso a especificação desaparece de todos os contextos, mas ela deixa de poder pretender ser, de forma duradoura, a verdade do produto.

Camada trazida por "Quatro dias de vibe coding…" (2026-07-28).

Camada trazida por "Ontology-Driven Design: e se a ontologia virasse a rede de segurança do código gerado por IA?" (2026-10-29). Quando agentes de código alteram o software, a hierarquia se completa com uma divisão em três elementos: o código faz fé sobre o comportamento implementado, a ontologia de negócio sobre o sentido, e a intenção da solicitação sobre o motivo pelo qual esse sentido pode mudar. Fazer fé sobre o comportamento não dá razão ao código quando ele contradiz o modelo: uma divergência introduzida sem que nenhuma solicitação a justifique é uma deriva a corrigir, não uma nova verdade.

Por que isso importa

Essa hierarquia raramente é enunciada, embora seja aplicada o tempo todo: um desenvolvedor que precisa decidir um comportamento ambíguo vai ler o código, não a especificação. Dizer isso explicitamente muda o que esperamos dos outros artefatos — eles viram visões, datadas, e não referências.

Ela também dá um critério para resolver um conflito entre dois artefatos sem reunir os autores: ninguém procura quem tem razão, a gente olha o repositório.

Nuances e limites

O código diz o que o produto faz, nunca por quê. A intenção, a decisão, a restrição comercial que levou àquele comportamento não aparecem nele — e essa parte continua nos documentos e nas conversas do projeto.

A regra vale para o comportamento entregue, não para o comportamento desejado: um bug está no código e, mesmo assim, faz parte do que vai precisar mudar.

Questões em aberto

• Quem percebe que uma intenção de produto desapareceu, enquanto o comportamento que ela produziu continua rodando sem ela?