Domptez vos refactorings agentiques avec la Mikado Method
Vous avez essayé. Vous avez confié à votre agent IA (Claude Code, Cursor, Copilot, peu importe lequel) une tâche de refactoring sur une vraie codebase legacy. Et vous avez vu apparaître une pull request de 147 fichiers où la moitié des changements ne ressemblent à rien, où trois tests cassés ont été “adaptés” plutôt que corrigés, et où personne dans l’équipe n’a envie de plonger.
Ce n’est pas un problème de modèle. Les agents font exactement ce qu’on leur a appris à faire : avancer. Face à une erreur, ils patchent. Face à un test rouge, ils adaptent. Face à une dépendance imprévue, ils contournent.
Sur un script de 200 lignes, c’est efficace. Sur un système legacy de 200 000 lignes, c’est destructeur.
Trois modes de défaillance, un seul mécanisme
Après quelques mois à observer des équipes piloter des agents sur du code legacy, trois patterns reviennent systématiquement.
L’avidité de changement. L’agent ne s’arrête pas face à un obstacle. Il l’absorbe, l’adapte, le contourne. Chaque correction génère de nouvelles dépendances modifiées, qui génèrent de nouvelles corrections, jusqu’à la PR ingérable. Ce n’est pas de la mauvaise volonté : c’est de l’optimisation locale sans vision globale.
La dispersion du contexte. Les agents ont une fenêtre de contexte finie. Sur un refactoring qui touche progressivement à 50 fichiers, l’objectif initial glisse hors du contexte actif. L’agent continue d’avancer, mais vers où ? La qualité des décisions se dégrade silencieusement, sans signal d’alerte.
L’illusion du vert. L’agent fait passer les tests, mais en les modifiant.
Il satisfait le compilateur, mais avec des # type: ignore et des mocks
complaisants. Le pipeline CI reste vert. La garantie sémantique, elle, a été
silencieusement érodée.
Ces trois modes partagent un mécanisme commun : un système entraîné à progresser, sans discipline pour s’arrêter.
La solution existe depuis 2014
En 2009, Ola Ellnestam et Daniel Brolund tentent un refactoring sur une codebase Java legacy. Ils s’en sortent très mal. Chaque changement en provoque trois autres, ils accumulent du code cassé pendant des jours, et finissent par tout jeter.
À la conférence SDC de la même année, ils présentent leur post-mortem. Dans la salle, Laurent Bossavit fait un parallèle avec le jeu de Mikado : ces baguettes empilées qu’on doit retirer une par une sans faire bouger les autres. Le nom reste. Le livre suit en 2014, chez Manning.
L’intuition centrale de la méthode tient en une phrase : on ne comprend une codebase legacy qu’en la cassant délibérément.
Pas en la lisant. Pas en dessinant des diagrammes UML. En tentant des modifications, en regardant ce qui pète, et en notant pourquoi. Le compilateur et la suite de tests sont des capteurs infiniment plus précis que n’importe quelle analyse statique.
Les quatre règles
La méthode Mikado tient en quatre règles.
-
Définir un objectif précis et testable. “Améliorer l’architecture” n’en est pas un. “Extraire la logique de facturation dans un service injectable, testable sans base de données” en est un. Vous devez savoir sans ambiguïté quand l’objectif est atteint.
-
Tenter l’objectif directement, naïvement. Pas d’analyse préalable, pas de design document. On essaie. La plupart du temps, ça casse : c’est précisément l’intérêt. Les casses révèlent les dépendances cachées.
-
Au premier blocage, annuler tout.
git reset --hard HEAD. On revient à un état vert. C’est la règle la plus contre-intuitive, et la plus importante. Le travail des dix dernières minutes n’est pas perdu : il est devenu de l’information dans le graphe. -
Noter le blocage comme prérequis, et recommencer sur ce prérequis. Le test qui était rouge révèle un couplage. Ce couplage devient un nœud dans le graphe. On lui applique récursivement les règles 2, 3 et 4 jusqu’à atteindre des feuilles, des prérequis directement traitables sans rien casser.
Quand toutes les feuilles sont résolues, on remonte le graphe. L’objectif initial, qui semblait impossible, devient mécanique.
Ce que ça donne en pratique
Prenons un exemple concret. Objectif : extraire send_invoice() d’un
OrderService monolithique.
Exploration. On tente directement, sans analyse préalable. Le compilateur
plante en trois endroits. git reset --hard HEAD. On ouvre mikado.md et on
note les trois blocages comme nœuds candidats.
Construction du graphe. On explore chaque nœud avec la même règle : tenter, observer, revenir.
- P1 : écrire les tests → rien ne casse : feuille ✓
- P3 : passer smtp_client en paramètre → rien ne casse : feuille ✓
- P2 : isoler l’accès DB → casse encore.
git reset. En creusant : l’accès DB dépend d’une classe non injectable. Un sous-nœud émerge.- L2 : créer un CustomerRepository injectable → rien ne casse : feuille ✓
Le graphe est stabilisé.
Le graphe ressemble à ceci :
L’objectif est en bas, les feuilles (en vert) en haut. On suit les flèches pour comprendre les dépendances. On résout dans l’autre sens.
Traitement des feuilles.
- P1 : écrire les tests, commit ✓
- L2 : créer le CustomerRepository injectable, commit ✓
- P2 : devenu feuille, brancher le repository, commit ✓
- P3 : injecter smtp_client en paramètre, commit ✓
L’extraction finale est triviale : tous les obstacles éliminés un par un, chaque commit autonome et reviewable en dix minutes.
C’est exactement ce que la méthode appelle une feuille : un changement qu’on peut faire sans rien casser d’autre. On ne travaille jamais sur autre chose.
Pourquoi cette méthode est précisément faite pour les agents IA
L’alignement entre les défauts des agents et les invariants de Mikado n’est pas accidentel. C’est la même classe de problème : maintenir la discipline dans un système qui optimise la progression locale.
Le revert systématique compense l’avidité de changement. Au lieu de laisser l’agent accumuler des patchs en cascade, on lui donne une règle claire : si ça casse, on note et on annule. L’échec devient un signal exploitable.
Le graphe externalise le contexte que l’agent ne peut pas maintenir. Un
fichier mikado.md versionné joue le rôle de mémoire persistante entre
sessions. L’agent ne conserve pas la stratégie globale dans sa fenêtre de
contexte : il la lit depuis le graphe au début de chaque itération.
Mikado rend les PRs reviewables. Sans méthode, l’agent produit des PRs monstres. Avec Mikado, chaque feuille devient une unité atomique : 3 à 5 fichiers, un commit, dix minutes de review. La vélocité de l’agent ne se traduit plus en dette de review pour l’humain.
Ce que ça change concrètement
-
Développeurs : la charge cognitive de la review chute. On revoit des unités atomiques avec un contexte clair, plus des PRs de 47 fichiers sans fil conducteur.
-
Tech leads : le graphe Mikado est un tableau de bord tactique. On voit en un coup d’œil les dépendances révélées, ce qui reste à traiter, où en est l’agent à tout instant.
-
DSI et CTOs : c’est un artefact auditable. Il documente la trajectoire de refactoring, les risques identifiés, les étapes validées. Dans un contexte où chaque équipe doit justifier son usage de l’IA, cet artefact a une valeur stratégique réelle.
La méthode Mikado n’est pas une nouveauté. Elle a été conçue pour des développeurs humains qui faisaient exactement les mêmes erreurs que nos agents aujourd’hui. Ce n’est pas vos agents qu’il faut améliorer. C’est le cadre dans lequel vous les faites travailler.
Le skill Mikado Method est désormais publié : découvrez ce qu’il impose à l’agent et pourquoi. Un article suivant déroulera un cas pratique complet.
Pour aller plus loin : Ola Ellnestam, Daniel Brolund : The Mikado Method (Manning, 2014) Site officiel : mikadomethod.info