Moderniser une codebase legacy est l’un des scénarios où Claude Code peut apporter beaucoup de valeur.
Mais c’est aussi l’un des scénarios où une mauvaise utilisation de l’agent peut produire les conséquences les plus importantes.
Une refonte à grande échelle combine souvent :
- une codebase mal connue ;
- des dépendances implicites ;
- peu de documentation ;
- des tests incomplets ;
- des comportements historiques difficiles à reproduire ;
- un blast radius potentiellement élevé.
Le module utilise précisément la modernisation legacy comme cas d’école pour appliquer plusieurs mécanismes de Claude Code ensemble.
Le workflow central est :
Explore → Plan → Code → Verify
L’idée n’est pas de demander immédiatement à Claude de modifier l’ensemble du système.
Il faut d’abord comprendre, limiter le périmètre, contrôler les changements et vérifier leur résultat.
Pourquoi le legacy est un bon test pour un agent
Une codebase récente et bien testée fournit de nombreux garde-fous :
architecture connue
+
tests fiables
+
conventions cohérentes
+
dépendances explicites
Une codebase legacy peut présenter exactement l’inverse.
architecture partiellement connue
+
tests incomplets
+
conventions historiques
+
dépendances implicites
Le risque vient donc autant de ce que Claude ne sait pas encore que de ce qu’il sait.
Le module souligne trois caractéristiques des grandes transformations legacy :
- high blast radius ;
- unpredictable dependencies ;
- limited reversibility.
Le mauvais point de départ : demander directement la refonte
Imaginons une demande comme :
« Modernise toute cette application et remplace les anciens patterns par la nouvelle architecture. »
Cette demande laisse beaucoup trop de décisions implicites.
Claude doit notamment déterminer :
- quelles parties sont réellement legacy ;
- quelles conventions doivent être conservées ;
- quelles dépendances risquent de casser ;
- quels fichiers sont hors périmètre ;
- quel ordre de migration utiliser ;
- quels comportements doivent absolument rester identiques.
Si l’agent commence directement par modifier le code, il peut prendre des décisions avant d’avoir compris suffisamment le système.
Le module recommande donc une séparation explicite entre exploration et exécution.
Étape 1 : Explore
La première phase consiste à comprendre la codebase.
Explore
↓
architecture
dépendances
patterns existants
zones sensibles
L’objectif n’est pas encore de produire du code.
Il faut construire une représentation suffisamment fiable du système.
Claude peut notamment examiner :
- l’organisation des répertoires ;
- les principaux modules ;
- les dépendances ;
- les conventions existantes ;
- les tests ;
- les composants directement concernés par la migration.
Le principe est :
Comprendre avant de modifier.
Utiliser Plan mode pour rester en exploration
Le fichier source présente Plan mode comme un mécanisme central pour les changements à haut risque.
Plan mode maintient l’agent dans une phase d’exploration en lecture seule pendant que l’équipe construit sa confiance dans le changement proposé.
Conceptuellement :
Claude Code
↓
Plan mode
↓
lecture / exploration
↓
proposition
↓
aucune modification encore
Cela crée une frontière claire entre :
analyser
et :
modifier
Pourquoi Plan mode réduit le risque
Avant qu’un seul fichier soit modifié, il devient possible de vérifier :
- le périmètre identifié ;
- les fichiers que Claude prévoit de toucher ;
- les dépendances ;
- la stratégie de migration ;
- les zones inattendues.
Le module insiste sur un point :
Vous pouvez examiner les modifications proposées, repérer des chemins que vous ne vous attendiez pas à voir touchés et intervenir avant la première modification.
C’est exactement le type de contrôle utile lorsque le blast radius est difficile à estimer.
Étape 2 : Plan
Après l’exploration vient le plan.
Le plan doit convertir la compréhension de la codebase en séquence de changements contrôlables.
On passe de :
Voici comment le système fonctionne
à :
Voici ce que nous allons modifier
et dans quel ordre
Un bon plan de modernisation doit permettre de répondre à des questions comme :
- quels composants seront modifiés ?
- quels comportements doivent rester identiques ?
- quelles dépendances sont concernées ?
- quels changements peuvent être isolés ?
- quels tests permettront de valider chaque étape ?
- à quel moment une validation humaine est-elle nécessaire ?
Le plan est aussi un point d’approbation
Le fichier source souligne que Plan mode crée une frontière entre exploration et exécution, mais que la décision d’approbation elle-même reste à définir par l’équipe.
Autrement dit :
Plan mode
→ fournit la frontière technique
Human approval
→ décide si l'on franchit cette frontière
C’est une distinction importante.
Claude peut proposer un excellent plan.
Cela ne signifie pas qu’il doit automatiquement être autorisé à l’exécuter.
Les trois questions à poser avant une tâche à haut risque
Le module propose trois questions particulièrement importantes avant de commencer une transformation majeure.
1. Quel est le blast radius ?
Il faut identifier :
- quels systèmes dépendent du code modifié ;
- ce qui pourrait casser en aval ;
- quelles parties du système seraient affectées par une mauvaise modification.
Conceptuellement :
Module modifié
↓
Service A
↓
Service B
↓
API externe
↓
utilisateurs
Une modification locale peut avoir des conséquences non locales.
2. Comment les changements seront-ils audités ?
Le module demande notamment si un PostToolUse hook journalise les tool calls et si cette trace répond aux besoins de la personne qui devra examiner ce que l’agent a touché.
Le workflow devient :
Claude
↓
tool call
↓
modification
↓
PostToolUse
↓
audit log
L’équipe dispose alors d’une trace déterministe des opérations.
3. Qui approuve chaque phase ?
Avant le travail, il faut déterminer :
Explore
↓
qui valide ?
Plan
↓
qui valide ?
Code
↓
qui autorise ?
Verify
↓
qui accepte le résultat ?
Le point important est de définir ces approbations avant la session.
Ne pas improviser la gouvernance lorsque l’agent a déjà commencé à modifier des centaines de fichiers.
Étape 3 : Code
Une fois le périmètre compris et le plan approuvé, Claude peut commencer les modifications.
Mais même à cette étape, l’autonomie ne doit pas être illimitée.
Le module recommande de combiner plusieurs mécanismes.
Utiliser CLAUDE.md pour définir la cible
CLAUDE.md peut contenir les conventions que la nouvelle architecture doit respecter.
Par exemple :
## Migration conventions
- Use the new repository abstraction.
- Do not introduce new calls to LegacyDatabaseClient.
- Preserve public API compatibility.
- Add tests for migrated behavior.
L’objectif est de donner à Claude une référence durable sur le target pattern.
Le fichier source explique que CLAUDE.md transporte les conventions de la nouvelle cible afin que l’agent les applique de manière cohérente dans tout le périmètre de changement.
Pourquoi c’est important dans une codebase legacy
Une difficulté particulière vient du fait que Claude lit beaucoup d’ancien code.
Si les anciens patterns dominent la codebase, le modèle peut être naturellement exposé à :
legacy pattern
legacy pattern
legacy pattern
legacy pattern
alors qu’on lui demande de produire :
new target pattern
CLAUDE.md permet de rendre explicitement cette cible persistante dans la session.
Le module souligne qu’il aide à éviter que l’agent ne dérive à nouveau vers les anciens patterns présents dans le code environnant.
Les Hooks pour empêcher certaines modifications
Pendant une migration sensible, certaines zones peuvent être strictement hors périmètre.
Par exemple :
/prod-config
/secrets
/database/manual-migrations
/vendor
Une simple instruction peut dire :
« Ne touche jamais à ces fichiers. »
Mais pour un garde-fou critique, le module recommande des mécanismes déterministes.
Les Hooks peuvent empêcher l’édition de certains chemins pendant les phases sensibles.
Conceptuellement :
Claude propose Edit
↓
PreToolUse
↓
path autorisé ?
/ \
oui non
↓ ↓
allow block
Pourquoi combiner CLAUDE.md et Hooks
Les deux mécanismes n’ont pas le même rôle.
CLAUDE.md
→ explique la stratégie et les conventions
Hook
→ impose une barrière
Pour une migration legacy :
"Utilise le nouveau repository pattern"
→ CLAUDE.md
mais :
"Ne modifie jamais /production/"
→ Hook / deny rule
La première est une instruction de conception.
La seconde est une contrainte de sécurité.
Limiter le scope des modifications
Un agent peut facilement produire une transformation très large.
Cela ne signifie pas qu’une grande transformation en une seule passe est souhaitable.
Le risque augmente avec :
nombre de fichiers
+
nombre de dépendances
+
nombre de comportements modifiés
Une stratégie plus contrôlable consiste à découper la migration.
Par exemple :
Phase 1
→ module A
Phase 2
→ module B
Phase 3
→ consommateurs
Phase 4
→ suppression du legacy
Chaque étape peut être validée avant la suivante.
Le principe de réversibilité
Le fichier source souligne que les changements legacy peuvent avoir une limited reversibility.
Plus une modification est difficile à annuler, plus le contrôle doit intervenir tôt.
On peut raisonner ainsi :
facilement réversible
↓
plus d'autonomie possible
difficilement réversible
↓
approval plus forte
C’est particulièrement important pour :
- migrations de données ;
- suppressions ;
- changements de schéma ;
- modifications d’interfaces utilisées par d’autres systèmes.
Human approval : placer la validation au bon endroit
Le but n’est pas d’exiger une validation humaine sur chaque modification triviale.
Cela supprimerait une grande partie du bénéfice de l’agent.
Il faut placer la validation humaine aux transitions à fort risque.
Par exemple :
Explore
↓
Plan
↓
[APPROVAL]
↓
Code
ou :
Code
↓
migration destructrice proposée
↓
[APPROVAL]
↓
exécution
L’approbation doit être proportionnée au coût d’une mauvaise action.
Étape 4 : Verify
Une fois les changements générés, le travail n’est pas terminé.
Il faut vérifier.
C’est pourquoi le workflow pratique doit se terminer par :
Verify
La génération de code n’est pas la preuve de sa correction.
Ce que Verify cherche à établir
La phase de vérification doit répondre à plusieurs questions.
Le code compile-t-il ?
Les tests passent-ils ?
Les comportements attendus sont-ils conservés ?
Les nouvelles conventions sont-elles respectées ?
Le périmètre réel correspond-il au plan ?
Selon le projet, cela peut inclure :
- tests unitaires ;
- tests d’intégration ;
- build ;
- linting ;
- type checking ;
- revue du diff ;
- validation fonctionnelle.
Le fichier source ne prescrit pas un ensemble universel de tests ; il insiste surtout sur la maîtrise du changement et sur la nécessité de vérifier ce que l’agent a effectivement touché.
Vérifier le diff, pas seulement le résultat final
Dans une migration importante, un système peut continuer à fonctionner tout en contenant des modifications inattendues.
Il faut donc également examiner :
quels fichiers ont changé ?
et :
pourquoi ?
C’est là que Plan mode et audit logging deviennent complémentaires.
On peut comparer :
Plan
→ fichiers prévus
à :
Audit / diff
→ fichiers réellement touchés
Tout écart mérite une explication.
Le rôle de PostToolUse dans la vérification
Le PostToolUse hook permet de disposer d’un journal des opérations.
Dans une transformation importante :
Plan prévu
↓
Claude exécute
↓
PostToolUse logs
↓
revue
L’organisation peut ainsi reconstituer la séquence des actions.
Le module présente ce mécanisme comme utile au-delà de la seule modernisation : toute tâche agentique à haut risque bénéficie de questions similaires sur le blast radius, l’audit et les approvals.
Claude peut trouver des problèmes sans avoir raison sur tout
Le module contient également un principe important concernant l’AI code review :
An AI code review gives you a set of findings to triage, not a verdict to apply.
Cela s’applique directement à la modernisation.
Claude peut signaler :
- un missing null check ;
- une ressource non fermée ;
- une incohérence visible dans le diff.
Ces éléments peuvent être examinés directement.
Mais une affirmation sur :
- le comportement réel en production ;
- les dépendances externes ;
- les performances runtime ;
- les effets sur un autre système ;
peut nécessiter une preuve supplémentaire.
Finding vs verdict
Il faut donc traiter la revue comme :
Claude produit un finding
↓
humain / tests vérifient
↓
finding confirmé ?
/ \
oui non
↓ ↓
action rejet
et non :
Claude dit qu'il y a un problème
↓
modification automatique
Le module recommande de placer le human gate lorsque le finding devient une action difficile à inverser.
Une architecture de migration contrôlée
En combinant les différents mécanismes, on obtient un workflow de ce type :
CLAUDE.md
conventions de migration
│
▼
Explore
│
Plan mode
│
▼
Plan
│
human approval
│
▼
Code
│
┌────────────┴────────────┐
│ │
PreToolUse guardrails PostToolUse audit
│ │
└────────────┬────────────┘
▼
Verify
│
tests + review
Chaque couche répond à un risque distinct.
Ce qu’il faut retenir pour la certification
Pourquoi commencer par Explore ?
Parce qu’une codebase inconnue contient des dépendances et des comportements implicites.
Modifier avant de comprendre augmente le blast radius.
Pourquoi utiliser Plan mode ?
Pour maintenir l’agent dans une phase d’exploration en lecture seule avant l’exécution des changements.
À quoi sert CLAUDE.md pendant une migration ?
À fournir les conventions et target patterns que Claude doit appliquer de manière cohérente pendant le changement.
À quoi servent les Hooks ?
À imposer des guardrails déterministes, par exemple empêcher l’édition de certains chemins sensibles.
Pourquoi auditer les tool calls ?
Pour pouvoir déterminer précisément ce que l’agent a réellement modifié.
Un PostToolUse hook peut fournir cette trace.
Quelles trois questions poser avant un travail à haut risque ?
- Quel est le blast radius ?
- Comment les changements seront-ils audités ?
- Qui approuve chaque phase ?
Une AI code review est-elle une preuve ?
Non.
Elle produit des findings à vérifier et à trier, pas un verdict à appliquer automatiquement.
Piège d’examen
Scénario :
Une entreprise veut utiliser Claude Code pour migrer une application legacy de grande taille. Les dépendances sont mal documentées et certains fichiers de production ne doivent jamais être modifiés. Quelle approche est la plus adaptée ?
Une mauvaise réponse serait :
« Utiliser
bypassPermissionsafin que Claude puisse terminer la migration rapidement. »
Cela optimise la vitesse au détriment du risque.
Une meilleure approche suit :
Explore
↓
Plan mode
↓
plan proposé
↓
human approval
↓
Code
↓
Hooks / restrictions
↓
PostToolUse audit
↓
Verify
avec les conventions de migration placées dans CLAUDE.md.
Le raisonnement central est :
Plus le blast radius est important et la réversibilité faible, plus les contrôles doivent intervenir avant l’exécution.
Le modèle mental à retenir
Pour une transformation importante avec Claude Code :
EXPLORE
Comprendre avant d'agir
↓
PLAN
Définir précisément le changement
↓
APPROVE
Valider le périmètre risqué
↓
CODE
Exécuter sous guardrails
↓
VERIFY
Tester et examiner le résultat
Autour de ce workflow :
CLAUDE.md
→ conventions
Hooks
→ enforcement
PostToolUse
→ audit
Human approval
→ décisions à fort impact
C’est cette combinaison qui permet de profiter de la capacité de Claude Code à travailler à grande échelle sans transformer cette capacité en autonomie incontrôlée.
Conclusion
La modernisation legacy n’est pas principalement un problème de génération de code.
C’est un problème de gestion du changement.
Claude Code peut explorer rapidement une grande codebase, proposer une stratégie et appliquer des transformations à grande échelle.
Mais cette puissance doit être encadrée par un workflow qui répond à trois questions avant l’exécution :
Quel est le blast radius ? Comment saurai-je exactement ce qui a changé ? Qui autorise le passage à l’étape suivante ?
Le principe à retenir est donc :
Explore → Plan → Code → Verify
avec Plan mode, CLAUDE.md, Hooks, audit et human approvals utilisés chacun pour le problème qu’ils savent réellement résoudre.
Dans la suite de la série
Claude Code, MCP et intégration : les 7 principes à retenir pour la certification
Le dernier article rassemblera les sept enseignements du module : permission modes, AI code review, portabilité des Skills, contexte durable, configuration partageable, transport et scope MCP, et sécurité des intégrations enterprise.
