Comprendre ce qu'on livre

Les deux guides précédents ont installé deux verdicts : la relecture juge le diff, la suite de tests juge le comportement promis. Il reste un angle mort, et il est large. Ce que vous livrez n’est ni un diff ni une suite verte, c’est un artefact complet : les dépendances qu’il embarque, la surface qu’il expose, les chemins qui ne s’exécuteront qu’en production.

Ce guide est la clé de voûte de la Section. La propriété de ce qu’on livre ne se délègue pas, et « comprendre » est le verbe exact : pas relire, pas vérifier, mais être capable d’expliquer. C’est aussi ici que se règle, sans caricature, la question du vibe coding.

---

Le diff n’est pas le colis

Un diff parfaitement relu sous-détermine l’artefact qu’il produit. Trois écarts, systématiques avec du code généré :

• Les dépendances embarquées. Une ligne dans le manifeste, des dizaines de milliers dans le livrable. Le guide 01 notait le réflexe de l’agent : une dépendance ajoutée pour s’épargner dix lignes. La ligne se relit en une seconde, le code qu’elle tire ne sera jamais relu par personne. Chaque dépendance est du code que vous livrez sans l’avoir lu, avec ses transitives, ses mainteneurs, sa surface d’attaque et son rythme de péremption.
• La surface exposée. Routes, ports, permissions, variables d’environnement, options par défaut. Le code généré tend à exposer plus que demandé : l’endpoint de debug resté en place, le CORS permissif « pour que ça marche », le message d’erreur qui raconte la base de données. Rien de tout ça n’échoue à la relecture ligne à ligne. Chaque ligne est correcte ; c’est l’inventaire qui manque.
• Les chemins jamais exécutés. Le code défensif que l’agent produit consciencieusement (branches de repli, catch décoratifs, valeurs par défaut), c’est du code qu’aucun test n’exerce et qu’aucune démo ne montre. Il ne tournera qu’en production, le jour où quelque chose va mal. C’est-à-dire le jour où vous aurez le plus besoin de le comprendre.

Le contrat du guide 02 garantit les comportements qu’il énonce, rien d’autre. La relecture du guide 01 couvre ce qu’elle voit, rien d’autre. Le colis, lui, part entier.

L’ownership ne se délègue pas

La règle posée au premier guide (ne pas merger une ligne qu’on ne saurait pas expliquer) prend ici sa vraie portée : elle ne s’applique pas qu’aux lignes du diff, mais à chaque propriété de l’artefact. Le critère opérationnel, c’est l’incident. À trois heures du matin, en production, pourriez-vous dire pourquoi cette dépendance est là, ce que cet endpoint expose, ce que fait cette branche quand le service d’à côté ne répond pas ? Si la réponse est « il faudrait que je demande à l’agent », vous n’êtes pas propriétaire du système. Vous en êtes le porte-parole.

Expliquer n’est pas paraphraser. L’explication qui compte répond à « pourquoi » et à « que se passe-t-il si ». Et celle de l’agent ne peut pas remplacer la vôtre : sa justification est fluide que le code soit correct ou non, c’est une carte pour naviguer, jamais une preuve (Relire du code qu’on n’a pas écrit). La compréhension peut s’acquérir avec l’aide de l’agent ; elle doit finir dans une tête humaine, parce que c’est le seul endroit d’où l’on répond d’un système.

Précisons ce que l’ownership n’exige pas : tout écrire. Les artisans ont toujours possédé du code qu’ils n’avaient pas écrit. Chaque bibliothèque adoptée l’a été comme une décision, avec ses garanties et ses risques pesés. Déléguer l’écriture est acquis ; c’est déléguer la décision et la compréhension qui constitue la démission.

Le vibe coding, lu honnêtement

L’expression désigne une pratique réelle et productive : générer sans lire les diffs, juger le résultat à l’écran, itérer en langage naturel jusqu’à ce que ça marche. Pour un prototype de week-end, un script d’analyse jetable, une exploration d’API, c’est rationnel. Le coût de l’erreur est quasi nul, l’artefact n’a pas de futur, et exiger là une compréhension ligne à ligne serait du sur-craft. Quiconque balaie le vibe coding d’un revers de main n’a pas compris ce qu’il optimise.

