Onboarder un agent IA sur 500 000 lignes de legacy : méthode et pièges

Tous les tutos IA partent d'un create-next-app. Le projet est vierge, le prompt fonctionne, la démo est magique. Sauf que dans la vraie vie, personne ne part de zéro : vous héritez de 200 000, 500 000, parfois plusieurs millions de lignes avec des conventions que personne n'a documentées. Lâcher un agent IA là-dedans sans préparation, c'est la garantie de PRs recalées en boucle.

J'ai onboardé des agents Claude Code sur plusieurs projets legacy chez des clients ces derniers mois. Le constat est toujours le même : la qualité du code généré dépend à 80 % de ce que vous injectez avant le premier prompt, pas du modèle que vous choisissez.

Pourquoi votre agent IA se noie dans le legacy

Le problème n'est pas l'intelligence du modèle. Claude Opus, GPT-4, Gemini : tous savent écrire du code correct en isolation. Le problème, c'est que du code correct ne suffit pas sur un projet legacy. Il faut du code aligné avec les conventions existantes.

Selon un rapport McKinsey, 70 % des logiciels des entreprises du Fortune 500 ont été développés il y a plus de 20 ans. Reuters estime que 95 % des transactions ATM tournent encore sur du COBOL. Cette dette n'est pas abstraite : Delta Airlines a perdu environ 500 millions de dollars en 2024 lors d'une panne IT qu'un système modernisé aurait mieux encaissée (chiffre cité par VirtusLab dans son analyse de migration agentique).

Quel est le vrai problème avec les gros codebases ?

Mike Codeur résume bien la situation dans sa vidéo sur AgentOS : « Quand tu arrives en entreprise, on te dit de ne pas coder pendant trois jours. Tu regardes le code, tu comprends l'architecture, les conventions implicites. L'IA, elle, saute cette étape et code directement. » Sur un projet de 200 000 lignes, même Claude Code avec son indexation automatique ne va pas parser chaque fichier. Des pans entiers de la logique métier restent invisibles.

Le résultat concret : l'agent génère du code qui compile, qui passe les tests unitaires basiques, mais qui sera systématiquement recalé en code review parce qu'il ne respecte pas les patterns du projet. J'ai vu des équipes perdre plus de temps à corriger le code généré qu'à l'écrire manuellement. C'est exactement le goulot d'étranglement que je décrivais sur les PRs générées par agents.

Le workflow classique (écrire, vérifier, corriger) ne marche plus avec l'IA. Il faut inverser : définir les règles d'abord, générer ensuite.

Extraire les conventions avant de lâcher l'agent

La première étape d'un onboarding agent sur du legacy, c'est l'extraction automatique des conventions. Pas un document Word de 40 pages rédigé il y a trois ans. Un scan du code tel qu'il existe aujourd'hui.

Comment AgentOS automatise la découverte de standards ?

Brian Castle a développé AgentOS, un framework open source qui s'intègre à Claude Code (et à d'autres agents). Le principe : une commande discover standards analyse votre codebase et extrait les patterns récurrents en fichiers .md structurés. Ces fichiers deviennent des règles injectables dans le contexte de l'agent.

Mike Codeur l'a testé sur son boilerplate ChipSaaS. L'outil a détecté en quelques minutes la séparation en couches (service, persistence, présentation), le pattern validate/authorize/execute dans les services, le système de façades pour les interceptors et la hiérarchie d'erreurs par domaine. Cinq standards identifiés automatiquement, là où un dev humain aurait mis une journée à documenter la même chose.

Le workflow se décompose ainsi : scan → génération de standards.md → injection dans le contexte via inject standards. L'agent code ensuite en respectant les conventions détectées, pas en improvisant. C'est le même principe que je défends pour tout projet IA : partir de specs claires, pas d'un prompt vague.

Quel rôle joue CodeScene dans ce processus ?

CodeScene apporte une dimension complémentaire : la mesure objective de la santé du code. Leur benchmark sur 25 000 fichiers montre que la moyenne de Code Health dans l'industrie IT est de 5.15 sur 10. Le seuil pour qu'un humain comprenne facilement le code est 9.0. Pour que l'IA puisse modifier le code sans introduire de bugs, il faut atteindre 9.4 minimum.

Avec leur serveur MCP intégré à Claude Code, le refactoring guidé produit 2 à 5 fois plus d'améliorations de Code Health que le refactoring brut. Adam Tornhill (fondateur de CodeScene) a publié ces chiffres en mars 2026 sur un dataset public de competitive programming. La différence est nette : sans feedback loop, l'agent fait du cosmétique. Avec le MCP, il cible les vrais hotspots.

Le context lake : donner à l'agent ce qu'un dev met 3 jours à absorber

Extraire les conventions ne suffit pas. Sur un projet de 500 000 lignes, l'agent a besoin de comprendre la logique métier, les dépendances entre modules et l'historique des décisions architecturales. C'est ce que l'équipe d'AI Fieldbook appelle le « Context Lakehouse ».

Faut-il un RAG massif ou des fichiers de contexte bien écrits ?

