Faire de Claude Code le meilleur partenaire de conception

• Au début, en utilisant Claude Code, l’approche consistait simplement à enchaîner instructions de prompt et cycles de correction, mais pour les tâches complexes, cela a révélé des problèmes de dépendance à l’historique de la conversation et de limites de contexte
• Pour y remédier, on lui fait rédiger un document de planification (plan document) avant toute implémentation, qui devient dans une nouvelle session l’unique source de vérité (SSOT)
• Le document de planification contient une reformulation des exigences, des explications sur les détails d’implémentation, des commandes de vérification de la qualité du code, etc., et continue d’être mis à jour pendant l’implémentation comme un document vivant (living document)
• Cela permet de résoudre les problèmes de perte de contexte, et de reprendre le projet dans une nouvelle session à partir de ce seul document
• Au final, l’IA ne sert plus seulement d’outil d’exécution, mais joue le rôle d’un partenaire de conception collaboratif qui pousse le développeur à réfléchir et documenter plus en profondeur sa conception

---

Constats : les limites d’une approche par simple conversation

• Lorsqu’on travaille avec Claude Code de manière conversationnelle, cela convient aux tâches simples, mais à mesure que les tâches complexes prennent de l’ampleur, plusieurs limites majeures apparaissent
  • La conversation devient l’unique source de vérité, si bien qu’un nouveau message peut facilement écraser une instruction précédente, sans qu’il soit toujours facile d’identifier clairement quand cela se produit
  • En raison de la limite de taille du contexte de l’IA, plus la conversation s’allonge, plus certaines informations antérieures risquent d’être perdues
  • Même si Claude Code dispose d’une fonction de compression des conversations, cela ne supprime pas complètement cette limite

Expérimentation d’une approche centrée sur le document de planification

• Pour résoudre ce problème, une approche fondée sur un document de planification a été testée
  • Au démarrage, on demande à Claude Code de décrire aussi précisément que possible la fonctionnalité à implémenter ou le bug à corriger
  • On mentionne également les fichiers source existants ou les documents de planification déjà rédigés qui peuvent servir de référence
  • On évite les consignes d’implémentation trop détaillées afin d’encourager le rôle de proposition de conception de l’IA
• Une fois le document de planification jugé suffisamment satisfaisant, on efface l’historique de conversation et on redémarre avec ce seul plan comme contexte
  • Le plan comprend un résumé de la fonctionnalité, un plan d’implémentation, du code et du pseudocode, ainsi que des commandes de type checking, lint et test

Un processus de conception collaboratif

• Quand la conception proposée par l’IA ne convient pas, on fournit un retour précis afin d’orienter vers une approche révisée
• Au fil des échanges, on peut aussi se rendre compte que la première proposition de l’IA était plus adaptée, ce qui s’avère plus efficace que de coder uniquement à partir de sa propre conception
• Une conversation structurée offre une expérience proche de celle d’une discussion de plan avec un collègue développeur
• L’IA ne propose pas spontanément une approche totalement différente, mais peut suggérer d’autres alternatives si on l’interroge

La méthode du document vivant (Living Document)

• Le document de planification n’est pas rédigé une fois pour toutes : il continue d’être mis à jour tout au long de l’implémentation
  • Les changements révélés pendant l’implémentation, le contrôle de types, le lint ou les tests y sont reflétés en temps réel
• On prend l’habitude, à chaque commit de code, de demander une vérification de l’état le plus récent du plan
• Comme le plan reste constamment à jour, il suffit de le joindre à une nouvelle session de conversation pour reprendre exactement où l’on s’était arrêté, sans perte de contexte

Revue de code et évolution des habitudes de développement

• Une fois l’implémentation commencée, on vérifie périodiquement les changements et, si le résultat est satisfaisant, on tend à accorder davantage de confiance au travail de l’IA
• Lors de la revue finale du code, le document de planification mis à jour aide à comprendre les fondements des décisions techniques
• Le fait de préparer et documenter minutieusement un plan en amont permet de devenir un meilleur développeur
  • Comme il faut l’expliquer à l’IA, on clarifie plus nettement son propre processus de décision

