Pourquoi Claude Code est si bon

• Claude Code est un agent IA / workflow extrêmement performant en termes d’utilisabilité
• Grâce à sa simplicité architecturale et à sa boucle de contrôle claire, il offre une expérience qui facilite le débogage et la maintenance
• En minimisant l’adoption du RAG et en exploitant activement des prompts sophistiqués ainsi que des fichiers de contexte, il maximise les points forts des LLM
• Il maintient la clarté et la cohérence du travail grâce à divers outils et à des directives explicites
• Plutôt que de miser sur la complexité, il privilégie une structure facile à comprendre et la conception de prompts, avec l’avantage de permettre d’implémenter soi-même un agent LLM similaire

---

Vue d’ensemble

• Claude Code (ci-après CC) offre actuellement l’expérience la plus satisfaisante parmi les agents IA / workflows de code disponibles
• Les atouts de CC résident dans une édition de code adaptée à la cible, la réduction des distractions inutiles et une UX agréable qui préserve le contrôle de l’utilisateur
• Le modèle Claude 4 et son Interleaved Thinking caractéristique jouent un rôle clé, mais CC provoque encore moins de frictions que d’autres outils fondés sur le même modèle, comme Cursor ou Github Copilot
• Cet article dissèque les principes d’implémentation de CC et propose un guide pratique pour construire son propre agent LLM capable d’offrir une expérience similaire

La vertu centrale de Claude Code : la simplicité

• La leçon la plus importante est de « rester simple (Keep Things Simple, Dummy) »
• Dès qu’un agent LLM introduit une structure complexe (multi-agent, RAG complexe, système de vérification, etc.), il devient extrêmement difficile à déboguer et à améliorer
• CC adopte une boucle principale unique, un ensemble d’outils simple et une structure compréhensible d’un seul coup d’œil, en regroupant toute la logique essentielle dans un seul fichier afin d’éliminer le boilerplate inutile et la complexité superflue

Pourquoi la simplicité est importante

• Au lieu d’une architecture multi-agent, la majorité du travail est traitée dans un seul thread principal
  • Le résumé de l’historique, l’agrégation de messages pour l’UX, etc. sont appliqués sous forme d’assistance
  • Lorsqu’une tâche complexe est nécessaire, il peut se dupliquer lui-même pour bifurquer en sous-agent (pas de branchement récursif, limité à un seul niveau)
• Il exploite activement une liste de tâches (todo list)
  • Les problèmes complexes sont découpés dans des sous-agents, puis les résultats sont fusionnés dans l’historique principal des messages
  • Des structures multi-couches trop abstraites (agents multiples, navigation par graphe) risquent au contraire de réduire la stabilité et la scalabilité du système

Utilisation active de modèles légers

• Des modèles LLM légers comme claude-3-5-haiku sont utilisés pour la majorité des requêtes
  • Ils permettent de traiter efficacement de nombreuses tâches comme la lecture de gros fichiers, l’analyse de pages web ou le résumé de l’historique git
  • L’utilisation de modèles légers peut réduire les coûts jusqu’à 70 à 80 %
• Il est recommandé d’utiliser une combinaison de modèles optimisée pour chaque appel de fonctionnalité clé

Conception de prompts sophistiquée

• Le prompt système de CC est constitué d’un volume très important (environ 2800 tokens) et de nombreuses sections (ton & style, gestion des tâches, politique d’utilisation des outils, informations sur l’OS/répertoires, etc.)
  • L’intégralité des fichiers de contexte tels que claude.md est toujours incluse afin de maximiser la richesse du contexte
  • Le prompt système fournit des indications très détaillées sur les règles de politique, les exemples, les points d’attention et le moment d’utiliser les outils

Utilisation conjointe de XML et de Markdown

• Le prompt utilise à la fois des balises XML et une structure Markdown
  • Des éléments comme <system-reminder>, <good-example>, <bad-example> permettent de transmettre des informations détaillées et conditionnelles
  • Les titres markdown servent à délimiter clairement les sections

L’importance des fichiers de contexte

• La présence ou l’absence de claude.md entraîne une différence de performance très marquée pour CC
  • Il est indispensable pour transmettre des règles supplémentaires difficiles à déduire depuis la codebase (exclusion de dossiers/bibliothèques, politiques préférées, etc.)
  • MinusX organise lui aussi de façon structurée les préférences de l’équipe et des utilisateurs via minusx.md

Minimiser le RAG, exploiter la recherche par LLM

