Les tests de spécifications ont guéri la dérive architecturale : l'agent a corrigé 637 tailles de police d'un coup

Il existe une expérience connue : on demande à ChatGPT de faire une copie exacte d'une image sans rien changer, et on répète l'opération 101 fois. La photo de Dwayne Johnson finit en bouillie de dessin animé. Chaque étape prise isolément est presque fidèle, mais l'ensemble donne quelque chose de tout à fait différent.

C'est exactement ce qui se produit avec le code dont s'occupe un agent IA. L'auteur de l'analyse appelle cela la dérive architecturale. L'exemple du frontend est le plus parlant : la police est définie et unique partout, mais les tailles sont différentes sur chaque page, et le style général du site s'effrite. Le principe vaut pourtant pour tous les domaines du développement : la source of truth se disperse.

La vérité est dans la spec, pas dans le code

L'auteur ne lit pas du tout le code, il ne contrôle que les specs. La logique : la spec est le plan, le code est la pièce, et l'on vérifie la pièce par rapport au plan, pas par rapport à une autre pièce. Deux sources de vérité engendrent le chaos.

Toute la documentation se trouve dans le dossier docs, à la racine du projet. Au 5 novembre 2026, il contient 7 478 fichiers .md et 11 niveaux d'imbrication. Dans 95,3 % des dossiers, il n'y a pas plus de 7 fichiers, et dans 97,4 % pas plus de 9. C'est la règle « 7 plus ou moins 2 » : il est plus facile pour un humain (et pour un agent) de comprendre où se trouve chaque chose. Les specs sont écrites et lues par des agents, tandis que l'humain les consulte dans l'interface d'administration sous une forme pratique.

Exemple : toutes les règles de typographie sont réunies dans un seul fichier, typography.md. Il compte 22 rôles, chacun avec sa famille, sa taille sur ordinateur et sur mobile, sa graisse et sa couleur. Par exemple, le paragraphe d'article est en Charis 21/30, la base en Inter 14/21. Deux familles pour tout le site, avec uniquement les graisses 400 et 700. Règle principale : il n'existe pas d'état hors du registre, et toute nouvelle combinaison implique une nouvelle ligne après validation.

Forcer la lecture et vérifier de façon déterministe

Les specs fonctionnent par elles-mêmes de manière probabiliste : l'agent peut les suivre, ou non. D'où deux couches de protection.

La première est le fichier AGENTS.md. Il prescrit qu'avant toute tâche, l'agent lit la documentation du dossier correspondant. S'il faut un audit des dépenses cloud, il va dans le dossier consacré au cloud et passe en revue tous les fournisseurs. Selon l'auteur, dans 9 cas sur 10, les règles ne sont alors pas enfreintes.

La seconde couche, ce sont les tests de specs pour le « dixième cas ». Le test lit les tableaux de typography.md, assemble les paires de tailles autorisées et parcourt tout le frontend. Toute paire hors spec fait échouer le build, avec le nom du fichier et la ligne.

Ce que le test a révélé

Jusqu'au 6 novembre, le test était une liste noire de neuf paires obsolètes. Lorsque l'auteur préparait l'article, il s'est avéré que le code contenait environ 150 paires hors spec. En une seule passe, l'agent a aligné 637 occurrences sur la spec, y a ajouté 4 lignes manquantes et a réécrit le test en liste blanche. C'est la principale leçon pratique : la liste noire n'attrape que ce que l'on connaît déjà, la liste blanche attrape tout le reste.

Si les docs et le code divergent malgré tout, un ordre aide : d'abord les tests, puis le self-heal en production (l'auteur promet un article à part), et seulement ensuite l'humain. Sa tâche n'est pas d'attraper le bug, mais de comprendre pourquoi il est passé et de combler cette faille.

Limites et conclusion

Cette approche exige de la discipline : il faut maintenir des milliers de documents sous une forme cohérente, et les exemples de l'auteur concernent surtout la typographie, où la vérification est simple. Pour la logique métier, les tests de specs sont plus difficiles à écrire. C'est l'expérience d'un seul projet, les chiffres sont autodéclarés, et le sondage sous l'article n'a recueilli qu'une seule voix.

Conclusion pratique pour ceux qui travaillent avec des agents : sortez les règles dans des specs lisibles par machine, prescrivez dans AGENTS.md la lecture obligatoire avant toute tâche, et transformez les déviations les plus fréquentes en tests avec listes blanches. L'auteur a publié sur GitHub le squelette lui-même (AGENTS.md, CLAUDE.md et un dossier docs sans code), on peut donc commencer à partir d'un modèle prêt à l'emploi.