Claude Code Plan Mode : des boucles de refactorisation guidées par la revue de conception

Beaucoup de développeurs commencent avec Claude Code de la même façon : coller une tâche, laisser tourner, puis vérifier le diff. Cela convient pour de petits changements, mais dès que plusieurs fichiers sont concernés, les limites apparaissent. 

Chaque décision non guidée que prend Claude peut être correcte la plupart du temps, ce qui semble acceptable jusqu'à l'effet cumulé : par exemple, si vous supposez 80 % de précision par décision, sur une fonctionnalité avec 20 points de décision, 0,8^20 fait chuter vos chances à environ 1 %.

Le Plan Mode change la donne en ajoutant une phase en lecture seule. Vous obligez Claude à lire la base de code, faire remonter les questions, puis produire un plan que vous validez avant de toucher au moindre fichier. 

Ce tutoriel détaille ce flux sur un exemple continu : une API de blog FastAPI désordonnée. Nous couvrons la boucle Explorer–Planifier–Exécuter, l'édition du plan avec Ctrl+G, et la montée en charge vers de plus gros refactorings avec Agent Teams. 

Notre tutoriel des bonnes pratiques Claude Code creuse davantage le problème des erreurs cumulées, et le guide Claude Code 2.1 vous accompagne pour l'installation et les fonctionnalités si vous avez besoin d'aide pour la mise en place.

Pour en savoir plus sur les modèles qui propulsent Claude Code, consultez nos guides sur Claude Sonnet 4.6 et Opus 4.6, ou suivez notre cours Introduction to Claude Models.

Qu'est-ce que le Plan Mode de Claude Code ?

Le Plan Mode verrouille Claude en opérations de lecture seule. Il peut lire des fichiers, rechercher dans la base de code et vous poser des questions, mais toute tentative d'écrire des fichiers, d'éditer du code ou d'exécuter des commandes shell est refusée. Demandez-lui de « corriger rapidement juste ceci » lorsque le Plan Mode est actif, et il ne bougera pas.

Vous pouvez l'activer de quatre façons :

• Shift+Tab deux fois dans le champ de saisie pour faire défiler Normal, Auto-Accept et Plan Mode

• La commande /plan bascule en Plan Mode jusqu'à ce que vous changiez à nouveau de mode

• Le flag CLI --permission-mode plan démarre une nouvelle session en Plan Mode

• Une entrée settings.json sous permissions.defaultMode définit le Plan Mode comme valeur par défaut permanente

Une fois le plan généré, Claude l'enregistre en fichier Markdown dans ~/.claude/plans/ avec un nom aléatoire (par exemple dreamy-orbiting-quokka.md). 

Ce fichier sert de contrat à relire : il persiste entre les sessions, survit à /clear et à la compactation du contexte, et rien n'est implémenté tant que vous ne l'avez pas approuvé. Notez que si le fichier de plan lui-même persiste, Claude peut parfois le perdre de vue après compactation du contexte, sauf si vous le poussez à relire le plan.

Si vous souhaitez conserver les plans dans votre projet pour le contrôle de version, définissez plansDirectory dans settings.json vers un chemin relatif au projet, par exemple ./plans.

Des plans relatifs au projet ouvrent des workflows que ~/.claude/plans/ ne peut pas supporter :

• Relire les diffs de plan dans des pull requests avant que quiconque ne commence à coder
• Conserver les annotations d'une session à l'autre sans dépendre de la compactation du contexte
• Traiter le fichier Markdown comme une spécification vivante que plusieurs membres de l'équipe peuvent éditer directement

Pour des refactorings au long cours ou un travail multi-sessions, un fichier de plan sous contrôle de version vous donne plus de maîtrise que Ctrl+G seul.

Mettre en place un workflow Explorer–Planifier–Exécuter avec Claude Code

Pour voir comment ces trois phases s'articulent, nous allons refactorer un dépôt fastapi-blog-api. Il n'inclut aucun test et comporte trois fichiers qui font chacun trop de choses : 

