Aller au contenu
Matthias Bohlen

Votre agent de code copie votre pire code

Les agents de code copient l'architecture qu'ils voient. Découvrez quels faits architecturaux consigner (attributs de qualité, frontières, ADR) et comment tester l'effet.

Architecture logicielle · Fonderie logicielle · Documentation d'architecture

Lire la vidéo
En lisant la vidéo, votre navigateur se connecte à YouTube.

Essayez dans Archilab ↗

La vidéo est en anglais. La transcription ci-dessous est une traduction.

Le diff qui avait l'air correct

Voici un diff concret, tiré d'un de mes projets d'exemple. L'agent de code a ajouté une fonctionnalité, les tests passent, la vérification des types est propre, la revue n'a rien relevé. Pourtant, le nouveau code du module billing importe le data store du module orders et lit les commandes directement dans le data store de l'autre module.

Le code était-il mauvais ? Non : il était correct, lisible et testé. Simplement, personne n'avait dit à l'agent que cet appel était interdit.

C'est arrivé plus d'une fois dans un projet client, et quand j'ai confié la même tâche à 5 sessions d'agent toutes neuves, c'est arrivé 5 fois sur 5. Je vais vous montrer ce qui l'a réellement empêché.

Après cet épisode, vous saurez regarder une mauvaise sortie d'agent et vous demander quel fait architectural manquait vraiment. Vous pourrez ensuite l'écrire là où l'agent le lit. Vous verrez une configuration petite et concrète, et une manière de tester si elle fonctionne : la même tâche, le même modèle, le même prompt, exécutés plusieurs fois, avant et après.

Les agents copient ce qu'ils voient

Voici ce qui m'a surpris. Sur la version propre de mon exemple, l'agent n'a pas commis cette erreur. Cinq sessions sur cinq ont tenu billing à l'écart des données d'orders sans qu'on le leur dise. Un code propre porte en lui son architecture, et l'agent la lit.

J'ai donc changé une seule chose. J'ai fait ressembler la base de code à une vraie base de code après quelques années, où quelqu'un a déjà pris un raccourci. Ici, dans le module users, il a importé directement le datastore d'orders pour lire le nombre de commandes de l'utilisateur. Ce nombre est lu ici, en bas, par un accès direct au datastore d'orders. Personne ne lui a dit que c'était une erreur, et ce n'était écrit nulle part non plus.

Voici les diffs des agents qui ont travaillé sur ce code. Sur ce code érodé, toutes les sessions ont copié le raccourci. Trois d'entre elles l'ont même joliment emballé : un port dans billing, plus un adaptateur dans billing qui importe orders. Cela ressemble à des ports et adaptateurs, mais la dépendance pointe dans le mauvais sens. Les tests étaient verts à chaque fois.

La plupart des mauvaises sorties d'agent sont des solutions locales correctes. L'agent suit le précédent qu'il trouve dans le code, et seule l'équipe sait que ce précédent est faux.

L'agent voit les fichiers qu'il ouvre, pas votre historique. Les attributs de qualité, les frontières de contexte et les options rejetées vivent dans les têtes, dans des wikis que personne n'ouvre et dans d'anciennes réunions.

Un exemple : un agent franchit la frontière, nous le corrigeons en revue, et à la session suivante il la franchit de nouveau. Les corrections faites dans le chat disparaissent avec la session. Seul ce qui est dans le dépôt persiste.

Vous direz peut-être : « Un meilleur modèle déduira l'architecture à l'avenir. » Sur du code propre, il le fait déjà, mais il ne peut déduire que ce que le code montre. Dès que le code contredit votre intention, l'agent ne distingue plus la règle de l'exception, et il ignore pourquoi billing ne doit pas lire les données d'orders.

Ce qu'il faut écrire

Trois types de connaissances modifient le plus la sortie d'un agent : les attributs de qualité, les frontières de contexte, et les décisions avec leurs raisons.

Il vous faut des attributs de qualité formulés comme des énoncés testables. Pas seulement « notre système doit être très rapide et scalable », mais « 300 millisecondes pour le checkout dans 95 % des cas, sous charge normale ». Billing peut être déployé sans orders. Cela guide l'agent. « Scalable » seul, non.

Les bounded contexts : nommez-les, listez qui peut parler à qui, et dites comment, par événements ou par API par exemple, jamais par le datastore de l'autre module. Un paragraphe et un petit diagramme sous forme de texte.

Et les ADR : contexte, décision, conséquences, et surtout les alternatives rejetées. Sinon l'agent propose de nouveau l'alternative rejetée, avec aplomb. Et dans une base de code érodée, l'alternative rejetée se trouve souvent juste là, dans le code, prête à être copiée.

Un exemple : l'ADR de mon projet. Billing lit les données de commandes uniquement via un port qui lui est propre. J'utilise le format Y-statement, une phrase en six parties. Elle se lit ainsi. Dans le contexte de l'émission de factures pour des commandes, face aux préoccupations que nous avons, à savoir des releases séparées de billing et d'orders d'une part, et une propriété des données séparée d'autre part, qu'avons-nous décidé ? Nous avons opté pour un port dans billing, que la composition root alimente depuis l'API publique du module Orders, et nous avons écarté d'autres options, comme billing important le store d'orders, ou un adaptateur dans billing qui importe orders. Nous voulons ainsi que billing puisse être déployé sans orders, en acceptant une fonction de plus pour le câblage.

