Main idea

A family of artefacts orbits a software product: the specification, the Figma mock-up, the changelog, the support documentation, the sales documentation. None of them says what the product does today. They say what it was meant to do, or what it did when someone wrote them.

The code, by contrast, cannot be wrong about the state of the product: it is that state. A behaviour present in the repository is a behaviour of the product, whether it was specified or not; a behaviour written in a specification and absent from the repository exists for no one.

That does not make the code a good medium for reading, nor a replacement for the other artefacts. It only sets a hierarchy of reliability: when the repository and a document disagree, it is the document that is wrong.

The same ranking holds for coordination artefacts: a ticket and a specification fall out of sync with each other and with the product from the moment the work is built, and the only lasting reality is what gets delivered — the code, the observable behaviour, and the documentation maintained from them.

Layer added by "The Backlog Is Not a Dumping Ground: It's a Tool for Action" (2026-06-03).

Being authoritative about the state of the product is not the same as describing it. The code establishes how the product works — the fields, the possible values, the processing — and leaves out what makes it usable: the rule stated in one sentence, when its enforcement is scattered across five files; an object's special cases; the words users actually use; the scope of a notion when two applications put a different meaning behind the same term. Those four pieces of information are not even in the same place: they are spread across the core code, the database, the screens and the translations. The hierarchy of reliability still holds; it does not exempt you from writing the meaning on top of it.

Layer added by "I wrote a product's ontology. Three times, I thought I was done." (2026-08-11).

The hierarchy is also borne out by the case where it is pushed to the limit. On an internal tool built with no prior specification — someone dives in, builds, shows it, gets requests, adjusts — no document ever described the intent, and yet the product works. The reverse does not exist: there is no product that works without code. The specification does not vanish from every context for all that, but it can no longer claim to be the lasting truth of the product.

Layer added by "Four days of vibe coding in the shoes of a rusty PM" (2026-07-28).

Layer added by "Ontology-Driven Design: what if the ontology became the safety net for AI-generated code?" (2026-10-29). When coding agents modify the software, the hierarchy is completed by a three-way division: the code is authoritative on the implemented behaviour, the business ontology on meaning, and the intent behind the request on why that meaning can change. Being authoritative on behaviour does not make the code right when it contradicts the model: a gap introduced without any request to justify it is drift to be fixed, not a new truth.

Why it matters

This hierarchy is rarely stated, although it is applied all the time: a developer who has to settle an ambiguous behaviour reads the code, not the specification. Saying it explicitly changes what you expect from the other artefacts — they become views, dated, not references.

It also gives a criterion for settling a conflict between two artefacts without getting the authors together: you do not look for who is right, you look at the repository.

Nuances and limits

The code says what the product does, never why. The intent, the trade-off, the commercial constraint that led to a behaviour cannot be read in it — that part stays in the documents and in the project conversations.

The rule holds for delivered behaviour, not intended behaviour: a bug is in the code and is nonetheless part of what will have to change.

Open questions

• Who notices that a product intent has disappeared, while the behaviour it produced keeps running without it?