Du chaos à la méthode

• Cette approche fait du document de planification la source unique de vérité, résout les problèmes de perte de contexte et favorise une réflexion architecturale
• Le document de planification contient à la fois la spécification et le journal d’implémentation, en documentant non seulement le « quoi », mais aussi le « pourquoi » et le « comment »
• Le résultat final est un processus de développement planifié, bien documenté et fiable
• L’IA s’impose non plus comme un simple exécutant, mais comme un partenaire de conception collaboratif

[jamsya]

Il semble que, dans le workflow des développeurs, le rôle de PM et celui d’architecte prennent une place plus importante.

[GN⁺]

Commentaires sur Hacker News

• Depuis deux semaines, je passe mes soirées à utiliser Claude Code avec une concentration intense pour fabriquer le « prompt parfait » capable de terminer un projet d’un seul coup. Au final, j’ai structuré un seul fichier CLAUDE.md pour qu’il référence huit autres fichiers Markdown différents, couvrant l’architecture du projet, les spécifications des modèles, l’ordre de build, la pyramide de tests, les scénarios, etc. Ce projet concerne la gouvernance basée sur les modèles de Databricks Unity Catalog ; j’ai beaucoup d’expérience sur le sujet, mais je n’ai jamais trouvé les outils existants assez flexibles. Au bout du compte, je me suis fait aider dans le travail sur les vrais fichiers de conception par trois sous-agents : un expert Databricks, un expert Pydantic et un expert prompt. Grâce à ça, la qualité des fichiers Markdown s’est énormément améliorée sur plusieurs points, depuis d’anciens problèmes de versions de Pydantic jusqu’à mes propres malentendus sur Unity Catalog. Hier, je l’ai vraiment lancé, et à part quelques validations d’usage d’outils de ma part, la plupart des outils et des tests ont été terminés en deux heures. Cette manière de travailler est tellement différente de ce que je faisais avant que ça m’a fasciné ; j’ai vraiment l’impression qu’il y a un avenir dans le fait de rédiger une documentation technique rigoureuse et d’aligner tout le monde sur une même direction. J’ai même l’impression que c’est plus productif que d’aller fouiller soi-même directement dans le code. En revanche, quand je codais, mon niveau de concentration était élevé, alors qu’avec plusieurs documents Markdown, mon attention se disperse plus facilement. Quelle époque fascinante

  • J’ai l’impression qu’un nouveau pattern émerge, un peu comme le Test-Driven Development, en poussant à concevoir le système à l’avance. Avant, on dessinait progressivement le système en écrivant le code ; avec ce type de développement basé sur l’IA, on conçoit et on cartographie le domaine en amont, et le code réel devient presque un simple travail de boilerplate qui matérialise la conception. Et l’IA est vraiment forte sur ce boilerplate

  • J’ai exactement le même problème : je suis plus productif, mais ma concentration se fragmente davantage. C’est bizarre, mais pour l’instant c’est efficace. À long terme, il faudra sans doute trouver une solution. La méthode qui me convient le mieux en ce moment, c’est de faire travailler plusieurs agents sur différentes tâches dans différents dépôts du projet, tout en continuant à approuver leurs actions. J’ai un peu l’impression d’être un chef de projet qui dirige une équipe à grande échelle. Là aussi, époque fascinante

  • C’est une approche vraiment rafraîchissante. Je me demande quel est le framework qui fait tourner les agents dans les expériences réelles

  • En ce moment, je note aussi à la voix les détails produit, les parcours utilisateurs, etc., puis je m’en sers pour lancer le processus de documentation technique. CLAUDE.md minimal, workflow GitHub pour le développement logiciel, mais créer un bon workflow CI reste difficile. Mon playbook est ici : https://nocodo.com/playbook/