Vous direz peut-être : « Cela fait beaucoup à écrire. » C'est vrai, voici donc une astuce pour gagner du temps. Commencez par la seule décision que votre agent a déjà enfreinte. Écrivez l'ADR à partir du commentaire de revue que vous avez fait. Puis recommencez la prochaine fois que votre agent ne fait pas ce que vous voulez.

Le mettre là où l'agent lit

Une connaissance n'aide que si elle se trouve dans le contexte de l'agent au bon moment, et si elle est assez courte pour être utilisée.

Dans mon exemple, il a fallu très peu de chose. Un court fichier CLAUDE.md qui dit : chaque module possède ses données, un module n'importe que ses propres fichiers, quand il a besoin de quelque chose d'un autre module il déclare un port, et la composition root, src/app.ts, alimente les ports. Plus cette composition root vide, pour qu'il y ait un endroit évident pour le câblage.

Dans un vrai système, CLAUDE.md grossit pour contenir la finalité du système, les trois principaux attributs de qualité, la context map, des règles comme « avant de modifier quoi que ce soit entre modules, lis docs/adr/ », et un index des ADR avec un résumé d'une ligne. Cet index compte. L'agent ouvre l'ADR pertinent pour la tâche au lieu de tout charger. Donnez donc aux ADR des titres sous forme d'affirmations, comme « Un bounded context ne lit jamais les données d'autres bounded contexts ».

Avant : billing lit le store d'orders. Après : billing déclare un port, orders publie la méthode de lecture, et src/app.ts relie les deux. Dans les cinq sessions.

Soyons honnêtes : c'est un modèle, une fonctionnalité, cinq exécutions chacun. Votre agent et votre base de code peuvent bien sûr se comporter autrement, alors mesurez sur votre propre code. Exécutez la même tâche plusieurs fois avant et après, et comparez les diffs.

L'imposer, le garder vivant

La documentation que l'agent lit est la première couche. Les contrôles qui font échouer le build sont la seconde. L'agent rend la mise à jour de la documentation peu coûteuse.

Transformez les règles les plus importantes en fitness functions : un test d'architecture, par exemple avec ArchUnit, import-linter ou un équivalent, qui échoue à chaque import traversant une frontière de module. Les violations héritées, s'il y en a, vont sur une liste qui ne fait que diminuer.

Voici de nouveau ce qui m'a surpris. Dans mes essais, le test n'est jamais passé au rouge. Les agents l'ont lu avant leur première modification et l'ont respecté. Même sans CLAUDE.md, le test et la composition root vide ont gardé les cinq sessions dans leurs frontières. Le test est donc aussi de la documentation, et une documentation qui ne peut heureusement pas devenir obsolète sans que le build vous le signale.

Ce test arrêtera-t-il un agent qui ignore tout ? Mes essais n'ont pas pu le montrer, car aucun agent ne l'a fait. C'est précisément pourquoi il est là. Il ne coûte rien tant que l'agent se comporte bien, et il bloque le merge quand ce n'est pas le cas. Il fait aussi un bon juge. Exécutez-le après toute session d'agent : chaque ligne rouge désigne un nouvel import qui franchit la frontière.

Vous pensez peut-être : « Ce n'est que de la documentation, nous ne l'avons jamais tenue à jour. » Or une chose a changé avec l'arrivée des agents de code. Avant, la documentation n'avait aucun lecteur qui agissait dessus chaque jour. Maintenant, elle en a un. Un ADR périmé produit visiblement du code erroné en quelques jours, et l'obsolescence se remarque donc.

Faites de l'agent un acteur de l'entretien. Quand une modification contredit un ADR, l'agent doit soit le respecter, soit proposer un nouvel ADR dans la même pull request. Un humain relit cette décision, pas la prose.

Alors, restez modeste. Dix ADR exacts valent bien mieux que cent ADR que personne ne lit. Bien sûr, tout cela ne remplace pas de vraies revues, et même un ADR peut se tromper. Mais au moins, le désaccord devient visible.

Conclusion et à vous de jouer

Souvenez-vous : votre agent copie l'architecture qu'il voit. Si votre code ne la montre plus, écrivez-la là où l'agent la lit.

Alors, essayez ceci. Prenez les trois derniers commentaires de revue où vous avez dit à un agent ou à un collègue : « ici, on ne fait pas comme ça ». Écrivez chacun sous forme de court ADR ou de ligne d'attribut de qualité, liez-les depuis CLAUDE.md, et relancez l'une des mêmes tâches. Comparez les diffs. En option, ajoutez un test d'architecture pour la règle qui comptait le plus.

Vous voulez essayer en pratique ? Utilisez le lien vers l'Architecture Practice Lab dans la description de cette vidéo. Vous y trouvez le dépôt d'exemple érodé de cet épisode. Donnez-lui la même tâche avec votre propre agent, Claude ou un autre, et voyez s'il respecte les frontières. Ensuite, écrivez l'architecture, réessayez, et obtenez le retour de mon agent relecteur, que j'ai entraîné sur des règles de bonne architecture.

À bientôt !

Essayez dans Archilab ↗