• main.py : toutes les routes, vérifications d'auth en ligne, configuration en dur, envoi d'e-mails

• models.py : modèles ORM, schémas Pydantic, fonctions de requête, données d'initialisation

• utils.py : hachage de mot de passe, jetons JWT, uploads S3, rendu Markdown, cache, limitation de débit, export CSV

Phase 1 : rassembler le contexte avant toute chose

Démarrez la tâche en Plan Mode (clonez d'abord localement le repo GitHub). Le prompt d'ouverture doit expliquer à Claude ce que vous souhaitez et l'orienter vers les fichiers pertinents :

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.Propulsé par

Claude délègue l'exploration de la base de code à un sous-agent intégré restreint aux outils en lecture seule. Il a lu les trois fichiers, retraçé les imports entre eux et utilisé AskUserQuestion pour faire remonter les ambiguïtés. 

Les questions portaient sur quelques choix de haut niveau :

• Profondeur architecturale (routers plats vs. couches de services complètes)
• Gestion de la configuration en dur
• Faut-il supprimer ou conserver les fonctions utilitaires mortes
• Quel framework de test utiliser

Ces questions comptent. Rien que la question d'architecture aurait relevé du pile ou face sans votre avis. Claude optera par défaut pour le motif le plus fréquent vu dans ses données d'entraînement, qui, pour FastAPI, est généralement une structure à routers plats. Répondre « utiliser une couche de services » ici a évité une boucle complète de re-refactoring plus tard.

Si vous avez un projet de référence qui correspond à votre cible architecturale, incluez un lien vers celui-ci dans votre prompt. Claude produit de meilleurs plans lorsqu'il dispose d'un exemple opérationnel plutôt que de descriptions abstraites.

Un point à vérifier avant d'accepter un plan : les questions de Claude citent-elles des fonctions et des détails ligne par ligne, ou seulement des noms de fichiers ? S'il évoque « le système d'auth » sans jamais mentionner verify_jwt_token ou la chaîne de middleware dans main.py, il a survolé les fichiers au lieu de les lire. Poussez-le à lire plus attentivement avant de passer à la phase 2.

Phase 2 : générer et éditer le plan

Après vos réponses, Claude génère automatiquement un plan. Aucun prompt séparé n'est requis. Le plan est enregistré dans ~/.claude/plans/ et inclut : 

• Un résumé du contexte
• La structure cible des répertoires
• Un ordre d'implémentation pas à pas
• Une section de vérification avec des commandes pour confirmer la réussite du refactoring

Avant de choisir comment poursuivre, appuyez sur Ctrl+G pour ouvrir le plan dans votre éditeur de texte par défaut (défini par $EDITOR). Vous pouvez aussi utiliser /plan open pour ouvrir directement le plan actif.

C'est à cette étape que le Plan Mode se rentabilise. Vous pouvez annoter les étapes avec des notes en ligne, supprimer celles avec lesquelles vous n'êtes pas d'accord, réordonner les opérations, puis enregistrer. Claude prend en compte chaque modification quand vous retournez au terminal.

Pour le plan de l'API de blog, les annotations pourraient ressembler à :

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.pyPropulsé par

Pour les plans complexes, un seul passage avec Ctrl+G peut ne pas suffire. Annotez, revenez, dites à Claude « traitez toutes les annotations du plan, n'implémentez pas encore », revoyez la version révisée, puis Ctrl+G à nouveau. Chaque tour d'annotation élimine une ambiguïté qui, sinon, se transformerait en une mauvaise décision d'implémentation.

Une fois le contrat conforme, Claude propose plusieurs options : 

1. Travailler sur le plan et effacer le contexte (utile quand la session devient obsolète), 
2. Travailler sans effacer (pour conserver l'historique), ou 
3. Continuer à échanger au sujet du plan. 

Choisissez selon la quantité de contexte accumulé. Si vous êtes dans une longue session, effacer offre à Claude une fenêtre fraîche pour l'exécution.

Phase 3 : exécuter le plan approuvé

Choisissez une option de travail et Claude commence à implémenter étape par étape. Il avance jusqu'à demander une intervention manuelle (comme une authentification interactive dans le terminal) ou jusqu'à l'achèvement du plan.

Surveillez la dérive. Le plan prévoyait d'abord d'extraire l'auth dans son propre module, mais Claude pourrait commencer à sortir routes et logique d'auth en même temps parce qu'il y voit un raccourci. C'est typiquement ainsi qu'on se retrouve avec une base de code à moitié migrée, où certains imports pointent vers l'ancien emplacement et d'autres vers le nouveau. 

Autres signaux de dérive : 

• Éditer un fichier non mentionné dans l'étape en cours
• Prendre silencieusement une décision d'architecture laissée ouverte par le plan
• Fusionner deux étapes que le plan gardait séparées

Quand il y a dérive, faites Shift+Tab pour revenir en Plan Mode. Claude lit l'état courant des fichiers, produit un plan révisé pour les étapes restantes, et vous le validez avant de continuer. Ce n'est pas une mesure d'urgence. La plupart des refactorings multi-fichiers passent par 2 à 3 révisions de plan avant d'être terminés.

Pour les refactorings qui ne tiennent pas dans une seule session, fractionnez le travail en plans séquentiels plutôt qu'en un seul gros plan. Finalisez l'extraction de l'auth sous son propre plan, puis lancez une session et un plan neufs pour le découpage des routes. 

Utilisez /rename pour nommer chaque session (par ex. : « blog-api-auth-extraction ») afin de reprendre facilement avec /resume. Des plans plus petits maintiennent la fenêtre de contexte focalisée et offrent un point d'arrêt naturel entre les phases.

Stratégies pratiques pour le Plan Mode de Claude Code

Maintenant que nous avons parcouru tout le processus une fois, voyons quelques bonnes pratiques pour tirer le meilleur parti du Plan Mode.

Quand utiliser le Plan Mode (et quand s'en passer)

Toutes les tâches n'ont pas besoin d'un plan. Les corrections sur une ligne, les fautes de frappe et les mises à jour isolées de fonctions sont plus rapides sans le surcoût de planification. Idem pour les changements mécaniques, comme renommer une variable dans un fichier.

Une bonne heuristique : si le changement touche trois fichiers ou plus, ou si vous ne pouvez pas décrire la modification complète en une phrase, planifiez d'abord. Trois fichiers, c'est typiquement le seuil où les erreurs cumulées commencent à mordre, chaque fichier ajoutant son lot de décisions que Claude doit bien prendre.

Tâches qui bénéficient toujours du Plan Mode :

• Refactorings qui déplacent du code entre des fichiers ou renommant des interfaces partagées
• Nouvelles fonctionnalités qui touchent des modules existants
• Mises à jour de dépendances avec des ruptures d'API
• Toute tâche où vous n'êtes pas certain de la manière dont la base de code gère un cas
• Séances de brainstorming où vous souhaitez itérer sur une approche avec Claude sans aucun risque de modifications prématurées

Détecter les plans faibles avant qu'ils ne coûtent cher

Un plan qui a l'air structuré n'est pas toujours un bon plan. Avec les versions actuelles de Claude Code, les références à des fichiers hallucinés et les étapes vagues « mettre à jour si besoin » sont rares. Le problème le plus probable est un plan qui liste toutes les étapes d'implémentation d'abord et relègue « ajouter des tests » à la fin.

Des plans structurés de cette manière donnent de moins bons résultats qu'attendu. Sans tests pendant l'implémentation, Claude n'a aucun moyen de vérifier son travail au fil de l'eau. Pour le refactoring de l'API de blog, un plan qui dit « Étapes 1–6 : extraire tous les modules, Étape 7 : écrire les tests » implique six étapes de code sans boucle de feedback. 

Un plan plus robuste adopte le TDD et alterne tests et implémentation : écrire les tests pour auth/ avant d'extraire les fonctions d'auth, confirmer qu'ils passent, puis écrire les tests pour posts/ avant de sortir les routes. Chaque test réussi donne à Claude un signal clair que le refactoring est sur la bonne voie. 

Ajouter des conventions TDD dans le CLAUDE.md de votre projet incite Claude à inclure par défaut des étapes de test. Les Claude Code Hooks peuvent automatiser ce type d'application en exécutant des scripts de validation qui contrôlent la qualité du plan avant d'approuver l'exécution.

Faire évoluer de grands refactorings avec Agent Teams

Les plans qui touchent sept fichiers ou plus perdent en qualité, car la fenêtre de contexte se remplit pendant l'exécution. Le refactoring de l'API de blog atteint ce seuil si l'on compte routes, modèles, services, configuration, tests et nouvelle structure de répertoires.

Agent Teams est une fonctionnalité expérimentale qui répartit ce type de travail entre plusieurs instances de Claude Code. Une session joue le rôle de lead d'équipe tandis que les coéquipiers disposent chacun de leur propre fenêtre de contexte indépendante. 

Pour l'API de blog, vous pourriez scinder en trois coéquipiers : un pour l'extraction des routes, un pour la couche base de données et modèles, et un pour la couverture de tests. Le lead assigne les tâches, les coéquipiers les réservent et les mènent à bien, et les tâches bloquées (par ex. « mettre à jour les imports » dépend de « extraire les modules ») se débloquent automatiquement quand les dépendances sont terminées. 

La même répartition fonctionne entre dépôts : si votre API dépend d'une bibliothèque partagée, un coéquipier peut refactorer la bibliothèque pendant qu'un autre met à jour son utilisation côté API.

La meilleure configuration pour le Plan Mode consiste à exiger l'approbation des plans des coéquipiers. Dites au lead : « Lance trois coéquipiers pour le refactoring de l'API de blog. Exige l'approbation des plans avant toute modification. » 

1. Chaque coéquipier planifie en mode lecture seule
2. Le lead revoit et approuve ou rejette avec feedback
3. Seuls les plans approuvés sont exécutés

Vous pouvez cadrer le jugement du lead en donnant des critères : « approuver uniquement les plans incluant une couverture de tests » ou « rejeter les plans qui modifient directement le schéma de base de données ». Activez Agent Teams en ajoutant "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" dans le bloc env de votre settings.json.

Pour une parallélisation plus simple sans le flag expérimental, les worktrees git permettent de lancer des sessions Plan Mode séparées sur des branches différentes, chacune suivant son propre plan.

Si une session au long cours subit une compactation du contexte, demandez aux coéquipiers de rouvrir explicitement et relire leurs fichiers de plan pour éviter la dérive.

Le tutoriel sur les plugins Claude Code présente d'autres méthodes pour gérer un travail en plusieurs phases.

Conclusion

La valeur du Plan Mode tient en une idée : relire avant d'exécuter. Chaque tour d'annotation que vous ajoutez, chaque question que Claude pose au lieu de deviner, supprime une décision qui avait des chances d'être mauvaise. 

Démarrez dès votre prochaine modification multi-fichiers : obligez Claude à planifier d'abord, puis éditez ce plan avec Ctrl+G avant d'accorder les droits d'écriture. Pour la configuration de CLAUDE.md, la gestion du contexte et les garde-fous à base de hooks, le tutoriel des bonnes pratiques prend le relais de celui-ci. 

Pour une vue d'ensemble du codage assisté par l'IA, nous vous recommandons notre parcours de compétences AI for Software Engineering, qui enseigne les fondamentaux et vous fait pratiquer sur des outils similaires comme GitHub Copilot, Windsurf ou Replit.