• L’idée selon laquelle « les résultats sont meilleurs quand on planifie d’abord » ne me parle pas vraiment. Depuis toujours, pour les grosses fonctionnalités ou les projets importants, je réfléchis naturellement à l’avance à la structure, aux raisons et à la manière de faire, que ce soit dans ma tête, sur papier, dans Confluence ou sur un tableau blanc. Les 80 % du génie logiciel, c’est le processus qui consiste à décider et clarifier le “quoi, pourquoi, comment”. On valide les idées et les objectifs avec les parties prenantes, on fait aussi de la recherche. Les 20 % restants seulement, c’est le codage proprement dit. Ça a toujours été comme ça, et je ne suis pas sûr que l’IA soit indispensable pour faire une vraie planification ou une bonne définition des objectifs

  • C’est peut-être vrai dans les grandes équipes ou les environnements avec une culture bien installée, mais une grande partie du développement se concentre sur des projets personnels, de petites équipes, des side projects, des POC rapides ou des outils d’automatisation à usage unique. Ce genre de travail ne commence pas forcément par de la documentation, des spécifications ou des tests ; on avance plutôt en mélangeant code, réflexion et implémentation. Il y a des cas où le TDD est adapté, et d’autres où il n’est pas nécessaire. Mais depuis l’arrivée des agents de code IA, le processus qui consiste à définir clairement l’idée et à l’organiser en spécifications est devenu bien plus important. Il faut vraiment verbaliser tout ce qu’on a en tête. Le langage de programmation le plus hot du moment, c’est l’anglais

  • J’ai plutôt tendance à mélanger développement et conception. Je commence par coder, puis j’affine et fais évoluer au fil de l’eau. Dans la plupart des cas, la solution générale est assez évidente, donc je n’ai pas l’impression qu’il faille passer beaucoup de temps à planifier en profondeur

• Avant, le prompt engineering était un sujet de blague, mais maintenant je le ressens vraiment. Il m’arrive de passer 10 à 20 minutes sur un prompt détaillé et une planification initiale soignée pour utiliser Claude Code de manière systématique. Comme l’OP, je sauvegarde aussi les plans dans des fichiers, puis je les exécute dans un nouveau contexte. Ce que je voudrais vraiment, c’est un bon CLI (j’utilise actuellement charm et cc). Ce serait idéal si on pouvait utiliser des modèles différents pour l’implémentation, la planification et chaque sous-agent. Une architecture où l’implémentation tourne sur un modèle local, tandis que la planification se fait sur un modèle cloud, avec possibilité de permutation si besoin pour économiser de l’argent. Parmi les outils que j’ai testés jusqu’ici, Charm gère très bien les allers-retours sans perte de contexte. La fonction de sous-agents parallèles est aussi l’une des meilleures fonctionnalités de Claude Code. (J’ai essayé CCR, mais j’ai été déçu qu’il ne fasse pas mieux que le modèle par défaut)

  • Si le prompt engineering est devenu un sujet aujourd’hui, c’est à cause des hot takes Twitter et des usages liés à la production de contenu. Mais en réalité, le prompt engineering a toujours été important. GIGO (« Garbage In, Garbage Out ») est une vérité dans tous les projets de machine learning. C’est pourquoi je continue à dire à mes collègues et à mes amis qu’il faut l’utiliser soi-même. Ce qui ne marchait pas il y a six mois peut marcher aujourd’hui. Il faut l’avoir en main pour voir ce qui a changé et ce qui fonctionne. Personnellement, je trouve les cas de réussite concrets, les blogs, les gist et les exemples bien plus utiles que les réactions négatives. Ce n’est pas juste pour faire un calcul simple ou trouver une faute de frappe ; il faut que ça améliore et soutienne mon workflow. Le prompt engineering, c’est un peu comme à l’époque où il fallait devenir très bon sur Google il y a 10 ou 15 ans, en apprenant en permanence les nouveaux changements et les patterns efficaces

  • Pour collaborer avec l’IA, le prompt engineering est vraiment central

  • Les projets où j’utilisais l’IA étaient ceux qui étaient le mieux documentés et testés. Comme il faut absolument du contexte pour tirer de bonnes performances d’un LLM, la documentation devient meilleure, et comme le coût de production des tests a baissé, il y a plus de tests. Contrairement aux prédictions disant que la qualité du code allait baisser, je pense qu’elle va au contraire s’améliorer

  • Honnêtement, le terme « prompt engineering » désigne une forme d’architecture conçue à l’aide d’un nouveau média. Comme autrefois la compétence de « conception de diagrammes » était valorisée, on est aujourd’hui face à une nouvelle manière de faire de l’architecture