• CC préfère une architecture fondée sur la recherche directe dans le code avec des commandes comme ripgrep, jq, find, à la manière d’un vrai développeur, plutôt que sur le RAG (Retrieval Augmented Generation)
  • Cela constitue une alternative aux risques d’échec cachés liés aux configurations RAG complexes (par ex. fonction de similarité, reranker, chunking)
  • Comme le LLM explore et comprend directement le contexte réel du code, le nombre de composants en mouvement diminue, avec en prime un gain potentiel d’efficacité pour l’apprentissage RL

Conception des outils et hiérarchie

• CC prend en charge des outils bas niveau (Bash, Read, Write), intermédiaires (Edit, Grep, Glob) et haut niveau (Task, WebFetch, etc.)
  • Les outils nécessaires sont séparés individuellement en tenant compte de leur fréquence d’utilisation et de leur précision
  • Le prompt système précise clairement la description, les exemples et le moment d’utilisation de chaque outil
• Les tâches complexes sont gérées de manière cohérente via Task ou d’autres outils de haut niveau

Gestion explicite des Todo pour éviter la perte de contexte

• Pour résoudre un problème typique des agents LLM à longue exécution (perte de contexte, perte de direction), CC gère l’état via une liste de Todo maintenue explicitement
  • Au lieu d’un système multi-agent, le modèle met lui-même à jour les Todo, ce qui permet de préserver à la fois la direction du travail et la flexibilité

Contrôle du ton, du style et du niveau de familiarité de l’agent

• Le ton, le style et le niveau de proactivité sont gérés dans des sections séparées
  • Limiter les explications inutiles, n’autoriser les émojis que sur demande explicite, etc. : tout cela vise à concevoir une expérience utilisateur cohérente
• Des modificateurs forts comme « IMPORTANT », « NEVER » et « ALWAYS » servent à mettre en avant les points d’attention

Conception de l’algorithme de décision et du flux

• Les algorithmes principaux que le LLM doit suivre sont décrits clairement et illustrés par des exemples
  • Plus qu’une simple liste de Do/Don’t, les flowcharts et check-lists étape par étape sont plus efficaces pour préserver la stabilité de l’algorithme
  • La portée des rôles et les politiques sont structurées en tenant compte des conflits possibles entre plusieurs consignes et exemples

Design patterns et conseils pratiques d’application

• Ses opinions fortes et sa structure constituent un excellent benchmark immédiat pour concevoir son propre agent
  • Plutôt que d’abuser de frameworks qui compliquent tout, il est important de concevoir une structure simple et efficace
• Dans MinusX aussi, de nombreux principes sont déjà appliqués en pratique, avec l’intention de les étendre progressivement

Conclusion

• La plus grande leçon de Claude Code : « la simplicité est la plus grande des forces »
• Clarté structurelle, conception de prompts pertinente et combinaison d’outils légers rendent possible un agent LLM puissant
• Lors du développement de son propre agent LLM, il est très utile de s’inspirer activement de la philosophie de conception et des guides de CC

[kaydash]

J’adore tellement, je suis trop heureux, c’est le top, c’est trop doux, je veux continuer.

[GN⁺]

Avis Hacker News

• La conviction que la simplicité façon KISS finit toujours par l’emporter, et le sentiment que cet article était utile parce qu’il l’explique bien

• C’est dommage que Claude Code ne soit pas open source, mais il existe des outils qui permettent de mieux comprendre son fonctionnement interne ; si cela vous intéresse vraiment, recommandation de Claude Trace
  https://github.com/badlogic/lemmy/tree/main/apps/claude-trace
  Cet outil génère un fichier JSON montrant tous les outils et prompts utilisés dans une session, ainsi qu’un fichier HTML formaté pour une lecture plus facile

  • Si vous cherchez une alternative open source, suggestion de jeter un œil à OpenHands CLI
    https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file
  • https://github.com/anthropics/claude-code
    On peut aussi y consulter le prompt système
    Le modèle est apparemment entraîné à découper les tâches en plusieurs étapes et à les résoudre patiemment, avec une certaine robustesse face aux échecs

