Comment utiliser Claude Code : séparer la planification de l’exécution

• Cette approche reconfigure en profondeur la manière d’utiliser les outils de codage IA, en proposant un workflow qui impose une étape explicite de revue du plan avant toute écriture de code
• Le principe central est : « ne pas laisser Claude écrire du code tant que le plan n’a pas été approuvé », ce qui permet d’obtenir à la fois un contrôle structurel et une utilisation plus efficace des tokens
• L’ensemble du processus suit une boucle Research → Plan → Annotation → Todo List → Implementation → Feedback
• À chaque étape, la collaboration s’organise autour de documents markdown (research.md, plan.md), enrichis par des annotations et des révisions successives pour améliorer le résultat
• Cette méthode met l’accent sur la séparation puis la combinaison de la capacité d’exécution de l’IA et du jugement humain, afin d’obtenir des résultats stables et cohérents, même sur des systèmes complexes

---

Vue d’ensemble du workflow

• Après environ 9 mois d’utilisation de Claude Code comme principal outil de développement, l’auteur a mis en place une procédure structurée séparant planification et exécution, au lieu du schéma classique « saisie d’un prompt → génération de code → itérations de correction »
• Avant que Claude n’écrive du code, l’exécution doit toujours se faire uniquement à partir d’un document de plan (plan.md) relu et approuvé par l’auteur
• Cette approche permet de réduire les essais-erreurs inutiles, de conserver la maîtrise des décisions d’architecture, et de maximiser la qualité par rapport au volume de tokens consommés

Phase 1 : Research

• Tout travail commence par une analyse approfondie de la codebase
  • Claude reçoit pour consigne de lire en profondeur un dossier ou une fonctionnalité donnée (detailed, intricacies)
  • Le résultat doit impérativement être consigné dans un fichier research.md
• Ce document sert de surface de revue pour vérifier le niveau de compréhension de Claude, et corriger les malentendus à ce stade
• Comme une mauvaise recherche mène à un mauvais plan puis à une mauvaise implémentation, cette étape bloque à l’avance la cause d’échec la plus coûteuse
• Cela permet par exemple d’éviter des problèmes comme l’ignorance d’une couche de cache, le non-respect de règles ORM ou la création de logique dupliquée

Phase 2 : Planning

• Une fois la recherche relue, Claude est chargé de rédiger un plan d’implémentation détaillé (plan.md)
  • Il inclut de vrais snippets de code, les chemins de fichiers à modifier et les trade-offs
  • Au lieu d’utiliser le mode plan intégré, l’auteur préfère un fichier markdown qu’il peut gérer directement
• Fournir en plus une reference implementation open source améliore fortement la qualité du plan produit par Claude
• Plus important encore que le document de plan lui-même : le cycle d’annotation qui suit

Cycle d’annotation

• L’auteur ouvre plan.md et y ajoute directement des commentaires inline
  • Correction d’hypothèses erronées, rejet d’une approche, ajout de connaissances métier, etc.
  • Exemples : « ça doit être un PATCH », « pas besoin de cache », « le champ visibility doit passer au niveau de la liste »
• Claude reçoit ensuite l’instruction de mettre à jour le document en tenant compte des annotations, sans encore implémenter quoi que ce soit
• Ce cycle annotation → mise à jour est répété de 1 à 6 fois, avec la consigne don’t implement yet pour éviter toute exécution prématurée
• Le document markdown fonctionne comme un état partagé plus clair et plus structuré qu’une suite d’instructions conversationnelles
• Grâce à ces itérations, un plan générique évolue vers une spécification parfaitement adaptée au système réel

Génération de la Todo List

• Avant l’implémentation, Claude ajoute une liste détaillée de tâches (todo list)
  • Elle contient les sous-tâches de chaque étape afin de suivre l’avancement
  • Claude peut marquer les éléments terminés, ce qui facilite le suivi même lors de longues sessions

Phase 3 : Implementation

• Une fois toutes les décisions arrêtées, l’exécution est lancée à l’aide d’un prompt standardisé
  • Par exemple : « ne t’arrête pas avant d’avoir terminé toutes les tâches », « pas de commentaires inutiles », « types any/unknown interdits », « typecheck en continu », etc.
