Agent Operable Codebase

Image: AI generated

Une question

Ouvrez le fichier le plus long de votre projet. Combien de fonctions contient-il ?

Demandez a un agent IA de modifier une fonction dans ce fichier. L’agent lira le fichier entier. Il l’a ouvert pour une seule fonction, mais 19 fonctions inutiles sont venues avec.

C’est la que le probleme commence.

Le code que l’humain lit, le code sur lequel l’agent travaille

Jusqu’a present, le code etait ecrit pour etre lu par des humains. Bien nommer les variables, ajouter des commentaires, rediger la documentation – tout cela pour reduire la charge cognitive humaine.

A l’ere des agents, la question change. Le code facile a lire pour un humain et le code facile a travailler pour un agent sont-ils identiques ?

Non.

Un humain fait defiler un fichier de 2 000 lignes et son intuition lui dit : “ne touche pas a cette partie.” L’agent n’a pas cette intuition. Lire 2 000 lignes signifie 1 950 lignes de pollution contextuelle.

La recherche le confirme. Quand des informations non pertinentes sont melangees, la performance de l’IA chute de 30 a 85 %. Meme si les tokens inutiles sont des espaces, la performance se degrade. Un contexte plus court est preferable – ce n’est pas de l’intuition, c’est un resultat experimental.

Ne mettez pas un robot dans un bureau humain. Construisez une usine ou le robot peut travailler.

Trois choses dont l’agent a besoin

Pour qu’un agent travaille de maniere stable sur une base de code, trois conditions doivent etre remplies.

1. Pouvoir lire – sans bruit

Un fichier, un concept. Le nom du fichier est le nom du concept.

before: read utils.go → 20 fonctions, 19 inutiles
after:  read check_one_file_one_func.go → 1 fonction, exactement ce qu'il faut

filefunc resout ce probleme. 22 regles structurelles separent le code en unites semantiques. Dans le framework Hono (star 23k+), 186 fichiers ont ete divises en 626. 4 419 tests, aucun n’a casse. Les fichiers ont ete multiplies par 3,4, mais pas une seule ligne de logique n’a change.

“N’y aura-t-il pas trop de fichiers ?” – L’agent n’ouvre pas les repertoires. Il cherche. Que ce soit 500 ou 1 000 fichiers, un seul grep suffit. Ne pas ouvrir 295 fichiers inutiles est plus important que d’attraper les 5 necessaires.

2. Pouvoir verifier – mecaniquement

Si l’on modifie une fonction sans tests, personne ne sait ce qui casse. L’agent non plus. Il tombe dans un doom loop.

before: 0 test, impossible de savoir ce qui casse apres modification
after:  527 fonctions avec tests, tout changement de comportement detecte instantanement

tsma resout ce probleme. Il indexe toutes les fonctions du projet, detecte la presence de tests, mesure la couverture et renvoie les numeros de ligne des branches non couvertes.

Sans feedback, si l’on demande au LLM d’ecrire des tests, la couverture s’arrete a 60~70 %. Si on lui dit “line 41, 44, 70 non couvertes”, elle atteint 100 %. Meme modele. La difference : uniquement la resolution du feedback.

Dans l’experience avec un projet de 527 fonctions : TODO a atteint 0. L’agent autonome s’est arrete a 40 et a declare “c’est termine.” Avec le ratchet, les 527 sont completees.

3. Les specifications doivent etre verifiables de maniere croisee

Le schema API, le schema de base de donnees, les politiques de securite et les transitions d’etat doivent pouvoir etre verifies mecaniquement pour leur coherence. Quand on en change un, il faut savoir avant la compilation si une incoherence apparait.

before: 200 endpoints, la coherence entre specifications verifiee par l'humain
after:  un seul operationId chaine toutes les couches, la machine detecte le drift

yongol resout ce probleme. 10 SSOT (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl, etc.) sont chaines par un seul operationId et verifies de maniere croisee par ~287 regles. user_id est string dans OpenAPI mais BIGINT dans DDL – ce type de contradiction entre couches echappe aux outils existants.

Une structure qui traverse les trois outils

filefunc, tsma, yongol sont des outils independants, mais ils partagent une structure commune.

filefunc:  22 regles structurelles → validate → corriger → repeter
tsma:      mesurer la couverture → feedback des branches non couvertes → corriger → repeter
yongol:    verification croisee → detection de drift → corriger → repeter

C’est toujours la meme boucle.

Le LLM genere → l’outil deterministe juge → le resultat est renvoye au LLM → repeter

Symbolic Feedback Loop. Une structure cyclique ou un outil deterministe corrige la generation probabiliste du LLM. Ce n’est pas l’IA qui verifie l’IA, c’est la machine qui verifie l’IA.

Donnez une opinion, il flattera. Donnez un fait, il corrigera. Demandez “le code est bon ?” et il repondra “oui, c’est bien.” Dites “line 41: field name mismatch” et il corrige immediatement. Un feedback sans objet de flatterie – parce que les nombres et les positions ne sont pas des emotions.

Du legacy a l’agent-operable

Pas besoin de tout changer d’un coup. Ce n’est pas un chantier de fondations, c’est un renforcement parasismique. On renforce le batiment sans fermer le commerce qui tourne.

Etape 1 – Rendre lisible

Commencez par le fichier le plus long. Lancez filefunc validate et ramenez les violations a 0. Tous les tests existants doivent passer.

Etape 2 – Rendre verifiable

Repetez tsma next. Ajoutez des tests aux fonctions non couvertes, comblez les branches non couvertes. Si l’agent meurt en cours de route, la progression est preservee. Un nouvel agent lance tsma next et reprend.

Etape 3 – Verifier de maniere croisee

Introduisez le SSOT et lancez yongol validate. La machine detecte les contradictions entre couches.

Chaque etape est independante. On peut faire l’etape 2 sans l’etape 1, ou l’etape 1 sans l’etape 2. Mais quand les trois sont combinees, la portee du travail autonome de l’agent s’elargit considerablement.

Changer le systeme d’exploitation

Un agent-operable codebase n’est pas un simple lint ou du tooling. C’est changer le systeme d’exploitation de la base de code.

Beaucoup de gens cherchent a rendre le train plus rapide. Des modeles plus grands, des agents plus intelligents, de meilleurs prompts.

Plus le train va vite, plus les rails comptent. Ceux qui posent les rails sont encore tres rares.

Articles connexes

• filefunc – Un fichier, un concept – Une convention de structure de code qui elimine la pollution contextuelle du LLM avec 22 regles structurelles
• tsma – La ligne de defense contre les regressions du code legacy – Automatisation de tests basee sur le ratchet : 527 fonctions jusqu’a TODO 0
• Pourquoi les agents de codage fonctionnent et pourquoi ils s’effondrent – Analyse structurelle du Symbolic Feedback Loop
• La topologie du feedback plutot que le QI du modele – Pourquoi le meme modele s’arrete a 40 ou complete 527
• whyso – Ce que git blame ne montre pas – Extraction automatique de l’historique des modifications par fichier

References

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – Performance en baisse de 30%+ quand l’information pertinente est enfouie au milieu du contexte
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) – Performance en baisse de 13,9~85 % meme si les tokens inutiles sont des espaces
• Demonstration empirique du framework Hono – 186 fichiers → 626 fichiers, les 4 419 tests passes
• Demonstration empirique tsma, 527 fonctions – PASS 246 (46,7 %), DONE 281 (53,3 %), TODO 0
• Experience Ratchet Pattern – Agent autonome 40/527 (7,6 %) vs ratchet CLI 527/527 (100 %)