• J’ai essayé Claude Code rapidement récemment, et je compte tester le workflow recommandé. Ça a l’air d’être une assez bonne approche. Par contre, le coût de CC est plus élevé que je ne le pensais. J’ai fait un simple refactoring : 5 minutes de travail + 15 minutes de revue, et ça m’a coûté 4 dollars. Si je l’avais fait moi-même, ça m’aurait pris 15 à 20 minutes. Je me demande combien vous dépensez en général avec CC par fonctionnalité. Personne ne parle des prix

  • Avec un abonnement, il y a un tarif fixe de 20 à 200 $ avec des limites d’usage de tokens journalières et hebdomadaires. https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan

  • La direction que souhaitent les investisseurs IA, c’est une structure où le marché du travail est remplacé par l’IA avec une marge de 15 %. Une époque va arriver où le budget développeur et le budget IA seront équivalents en 1:1. Par exemple, le poste d’un développeur senior payé 100 k$ sera remplacé par un budget IA de 100 k$. Le budget IA sera prélevé sur les coûts de développement, les salaires seniors risquent de baisser et la taille des équipes de développement pourrait diminuer brutalement. Pour l’instant, on est dans une phase de « conquête de territoire » entièrement subventionnée par le VC, mais vu l’ambiance des VC sur Twitter, cette phase semble proche de la fin. Continuer à relever encore et encore 500 millions de dollars pour 9 mois de runway finit par atteindre ses limites

  • Depuis que j’ai déplacé une partie de mon usage de Cursor vers Claude Code, les coûts ont beaucoup augmenté. Comme je l’utilise surtout au travail, convaincre mon manager a été facile, mais pour les side projects, ça me fait réfléchir. Je n’ai pas envie de payer 20 dollars chaque fois que je bootstrappe une app juste pour le fun

  • On peut s’abonner en choisissant entre Sonnet (20 euros/mois) et Opus (100 euros/mois). J’ai commencé avec Sonnet, puis je suis passé plus tard à Opus. Sonnet est déjà largement utilisable. Tant que je reste dans les limites de tokens, ça me suffit pour mon usage. Mais je ne sais pas ce que ça donnera à l’avenir

  • Tu dis « si je l’avais fait moi-même, ça m’aurait pris 15 à 20 minutes », mais peut-être que tu pourrais utiliser ces 15 à 20 minutes sur autre chose

• Ma façon d’utiliser le combo Visual Studio Code/ChatGPT5 preview ressemble à mon workflow {je pense probablement payer via un abonnement GitHub Copilot, mais en ce moment je n’en suis plus très sûr}. J’ai l’impression que les LLM non agents ont une forte tendance à dégrader rapidement le code. En passant en mode agent, la manière de construire le code change radicalement. Je ne suis pas développeur Python, mais j’ai été réellement impressionné en voyant le LLM générer tout un nouveau bloc de code. Une fois terminé, j’aimerais faire tourner un petit LLM dans BitGrid, puis comprendre totalement le code a posteriori. L’idée, c’est de répéter de petites phases d’exploration, puis de ne faire que quelques corrections pour garder le design global conforme à ce que je veux. Ça m’a rendu confiant dans l’avenir où les LLM deviendront des partenaires de programmation. Je me demande si d’autres utilisent aussi la combinaison Visual Studio Code/ChatGPT5

• Je trouve intéressant que, dans la recherche d’optimisation des outils IA, les développeurs redécouvrent la valeur d’une « bonne communication » et d’une « bonne définition des attentes ». L’image du développeur 10x telle qu’on l’a connue jusqu’ici, celle de l’outsider ou du génie excentrique, mérite sans doute d’être reconsidérée