• Cette commande transforme l’implémentation en phase mécanique d’exécution du plan, la part de jugement créatif ayant déjà été traitée en amont
• Implémenter directement sans plan revient à construire du code sur de mauvaises hypothèses ; la règle don’t implement yet est donc le garde-fou essentiel

Feedback pendant l’implémentation

• Pendant l’exécution, l’auteur passe à un rôle de superviseur
  • Les retours sont courts et explicites : « cette fonction manque », « déplacer vers l’app admin », etc.
  • Pour les changements frontend, il utilise aussi des consignes brèves comme « wider », « 2px gap », ou des captures d’écran
• L’auteur s’appuie souvent sur le code existant pour préserver une UI/UX cohérente
• Si le travail part dans la mauvaise direction, il est plus efficace de faire un git revert puis de réessayer avec un périmètre réduit que de corriger progressivement

Rester aux commandes

• Claude ne reçoit jamais une autonomie totale ; la décision finale revient toujours à l’humain
• L’auteur peut ne retenir qu’une partie des propositions de Claude, les modifier, les supprimer ou redéfinir les choix techniques
  • Exemples : « pour le premier, utiliser Promise.all », « ignorer les quatrième et cinquième », « supprimer la fonctionnalité de téléchargement », « ne pas changer la signature de la fonction », « utiliser la méthode de cette bibliothèque »
• Claude se charge de l’exécution mécanique, tandis que l’humain garde le jugement et la priorisation

Sessions longues uniques

• De la recherche à l’implémentation, tout se déroule dans une seule longue session
  • Au fil de la session, Claude accumule continuellement du contexte, avec suffisamment de mémoire grâce à l’auto-compaction
  • plan.md reste conservé dans sa forme complète pendant toute la session et peut être consulté à tout moment

Résumé clé

• « Lire en profondeur, écrire le plan, l’affiner par annotations, puis exécuter d’un seul coup. »
• Même sans prompts complexes ni consignes système élaborées, ce pipeline discipliné, qui sépare la réflexion (Thinking) de la frappe (Typing), permet d’obtenir une qualité élevée
• La phase Research empêche les modifications faites dans l’ignorance, la phase Plan empêche les mauvaises modifications, et l’Annotation injecte le jugement humain
• L’exécution finale n’est automatisée qu’une fois toutes les décisions arrêtées, ce qui aboutit à une structure de collaboration efficace

[naka98]

Je rencontre moi aussi régulièrement un problème similaire. Quand on collabore avec une IA uniquement via le chat, la décomposition du travail (WBS), l’avancement et l’historique des décisions ont tendance à devenir flous.

[pcj9024]

Le fait de simplement placer le fichier de plan dans le dépôt et d’enregistrer les modifications appliquées en exécutant ce plan permet de conserver assez bien le contexte.

[geekbini]

Ce contenu ne se limite pas à Claude uniquement ; il semble pouvoir s’appliquer de façon générale à d’autres services d’IA en CLI également.

[GN⁺]

Avis Hacker News

• Le vrai point clé n’est pas « planifier ou non », mais faire apparaître les hypothèses avant qu’elles ne se figent dans le code
  Les LLM échouent moins sur la syntaxe que sur des présupposés invisibles comme l’architecture ou les contraintes. Un plan documenté fournit donc une surface où ces hypothèses peuvent être déboguées

  • Dans cette optique, une architecture à sous-agents aide beaucoup. Si l’un s’occupe du plan, un autre de l’implémentation, et un troisième de la revue, les rôles deviennent clairs. On peut aussi faire une approche type blue team/red team. Au fond, l’essentiel est d’aider le LLM à raisonner correctement avec des consignes plus explicites
  • Inclure dans les instructions le flux complet du cas d’usage évite au modèle de partir dans des comportements aberrants
  • Mais le simple fait d’exposer ces hypothèses peut aussi modifier le comportement du modèle. Un peu comme quand on ajoute un printf() et que le Heisenbug disparaît
  • Presque pas d’erreurs de syntaxe ? Mon expérience est différente. En voulant ajouter un backend S3 à un petit projet Rust, Claude est entré dans une boucle d’hallucination d’API et a brûlé 20 $ en 30 minutes. Alors que ce n’était qu’un simple problème de syntaxe
  • Au fait, cet article n’a pas été écrit avec ChatGPT ?