AI Fieldbook a présenté un cas concret : un retailer mondial avec des dizaines de millions de lignes de code écrites entre les années 1990 et 2000. Leur approche consiste à ingérer le code, la documentation existante, les données APM, les tickets d'incidents et les tests dans un « lac de contexte » que l'IA interroge. Le résultat : l'agent documente correctement le code dans 80 à 90 % des cas. Les 10 à 20 % restants nécessitent une intervention humaine (« ce module a été développé en 1998 et abandonné en 2003 »).

Pour la plupart des projets que je croise (50 000 à 500 000 lignes, pas des dizaines de millions), un RAG aussi lourd est surdimensionné. Ce qui fonctionne : un ensemble de fichiers de contexte structurés. Mon approche repose sur cinq fichiers clés que j'installe systématiquement.

CLAUDE.md porte les instructions générales pour l'agent. ARCHITECTURE.md décrit la structure du projet et les choix techniques. CONVENTIONS.md liste les patterns à respecter (nommage, structure des fichiers, gestion d'erreurs). CURRENT_STATE.md résume l'état actuel du projet et les chantiers en cours. DECISIONS.md trace les décisions architecturales passées et leurs raisons. Ces cinq fichiers remplacent trois jours d'onboarding humain. L'agent les lit au démarrage, et chaque PR générée respecte le cadre.

Un agent qui lit le contexte du projet, exécute une tâche, teste, documente, puis passe à la suivante : c'est ça, le workflow qui tient en production.

C'est d'ailleurs la même logique qui rend Claude Code opérationnel en maintenance : sans cette mémoire projet, l'agent dérive au bout de quelques itérations.

Les pièges qui font dérailler l'onboarding agent

Même avec des conventions extraites et un contexte injecté, certains pièges reviennent systématiquement. J'en ai identifié quatre après plusieurs mois de projets legacy augmentés par IA.

Pourquoi le one-shot échoue toujours sur du legacy ?

VirtusLab a documenté un test parlant : ils ont demandé à Claude Code (Sonnet 4.5) de réécrire un jeu C++ complet en Rust, en un seul prompt. Le résultat compile, mais le jeu ne fonctionne pas correctement. Les animations sont cassées, la gestion d'état est approximative, des pans entiers de logique ont été simplifiés. Leur conclusion : le one-shot « vibe coded » ne passe pas à l'échelle sur du legacy.

Leur solution est un pipeline agentique découpé en étapes : audit système, analyse de la logique, plan de migration, exécution par blocs, vérification croisée par un second agent. Chaque étape produit un artefact vérifiable. C'est plus lent qu'un prompt unique, mais le taux de réussite passe de « ça compile peut-être » à « ça fonctionne en production ».

Les trois autres pièges que j'observe régulièrement :

Le piège du context window saturé. Sur 500 000 lignes, impossible de tout injecter. Il faut un mécanisme de sélection (rules files, scoped conventions par dossier). AgentOS gère ça avec des détections automatiques par répertoire.

Le piège de la confiance aveugle dans les tests générés. L'agent écrit des tests qui passent, mais qui ne testent pas les cas métier réels. J'ai détaillé ce problème dans mon retour sur les tests générés par Claude Code après 4 mois en production. La couverture grimpe, la qualité des assertions stagne.

Le piège du refactoring sans mesure. Sans un outil comme CodeScene pour scorer objectivement la santé du code avant et après, vous ne savez pas si l'agent améliore ou dégrade. Selon Centric Consulting, les agents bien encadrés réduisent les coûts de réécriture de 30 à 50 % et compriment les timelines de 50 à 80 %. Mais « bien encadré » est le mot clé. D'après leur analyse, les agents sont avant tout des outils de compréhension, pas de génération brute.

Verdict : go sur du legacy, mais uniquement avec la méthode

Onboarder un agent IA sur 500 000 lignes de code legacy, c'est faisable. Je le fais, mes clients le font, les résultats sont concrets quand la méthode est en place. Mais lâcher Claude Code ou Cursor sur un monorepo sans préparation, c'est perdre du temps et de l'argent.

Quand est-ce que ça vaut le coup ?

Le cas d'usage le plus rentable : le refactoring progressif piloté par un score de santé. Vous partez de 5/10, vous visez 9.4. L'agent, guidé par CodeScene ou un équivalent, traite les hotspots un par un. En quelques semaines, des pans entiers de code redeviennent maintenables. D'après Augment Code, le legacy consomme 74 % de budget maintenance en plus que le code moderne. Réduire cette dette, même partiellement, libère de la bande passante pour les features.

Le no-go : un projet sans aucun test, sans documentation, avec des dépendances circulaires et un build qui casse une fois sur deux. Là, l'agent ne peut rien. Il faut d'abord stabiliser à la main, puis introduire l'IA.

Mon verdict personnel : un bon système de production logiciel industrialisé autour de l'IA, avec des specs claires, des blocs courts testables et des fichiers de contexte bien tenus, bat n'importe quelle équipe classique en vitesse et en coût sur du legacy. Ce n'est pas l'agent qui fait la différence. C'est l'architecture de votre workflow autour de l'agent.