Main idea

A family of artifacts orbits a software product: the specification, the Figma mockup, 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 at the moment someone wrote them.

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

That does not make the code a good medium to read, nor a replacement for the other artifacts. It only fixes a hierarchy of reliability: in case of disagreement between the repository and a document, it is the document that is wrong.

The same ranking holds for coordination artifacts: a ticket and a specification drift out of sync with each other and with the product from the moment of implementation, and the only lasting reality is what gets delivered — the code, the observable behavior, 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 outside 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 the users employ; the scope of a notion when two applications put a different meaning behind the same term. Those four pieces of information are not even found in the same place: they are spread across the core code, the database, the screens and the translations. The hierarchy of reliability remains true; 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 also shows up in the case where it is pushed to the limit. On an internal tool built with no prior specification — someone dives in, builds, shows it, receives requests, adjusts — no document ever described the intent, and the product works all the same. The reverse does not exist: there is no product that works without code. The specification does not disappear from every context for all that, but it stops being able to claim it is lastingly the truth of the product.

Layer added by "Four Days of Vibe Coding as a Rusty PM" (2026-07-28).

Why it matters

This hierarchy is rarely stated, although it is applied constantly: a developer who has to settle an ambiguous behavior will read the code, not the specification. Saying it explicitly changes what you expect from the other artifacts — they become views, dated, and not references.

It also gives a criterion for settling a conflict between two artifacts without gathering the authors: 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 that behavior cannot be read in it — and that part stays in the documents and in the project conversations.

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

Open questions

• Where should the intent behind a product decision be lodged so that it survives as well as the behavior it produced?