• Certains disent qu’il faut utiliser des mots comme « en profondeur » ou « en détail » pour que Claude ne lise pas de manière superficielle, mais honnêtement je ne vois pas intuitivement pourquoi

  • C’est lié au mécanisme d’attention. Les LLM ont été entraînés sur tout l’internet, et les textes contenant des formulations comme « regardez les détails du problème » embarquent souvent des réponses de niveau expert. Quand ces mots apparaissent, le modèle donne donc plus de poids à cette partie des données. C’est la même raison pour laquelle des prompts du type « agis comme un professeur du MIT » peuvent fonctionner
  • Mais ce genre d’explication ressemble à de la superstition. Il n’y a pas de validation statistique solide, et ça donne l’impression d’une pensée magique, comme sacrifier quelque chose au dieu du soleil. Si ça marchait vraiment, on devrait pouvoir le démontrer comme un problème d’optimisation, or personne ne publie les données
  • On vit une époque vraiment étrange pour le développement logiciel. Personne ne sait vraiment pourquoi les LLM se comportent comme ça. On espère juste que les prompts déplacent les probabilités dans le bon sens. C’était autrefois un domaine déterministe, et maintenant on écrit des ordres en gras dans des fichiers AGENTS.md comme un parent qui parle à son enfant
  • Ce qui m’étonne, c’est qu’on continue à prendre ce genre de discours au sérieux. On dirait presque de l’astrologie pour ingénieurs
  • Si on imagine l’espace latent du modèle comme un relief, c’est plus simple à comprendre. Le prompt revient à faire tomber une balle à un endroit précis, et le choix des mots détermine dans quelle vallée elle va rouler. Des expressions comme « en profondeur » aident la balle à rester dans la zone souhaitée. Ce n’est peut-être pas une explication parfaite, mais ce modèle mental a bien marché pour moi

• J’utilise une structure composée de trois types de documents et de deux skills
  Les Specs sont les documents de conception statique du projet, les Plans sont les plans d’exécution générés par le LLM, et les fichiers de Working memory servent à suivre l’avancement.
  J’utilise le planner skill de Gemini Pro pour créer de nouveaux plans, puis le implementer skill de Codex pour les exécuter.
  Avec ça, le contexte reste léger et focalisé, donc l’efficacité est bonne. Même avec les offres à 20 $ de Codex/Gemini, ça avance suffisamment vite

  • J’ai une approche similaire. Je crée des fichiers spec à partir d’articles scientifiques, puis je fais évoluer le plan en interagissant avec Claude. Je gère des documents exigences–tests–spécifications dans un style d’ingénierie système proche de l’IEEE. Claude suit bien quand on lui donne des garde-fous. Il me convient mieux que Codex
  • Bonne approche. En revanche, je me demande si le monorepo n’est pas un meilleur choix à l’ère de l’IA. Dans notre entreprise, nos apps Next.js sont réparties sur plusieurs dépôts, et on se demande s’il ne vaudrait pas mieux tout regrouper

• L’idée de laisser directement des annotations dans le document de plan me paraît très fraîche. Je me demande s’il existe une façon de conserver ces annotations séparément ou de les gérer pour pouvoir les revoir plus tard

• Il y a plusieurs choses qui me déplaisent dans cette approche
  D’abord, la méthode big bang qui consiste à générer tout le code d’un coup produit un énorme bloc de code difficile à comprendre. À mon avis, mieux vaut planifier et exécuter étape par étape.
  Ensuite, je trouve dommage de donner du feedback sans mettre à jour la base de connaissances. Il faudrait enregistrer la cause des erreurs pour éviter de les répéter ensuite.
  Enfin, il n’y a aucune mention des tests. Il faudrait intégrer au moins un peu de développement piloté par les tests (TDD). C’est intéressant de voir comment le développement assisté par IA pourrait fusionner avec ce type de méthodologie

  • J’ai eu une expérience similaire. Je découpe PLAN.md par étapes et je rédige soigneusement les prompts pour n’exécuter qu’une seule étape à la fois. J’inclus aussi les tests dans le plan, mais pour l’instant je les ajoute plutôt vers la fin