• Avis selon lequel il était intéressant de voir comment une organisation centrée sur les LLM aborde le sujet à une époque où les systèmes multi-agents attirent beaucoup d’attention ; la personne dit aussi expérimenter au quotidien différents points de vue en matière de design, ce qui lui parle
  Principaux enseignements :
  (1) Des prompts longs peuvent très bien convenir, et il faut absolument inclure des explications de base sur l’objectif des outils et la manière dont ils aident
  (2) L’appel d’outils est un aspect très fondamental, donc il faut mieux refléter le contexte — quand les utiliser, quand ne pas les utiliser, etc.
  (3) Gérer l’état du système sous forme de messages fonctionne bien ; des méthodes plus sophistiquées ont été envisagées (stockage en dataframe, parsing de variables, etc.), mais avec une fenêtre de contexte plus longue, de simples messages semblent suffisants

  • Les prompts longs sont utiles seulement si le modèle est optimisé pour bien les gérer ; la personne dit avoir remplacé le modèle dans Claude Code par d’autres, et avoir constaté que presque aucun modèle local ne gérait aussi bien que promis à la fois les prompts longs et l’usage des outils
    Des essais ont aussi été faits avec des modèles d’OpenAI et de Google Gemini, mais ils semblent moins bons que les modèles d’Anthropic et plus lents ; plus le prompt s’allonge, plus ils oublient les outils ou renvoient des résultats dans un mauvais format
  • (Auteur du billet) Avis selon lequel on peut obtenir de très bonnes performances dans 99 % des cas rien qu’en exploitant bien les fonctions de base ; il est important de garder une boucle simple et de fournir des outils clairs, même si certaines fonctionnalités se recoupent
    La clarté et la simplicité passent avant tout

• Question sur la comparaison entre Google Gemini (surtout la version Pro) et Claude ; la personne apprécie beaucoup de produits Google, mais s’inquiète de la tendance de Google à abandonner souvent ses produits, de son côté un peu brutal en matière de contrôle d’entreprise (Chrome, etc.) et des questions de censure

  • Gemini est particulièrement excellent quand on peut lui fournir d’un bloc les fichiers fusionnés de tout le dépôt pour en discuter ; son niveau de compréhension d’une base de code entière est étonnant, et il aide beaucoup sur la conception d’architecture ; Claude est jugé très en retrait sur ce point
    La stratégie personnelle décrite consiste à utiliser Gemini pour produire un résumé du projet et un plan de conception de haut niveau, puis à demander à gpt5 d’améliorer cela et de détailler le workflow (par exemple sous forme de document XML), avant de renvoyer le tout à Claude ; rien qu’avec cela, on évite presque entièrement que Claude parte dans tous les sens
  • Gemini Pro n’est pas mauvais pour le code, mais d’après l’expérience rapportée, Claude est bien meilleur pour les tâches liées au terminal (CLI, etc.) ; la plupart des CLI utilisent aussi beaucoup Claude
    https://www.tbench.ai/leaderboard
  • Pour l’interface web (chat), Gemini 2.5 Pro est plutôt apprécié ; dans les outils en ligne de commande, Gemini code ne sert à rien et Claude code est la plupart du temps lent
  • Gemini serait meilleur pour déboguer les problèmes difficiles où il faut suivre plusieurs appels de fonctions ; Claude, lui, est toujours prévisible et suit bien les instructions, surtout pour gérer des listes de tâches
  • La personne l’aimait beaucoup avant, mais a l’impression qu’il est devenu un peu plus bête récemment, et se demande si elle est la seule à le ressentir

• Opinion selon laquelle c’est avant tout le modèle de base lui-même qui est fort sur le vrai travail de développement, ce qui explique les bons retours des utilisateurs, davantage que sur des problèmes de benchmark classiques ; en essayant GitHub Copilot, Claude serait largement supérieur aux modèles d’OpenAI et de Google, avec un écart si grand que les autres modèles en deviennent pratiquement inutiles

  • Comme Anthropic peut optimiser en interne à la fois le modèle et le prompt pendant l’apprentissage par renforcement, le conseil de l’article consistant à « réutiliser tel quel les approches existantes » semble mieux convenir aux modèles d’Anthropic ; leur modèle par abonnement crée une forte incitation à optimiser l’efficacité de la boucle
  • Cela ne peut pas s’expliquer uniquement par la qualité du modèle de base ; quand la personne utilise opus et cline dans VS Code puis Claude Code, il est difficile de quantifier précisément l’écart de productivité, mais elle accomplit davantage de travail avec CC
  • Après avoir vu tant d’éloges, une personne a utilisé Claude Code pendant un mois avec de grandes attentes, pour finir encore plus déçue ; l’expérience lui a semblé inférieure à la sidebar de Cursor, et elle se demande si elle l’utilise mal, après avoir constaté beaucoup d’erreurs de code absurdes sur deux bases de code différentes

