Idée principale

Autour d'un produit logiciel gravite une famille d'artefacts : la spécification, la maquette Figma, le changelog, la documentation de support, la documentation commerciale. Aucun ne dit ce que le produit fait aujourd'hui. Ils disent ce qu'on a voulu qu'il fasse, ou ce qu'il faisait au moment où quelqu'un les a écrits.

Le code, lui, ne peut pas se tromper sur l'état du produit : il est cet état. Un comportement présent dans le dépôt est un comportement du produit, qu'il ait été spécifié ou non ; un comportement écrit dans une spécification et absent du dépôt n'existe pour personne.

Cela ne fait pas du code un bon support de lecture, ni un remplaçant des autres artefacts. Cela fixe seulement une hiérarchie de fiabilité : en cas de désaccord entre le dépôt et un document, c'est le document qui a tort.

Le même classement vaut pour les artefacts de coordination : un ticket et une spécification se désynchronisent l'un de l'autre et du produit dès la réalisation, et la seule réalité durable reste ce qui est livré — le code, le comportement observable, et la documentation maintenue depuis eux.

Couche apportée par « Le backlog n'est pas un dépotoir : c'est un outil d'action » (2026-06-03).

Faire foi sur l'état du produit ne revient pas à le décrire. Le code établit comment le produit fonctionne — les champs, les valeurs possibles, les traitements — et laisse dehors ce qui le rend exploitable : la règle énoncée en une phrase, quand son contrôle est éparpillé dans cinq fichiers ; les cas particuliers d'un objet ; les mots employés par les utilisateurs ; la portée d'une notion quand deux applications mettent un sens différent derrière le même terme. Ces quatre informations ne se trouvent d'ailleurs pas au même endroit : elles se répartissent entre le cœur du code, la base de données, les écrans et les traductions. La hiérarchie de fiabilité reste vraie ; elle ne dispense pas d'écrire le sens par-dessus.

Couche apportée par « J'ai écrit l'ontologie d'un produit. Trois fois, j'ai cru avoir fini. » (2026-08-11).

La hiérarchie se vérifie aussi par le cas où elle est poussée à bout. Sur un outil interne construit sans spécification préalable — quelqu'un se lance, construit, montre, reçoit des demandes, ajuste —, aucun document n'a jamais décrit l'intention, et le produit fonctionne pourtant. L'inverse n'existe pas : il n'y a pas de produit qui fonctionne sans code. La spécification ne disparaît pas de tous les contextes pour autant, mais elle cesse de pouvoir prétendre être durablement la vérité du produit.

Couche apportée par « Quatre jours de vibe coding… » (2026-07-28).

Pourquoi c'est important

Cette hiérarchie est rarement énoncée, alors qu'elle est appliquée en permanence : un développeur qui doit trancher un comportement ambigu va lire le code, pas la spécification. Le dire explicitement change ce qu'on attend des autres artefacts — ils deviennent des vues, datées, et non des références.

Elle donne aussi un critère pour arbitrer un conflit entre deux artefacts sans réunir les auteurs : on ne cherche pas qui a raison, on regarde le dépôt.

Nuances et limites

Le code dit ce que le produit fait, jamais pourquoi. L'intention, l'arbitrage, la contrainte commerciale qui a conduit à ce comportement ne s'y lisent pas — et cette part-là reste, elle, dans les documents et dans les échanges projet.

La règle vaut sur le comportement livré, pas sur le comportement voulu : un bug est dans le code et fait pourtant partie de ce qu'il faudra changer.

Questions ouvertes

• Où loger l'intention d'une décision produit pour qu'elle survive au même titre que le comportement qu'elle a produit ?