• Ce workflow est en fait la méthode standard de Claude Code recommandée par Anthropic. Mais son inconvénient, c’est que si le plan n’est pas parfait, il faut tout recommencer depuis le début.
  Du coup, je fractionne design → plan → exécution en plusieurs lots. Quand les plans restent sous les 1 500 lignes, il est plus facile de garder la complexité sous contrôle.
  Mon application de 30 000 LOC s’accompagne de 100 000 lignes de plan. Impossible de produire ça d’un seul coup

  • Même expérience de mon côté. Du coup, je découpe en plans plus petits et je gère les commits avec des branches par fonctionnalité. Grâce à l’IA, mes habitudes de développement se sont même améliorées
  • En fait, c’est un peu gênant de présenter comme « radicalement différent » un workflow qui consiste simplement à utiliser le mode Plan par défaut
  • Moi aussi, je pense que l’exécution incrémentale est la bonne réponse. Terminer un projet gigantesque d’un seul coup reste encore une illusion
  • Ce n’est pas grave si le plan n’est pas parfait. Il suffit d’annuler uniquement les parties modifiées par l’IA, puis de repartir de l’étape précédente. La clé, c’est de réduire la complexité avec des changements de petite taille
  • 100 000 lignes de plan, c’est presque un million de mots. Rien que les lire prendrait 66 heures. Ce n’est pas réaliste

• Au lieu de plan.md, je travaille surtout autour de scaffolds exécutables et de boucles de validation
  J’ai construit avec l’IA un vrai système de paiement appelé Kolibri Tickets. L’important n’est pas que le modèle tape vite du code, mais de concevoir la boucle de validation

  • garder dès le début une base exécutable
  • n’ajouter à la fois qu’une fine tranche verticale
  • imposer des artefacts vérifiables comme les tests, les types ou les machines à états
  • banaliser le refactoring
    De cette façon, on peut réellement déployer plus vite, au lieu de tomber dans une simple « illusion de vitesse ». Le document de plan est une façon de maintenir un état partagé, mais un harnais vérifiable en est une autre
  • Moi aussi, maintenant que le code coûte moins cher à produire, je vise une couverture de tests à 100 %. J’introduis du typage statique en Python, des tests Playwright et même du mutation testing. Désormais, des agents peuvent tourner pendant une heure en boucle et produire du code qui ne demande presque plus de corrections

• J’utilise Claude Code pour préparer des cours
  J’écris mes notes de cours avec Quarto, puis je demande à Claude de les convertir en slides Slidev. Ensuite, j’ajoute des annotations sur les slides du genre « séparer ceci en deux diapositives » ou « ajouter une image ici » pour donner du feedback.
  Ce feedback par annotations est extrêmement puissant. Ça aide beaucoup pour la distance de tokens et le maintien du contexte

  • Quarto prend déjà en charge plusieurs formats comme PowerPoint, PDF ou HTML. Du coup, je me demande pourquoi utiliser Slidev. On ne pourrait pas simplement demander à Claude de régénérer le document Quarto ?
  • Je me demande si le feedback est laissé sous forme de commentaires inline, par exemple # remplacer cette partie par X ?
  • Est-ce que ce skill Claude a été publié en open source ?

• Des outils comme Kiro d’Amazon, Antigravity de Google, le Spec Kit de GitHub et OpenSpec offrent déjà ce type de fonctionnalité

• L’échec le plus coûteux dans le codage assisté par IA n’est pas l’erreur de syntaxe, mais une implémentation qui fonctionne partiellement tout en cassant le système dans son ensemble
  C’est pourquoi j’ajoute dès le départ un fichier brief.md qui précise la définition du problème, les métriques cibles et les critères d’arrêt d’une fonctionnalité. Cela réduit le coût des décalages entre les objectifs métier et l’implémentation technique