La dette générée · Craftomancer

En chantier Cette section est en cours d'écriture : ce guide est lisible mais pas encore finalisé, son contenu peut évoluer.

La dette technique a toujours eu un garde-fou naturel : la vitesse à laquelle des humains tapent du code. Ce garde-fou vient de sauter.

Un agent dépose de la dette au rythme où il produit des diffs. Si vous la remboursez comme avant, au fil de l’eau, vous ne suivrez pas.

Dans ce guide, je décris la dette propre au code généré, pourquoi elle s’accumule plus vite que l’ancienne, et la discipline pour la contenir. Spoiler : l’asymétrie qui crée cette dette est aussi celle qui rend son remboursement bon marché. À condition d’avoir gardé les verdicts des guides précédents.

Une dette que personne n’a empruntée

La métaphore de la dette, à l’origine, décrit un emprunt. On livre maintenant, on paye plus tard, et quelqu’un a pris la décision : elle est datée, discutable, parfois même documentée. On savait où était le raccourci, on pouvait planifier son remboursement.

La dette générée, personne ne l’a empruntée. C’est un résidu de production : ce qui se dépose quand on accepte, diff après diff, du code vraisemblable produit sans mémoire du reste. Personne n’a décidé d’avoir quatre variantes du même helper ou trois façons de gérer les erreurs. Chaque diff pris isolément était acceptable. C’est exactement ça, le piège.

Cette dette ne se voit pas dans le diff : elle n’existe que dans la somme. Pile là où la relecture (guide 01), qui juge un diff à la fois, ne regarde pas.

Les trois espèces : duplication, slop, divergence

La duplication paraphrasée. L’agent n’a pas de mémoire : chaque session redécouvre le code et réinvente ce qu’elle n’a pas trouvé. Le guide 01 la signalait déjà au niveau du diff ; à l’échelle du dépôt, elle s’accumule. Et ce n’est pas du copier-coller, un outil le verrait. C’est de la paraphrase : même logique, forme différente, invisible aux détecteurs. Ensuite chaque copie vit sa vie. Le bug que vous corrigez dans l’une survit dans les trois autres.
Le slop. Toute cette masse plausible que personne n’a demandée : le catch décoratif, l’abstraction à usage unique, l’option que rien n’appelle, le commentaire qui paraphrase sa ligne, le helper « au cas où ». Pris un par un, chaque élément se défend. C’est pour ça qu’il passe la relecture. Le problème, c’est la masse : du code en plus à lire, une taxe prélevée sur chaque lecture future. Et la machine paye cette taxe aussi, on y revient plus bas.
La divergence des conventions. Chaque génération échantillonne une convention vraisemblable. Pas forcément la vôtre, pas forcément celle de la session précédente. Une équipe humaine converge par friction : relectures croisées, habitudes, mémoire partagée. Un agent n’a pas de friction. La session de mardi ignore les choix de lundi, et le dépôt perd peu à peu ce qui le rendait navigable : une seule façon de faire chaque chose.

Le taux d’intérêt a changé : la dette engendre la dette

La dette classique prélevait ses intérêts sur les humains : compréhension plus lente, modifications plus risquées. La dette générée prélève un second intérêt, et c’est lui la vraie nouveauté.

Les Fondamentaux l’ont posé : le modèle ne connaît de votre projet que ce que son contexte contient. Votre code est son exemple. Un dépôt dupliqué lui enseigne la duplication. Trois idiomes en place rendent un quatrième parfaitement vraisemblable. Chaque déchet accepté entre dans le contexte des générations suivantes.

La boucle est bouclée : plus de dette produit de pires générations, qui produisent plus de dette. C’est la seule dette qui dégrade l’outil censé aider à la rembourser. Elle dégrade aussi votre relecture, au passage : la passe d’intégration suppose de connaître l’existant, et un existant divergent devient inconnaissable.

La conséquence m’amuse, parce qu’elle renverse un vieux rapport de force. La propreté du code n’est plus une élégance d’artisan à défendre contre les délais : c’est un avantage opérationnel mesurable. Un dépôt cohérent et dense produit de meilleures générations, plus vite, avec moins de contexte. Entretenir le code, c’est entretenir la machine.

Contenir à la source

Le moment le moins cher pour traiter cette dette, c’est la porte. Avant le merge, et même avant la génération.