• Quelqu’un essaie en ce moment de déboguer avec Claude Code un problème lié à Elastic sur Security Onion, mais au bout de quelques minutes une avalanche de code JS obscur apparaît, suivie de l’erreur « Error: kill EPERM »
  En regardant les logs, la personne se demande si cela tue le processus Node.js et donc Claude lui-même, ou si Claude se ferme de lui-même parce qu’il n’arrive pas à résoudre le problème
  Quoi qu’il en soit, elle aimerait qu’il aide davantage tant que le processus tient encore

  • Claude et localstack ne s’accordent pas très bien sur certains points ; en Rust, en revanche, cela marche étonnamment bien
    Idée selon laquelle les langages, plateformes et architectures que les LLM maîtrisent le mieux vont peu à peu s’imposer ; par exemple, si les LLM gèrent nodejs 10 fois mieux, il devient rationnel d’utiliser nodejs dès le départ plutôt qu’Elixir ou Go ; même un développeur junior peut alors travailler à un niveau intermédiaire ou senior avec l’aide d’un LLM
  • Ce type d’erreur peut apparaître quand on utilise sudo pour lancer un processus avec des privilèges superutilisateur et qu’un timeout se produit
  • Dans certains cas, le problème se règle en mettant à niveau l’installation, ou en supprimant les fichiers d’installation existants puis en réinstallant ; c’est ainsi que la personne a corrigé le souci
  • Quelqu’un dit avoir basculé vers un autre LLM pour voir ce qui se passait (sans que ce soit un conseil officiel)
  • Une personne dit n’avoir jamais obtenu de bons résultats avec la combinaison Elasticsearch + LLM ; la plupart des réponses étaient des « hallucinations » sans fondement, probablement faute de bons exemples disponibles en ligne

• Une personne explique avoir construit l’intégralité du premier MVP de sa startup avec Claude Code, et avoir désormais des clients payants ; elle conserve bien sûr une inquiétude de fond à l’idée qu’un incident SEV puisse tout faire s’écrouler d’un coup, mais continue d’utiliser activement Claude pour corriger des vulnérabilités de sécurité, pratiquer le test-driven development et concevoir l’architecture logicielle selon une feuille de route à long terme
  Elle espère que ce genre d’histoire deviendra de plus en plus courant

  • Demande de partager un lien vers le produit, par curiosité et pour voir un cas réel d’utilisation
  • Question, sur le ton de la plaisanterie, demandant si « corriger des vulnérabilités de sécurité » signifie qu’au départ c’est Claude qui a écrit le code et créé aussi les vulnérabilités
  • Demande d’exemples concrets expliquant comment l’outil a aidé sur le test-driven development, la conception logicielle et d’autres aspects similaires
  • Blague disant que la personne a demandé à Claude Code de lui virer de l’argent tous les mois sur son compte bancaire, et qu’il l’a réellement fait
  • Retour demandant plus de transparence sur ce qui a été concrètement construit avec Claude Code

• Avis selon lequel, si l’affirmation « Keep things simple » est vraie, l’ensemble paraît malgré tout plutôt complexe
  La personne dit qu’elle a toujours réussi à faire beaucoup de choses avec une méthode simple consistant à poser un prompt à la fois selon le besoin
  Elle n’est pas convaincue de la valeur supplémentaire apportée par les structures complexes évoquées, par rapport à un prompt vraiment bien conçu
  Elle prend l’exemple d’un prompt en une phrase du type « comment faire une boucle while dans un langage que j’apprends » qui pourrait être plus efficace
  Le contrôle de flux paraît au contraire plus flou ; elle se demande aussi si les LLM exploitent vraiment correctement les appendices (outils ou prompt système), et si, quand la demande devient trop complexe, une partie n’est pas ignorée ou n’entraîne pas juste un gaspillage de tokens
  Pour elle, programmer en envoyant des prompts séparés par morceaux semble bien plus naturel
  Elle aimerait voir des exemples d’autres approches ou de prompts utilisés
  Elle se demande concrètement comment les gens construisent un programme complet avec des LLM, et voudrait voir des cas où le travail est découpé prompt par prompt

  • Quelqu’un dit utiliser exactement la même approche et être curieux de lire les réponses des autres

• À noter enfin que le lien minusx.com à la fin de l’article pointe vers un site dont le certificat de sécurité a expiré il y a 553 jours ; le site n’est donc pas valide, prudence