Plan mode et specs

Qu’est-ce que le plan mode ?

Le plan mode de Claude Code (activé via /plan ou --plan) force l’agent à rédiger un plan structuré avant d’agir. La sortie est un document que tu peux lire, modifier, approuver ou rejeter. Aucune écriture, aucune commande, aucun changement de fichier n’a lieu tant que tu n’as pas validé le plan.

Point clé : Le plan mode n’est pas un mode « lent ». C’est un mode « réfléchi ». Le temps passé à valider un plan d’une page est largement inférieur au temps perdu à corriger un agent qui est parti dans la mauvaise direction sur 12 fichiers.

Cas d’usage typiques :

• Changements multi-fichiers avec dépendances croisées.
• Migrations de stack ou de framework.
• Refactos non triviaux qui touchent à l’architecture.
• Toute tâche dont la mauvaise direction coûterait plus cher à corriger que la planification ne coûte à produire.

Le principe 80-20 Planning

Règle empirique : investir environ 20% du temps en planification permet d’éliminer environ 80% des mauvaises directions. C’est le levier le plus rentable du développement agentique.

Les deux erreurs symétriques

• Pas de plan du tout : on lance l’agent, on découvre 30 minutes plus tard qu’il a fait fausse route. Coût de correction élevé.
• Sur-planification : on rédige un plan détaillé ligne par ligne. Coût de planification supérieur au coût d’exécution.

Ce qu’un bon plan contient

• L’objectif en 1 à 3 phrases.
• La liste des fichiers impactés.
• Les contraintes (« ne pas casser l’API publique », « garder le module X intact »).
• Un ou deux exemples de code existant à suivre comme modèle.

Attention : Ce qu’un bon plan ne contient PAS : du pseudo-code ligne par ligne, l’implémentation interne détaillée, ou un découpage en sous-étapes microscopiques. Spécifie le quoi, laisse l’agent décider du comment.

Spec-first : la spec comme contrat

L’approche spec-first consiste à transformer la demande en spec écrite avant tout code. PRD → tests → code. La spec est rédigée par toi, ou co-rédigée avec l’agent à partir d’une demande informelle.

Pourquoi ça paie

• Tu valides la direction sur du texte, beaucoup moins coûteux que sur du code généré.
• La spec devient la mémoire du « pourquoi » : utile lors d’un --resume, ou pour briefer un sub-agent sans rejouer toute la conversation.
• Elle sert d’oracle pour les tests : si le test correspond à la spec, l’implémentation suit.

Point clé : Une spec écrite vaut mieux qu’un plan négocié à l’oral. Elle survit à la fin de la session et reste auditable.

Quand planifier (et quand ne pas le faire)

Règle de pouce : si la tâche prend moins de 10 minutes à l’agent et touche un seul fichier, le plan mode est surdimensionné. Sinon, c’est le défaut raisonnable.

Pièges fréquents

• Approuver sans lire : si tu n’as pas relu le plan, il ne sert à rien. Pire, il te donne une fausse sécurité.
• Plan figé : si l’agent découvre une contrainte imprévue en exécutant, le plan doit pouvoir évoluer. Ne pas l’imposer comme une loi.
• Confondre plan et spec : le plan dit « comment on va faire les changements », la spec dit « quel comportement le système doit avoir ». Les deux peuvent coexister.
• Inflation des plans : à mesure que l’équipe les utilise, ils ont tendance à grossir. Au-delà d’une page, ils deviennent illisibles et ne remplissent plus leur rôle de filtre.

Point clé : Le bon test — ton plan tient-il sur une page et te ferait-il dire « non, attends » si l’agent prenait une mauvaise direction ? Si oui, il fait son travail.