La passe d’intégration est votre filtre anti-duplication. « Le code s’appuie-t-il sur l’existant ou le réinvente-t-il ? » : c’est la question qui attrape la paraphrase avant qu’elle n’entre. Et exigez la recherche avant la production. Un agent à qui on demande d’inventorier les helpers et les conventions du périmètre avant d’écrire duplique beaucoup moins.
Encodez le canon là où l’agent le lit. Une convention qui ne vit que dans les têtes ne survit pas aux sessions. Le fichier d’instructions porte les choix non mécanisables. Le lint porte tout ce qui peut faire échouer un build : une règle qui casse la CI ne dépend de l’attention de personne. Et un fichier exemplaire désigné (« fais comme ici ») vaut mieux qu’un paragraphe de style. C’est la même logique que dans le guide 02 : la consigne durable est celle qui s’exécute.
Comptez les lignes nettes comme un coût. L’agent ne paye pas la ligne qu’il ajoute. Vous, si : à chaque lecture, pour toujours. Demandez le diff qui en ajoute le moins, refusez le défensif non motivé. Et gardez le critère du guide 01 : un volume de code que vous auriez refusé d’un humain ne devient pas acceptable parce qu’il a coûté trois minutes.

Rembourser : le refactoring est redevenu bon marché

La même asymétrie joue dans l’autre sens.

Ce qui rendait le remboursement rare, c’était son coût : des heures d’édition minutieuse, la peur de casser, aucune feature à montrer en face. Or les transformations qui résorbent la dette générée (consolider quatre variantes en une, inliner l’abstraction à usage unique, supprimer les branches mortes, aligner un module sur la convention canonique) sont exactement les tâches où un agent excelle sous harnais : mécaniques, à comportement constant, intégralement jugées par la suite de tests du contrat. La dette générée se rembourse avec l’outil qui l’a produite. Encore faut-il une discipline :

Le refactoring est un geste séparé. Le guide 01 refusait le refactoring opportuniste dans un diff de feature. La symétrie vaut aussi : un diff de remboursement ne change pas de comportement, et la suite verte avant et après en est la preuve.
Programmez le troisième temps. Rouge, vert… puis refactor. C’est le temps que les agents sautent par défaut, parce que le vert ressemble à une fin. Après chaque vert, posez la question en standard : qu’est-ce qui peut être supprimé ou consolidé sans casser la suite ? Un diff net-négatif régulier, c’est un signe de santé du dépôt.
Remboursez par petites coupures. Une consolidation par session, dans le périmètre que vous touchez déjà. La règle du campeur, version exécutant infatigable. Les grandes campagnes de nettoyage attendront d’avoir le harnais qu’elles méritent.

Le tips Craftomancer

Ne lancez jamais un agent « améliorer le code » sans harnais ni périmètre. Sans suite verte avant et après, un refactoring généré n’est pas un remboursement : c’est une génération de plus, avec les mêmes propriétés que la première. Plausible, fluide, non vérifiée. Et relisez les remboursements comme le reste. Un agent qui « simplifie » supprimera volontiers le cas limite qui ressemblait à du slop. La frontière entre code mort et code rare, c’est la suite de tests qui la connaît. Si elle ne la connaît pas, personne ne la connaît.

En pratique

La dette générée n’a pas d’emprunteur et ne se voit pas dans le diff. Surveillez la somme : duplication paraphrasée, slop, conventions qui divergent.
Votre code est l’exemple du modèle. Chaque déchet accepté dégrade les générations suivantes ; la propreté est un avantage opérationnel, plus seulement une élégance.
Filtrez à la porte : recherche de l’existant avant génération, passe d’intégration sans complaisance, lignes nettes comptées comme un coût.
Encodez le canon là où l’agent le lit : le lint pour le mécanisable, le fichier d’instructions et les fichiers exemplaires pour le reste.
Remboursez sous contrat : refactoring en geste séparé, suite verte avant et après, une consolidation par session plutôt qu’une grande campagne.
Après chaque vert, exigez le troisième temps : que peut-on supprimer sans casser la suite ? Le diff net-négatif est un signe de santé.

Rembourser localement ne suffit pas si la structure d’ensemble dérive. Reste à décider quelle cohérence défendre, et comment faire tenir une architecture quand chaque session repart de zéro. C’est le sujet du prochain guide : cohérence et architecture.