• J’ai eu une expérience similaire sur Replit. Quand l’application grossit, si les documents de conception ne deviennent pas la source de vérité pour les tâches, tout s’effondre très vite. OpenAI devient lent et plante rapidement dans les chats, donc créer la documentation séparément puis l’importer dans un nouveau chat aide beaucoup. J’ai aussi eu le sentiment qu’au niveau humain, c’est ce que nous devrions faire nous-mêmes. En pratiquant l’auto-rétrospective, en documentant et en inscrivant notre « mémoire » dans les documents de design, on peut libérer à la fois nous-mêmes et les LLM

• J’ai moi aussi découvert récemment ce workflow, et ça m’a vraiment surpris. Le point important, c’est de ne fournir à Claude que les exigences minimales et de laisser tourner librement le mode plan. Si c’est un rapport sur des métriques commerciales, il suffit par exemple de dire « Ultrathink relevant sales metrics » et il propose différents indicateurs, puis permet de les classer et de les filtrer. Je crée un répertoire séparé pour chaque nouvelle fonctionnalité et je lui fais rédiger le plan de cette fonctionnalité dans un fichier. Ensuite, je lui fais dérouler les étapes une par une : plan d’implémentation, requêtes de données nécessaires, implémentation réelle, tests, rédaction de la documentation utilisateur, puis envoi en QA. Avant, il fallait une grosse équipe et beaucoup de temps pour produire une simple fonctionnalité de prévision des ventes ; désormais, Claude l’implémente dans un conteneur Docker en une demi-journée. Ce changement est en train de modifier ma vision du logiciel. Avant, à cause des NDA, de la PI, etc., les entreprises ne laissaient absolument jamais sortir leur code source. Mais maintenant, même un système ERP complexe construit en 20 ans peut être réimplémenté rapidement par Claude, avec documentation et tests en plus. En pratique, ce n’est pas encore parfait, mais la vitesse d’avancement est vraiment impressionnante

• Pour obtenir de bonnes fonctionnalités avec Claude Code, le point clé est de bien écrire le plan en amont. Récemment, j’utilise GPT-5 High dans Cursor pour élaborer le plan, puis je l’envoie à Claude Code pour l’implémentation. Si on lui fait documenter à l’avance les parties du codebase à modifier, on obtient encore 15 à 20 % de meilleurs résultats. Quand le modèle de plan documente le mode de fonctionnement, l’architecture, les patterns, puis y intègre aussi la conception de la fonctionnalité, le résultat est meilleur. Enfin, relire et corriger soi-même la documentation et le plan aide énormément

  • Dans l’entreprise, on utilise Google Workspace, donc Gemini est très puissant pour l’écriture en « style académique », mais reste plus faible que CC pour écrire du code. Du coup, je fais détailler suffisamment le plan par Gemini, puis je le donne à CC pour qu’il adapte et implémente cela dans mon codebase. Avec cette méthode, j’ai vu des effets étonnants aussi bien pour le développement de nouvelles fonctionnalités que pour l’extension de fonctionnalités existantes. En huit semaines, un produit que j’ai construit moi-même est déjà utilisé en vraie production, avec des démos clients en cours. Je suis très satisfait de l’expérience et des résultats avec CC. Comme je l’avais déjà expliqué sur HN, notre équipe aurait pu en réaliser une bonne partie avec ses propres effectifs, mais nous n’aurions même pas osé nous attaquer au frontend. Ce qui aurait pris plus d’un an, avec davantage d’ingénieurs et de data scientists, a été réalisé en grande partie en seulement deux mois. Ajouter des fonctionnalités ne prend plus du temps, mais presque « quelques secondes ». Grâce à CC, je trouve intéressant de voir mon expérience se diffuser à d’autres personnes

• Je me demande si quelqu’un a trouvé une bonne façon d’intégrer élégamment le design frontend dans ce type de processus. La plupart du temps, ça se limite à la mention d’un framework frontend ou à une image Figma. Je n’ai pas l’impression qu’on obtienne ainsi une vraie solution de design intégrée