La critique sérieuse est ailleurs. Le vibe coding n’est pas une pratique de développement dégradée, c’est une renonciation délibérée à l’ownership. Légitime exactement là, et seulement là, où il n’y a rien à posséder. La question qui le borne n’est pas morale, elle est patrimoniale : ce code a-t-il un futur ? Des utilisateurs, des données, une maintenance ? Alors quelqu’un devra pouvoir l’expliquer. Un artefact que personne ne comprend n’est pas un produit, c’est un passif qui attend son incident.

Or la frontière ne tient jamais d’elle-même. Le mode de défaillance standard n’est pas le vibe coding assumé, c’est la dérive : le prototype qui trouve un utilisateur, le script « temporaire » branché sur la prod, la démo qui devient la v1 parce qu’elle marchait. Le code, lui, ne porte pas d’étiquette indiquant le niveau d’exigence avec lequel il a été produit.

Le tips Craftomancer

Le vibe coding ne se juge pas à la génération, il se juge au merge. Vous avez le droit de générer sans lire : personne ne relit ses explorations. Vous n’avez pas le droit de merger sans comprendre, parce que le merge est l’acte qui donne un futur au code. Le jour où un artefact vibe-codé entre en production, la dette de compréhension est exigible en totalité, avec les intérêts. Et c’est celui qui a mergé qui la paye, pas l’agent.

Reconstruire la compréhension, au bon prix

Comprendre tout de tout serait du zèle ruineux. Comme toujours, la profondeur exigée se calibre sur le coût de l’erreur. Les gestes qui rapportent :

• Toute nouvelle dépendance se défend comme une décision d’architecture. Le critère : l’auriez-vous ajoutée vous-même, après l’examen habituel (maintenance, poids, surface, alternatives) ? Lisez le diff du lockfile, pas seulement celui du manifeste. La position par défaut reste : dix lignes de code compréhensibles valent mieux qu’une dépendance non choisie.
• La surface s’inventorie, elle ne se devine pas. Avant de merger, énumérez ce que le changement expose : routes, permissions, configuration par défaut, données présentes dans les logs et les erreurs. L’agent produit cet inventaire en quelques secondes. Traitez-le comme sa carte du diff : un guide de lecture à vérifier contre le code, pas une caution.
• Exécutez ce que vous livrez. Le comportement observé prime sur le comportement lu. Lancez l’artefact, suivez une requête de bout en bout, provoquez l’erreur pour voir ce que voit l’utilisateur. Dix minutes d’exécution attrapent ce que ni la relecture ni les tests décoratifs ne voient.
• Le test de l’explication, en dernier filtre. Rédigez la description de la PR de mémoire, sans relire le diff : ce que ça change, pourquoi, ce qui pourrait casser. Chaque endroit où l’explication bute marque précisément l’endroit où la compréhension manque. Retournez lire là, et seulement là.

En pratique

• Le diff n’est pas le colis : dépendances embarquées, surface exposée et chemins jamais exécutés partent en production avec lui.
• Ne mergez pas ce que vous ne sauriez pas expliquer en incident. L’explication de l’agent est une carte ; la compréhension doit finir dans votre tête.
• Chaque dépendance ajoutée par un agent se défend comme une décision d’architecture, ou se remplace par dix lignes que vous possédez.
• Le vibe coding est légitime là où il n’y a rien à posséder. La question qui le borne : « ce code a-t-il un futur ? ». Et le merge est l’acte qui lui en donne un.
• Inventoriez la surface, exécutez l’artefact, expliquez de mémoire : calibrez la profondeur sur le coût de l’erreur, pas sur la confiance.

Comprendre ce qu’on livre aujourd’hui ne dit pas encore ce que ce code coûtera demain : les raccourcis générés s’accumulent à une vitesse que le métier n’avait jamais connue. C’est l’objet du prochain guide de la Section : la dette générée.