Penser comme un Agent : la philosophie de conception d'outils de l'équipe Claude Code

Thariq est ingénieur chez Anthropic et l'un des principaux contributeurs de Claude Code. Fin février, il a publié un long article sur X, partageant cinq cas concrets sur la conception d'outils pour agent issus de la construction de Claude Code — non pas un cadre théorique, mais des retours d'expérience de terrain. Cet article a récolté 3,51 millions de vues, 209 réponses et 9 691 likes, suscitant de nombreuses discussions de qualité.

Pour introduire la question centrale de l'article, Thariq utilise une excellente analogie : imaginez que vous êtes face à un problème mathématique difficile, de quels outils avez-vous besoin ?

Un stylo et du papier représentent le minimum — mais vous êtes limité au calcul manuel. Une calculatrice est mieux — mais vous devez savoir utiliser les fonctions avancées. Un ordinateur est le plus puissant — mais il faut savoir coder.

Le choix de l'outil dépend des capacités de l'utilisateur. Donner un ordinateur à quelqu'un qui ne sait pas programmer est moins utile que de lui donner une calculatrice. Donner une calculatrice à un programmeur limite au contraire son potentiel.

C'est la même chose pour un agent. La question n'est pas « quel outil est le plus puissant », mais « quel outil correspond le mieux aux capacités actuelles du modèle ». Cet article partage les erreurs commises par l'équipe Claude Code dans sa quête de ce point d'adéquation.

Voici quatre thèmes progressifs que j'ai extraits de l'article original et des discussions de la communauté.

---

Moins, c'est plus — le paradoxe du nombre d'outils

L'intuition nous dit que plus un agent a d'outils, plus il est performant. Mais l'expérience de l'équipe Claude Code prouve exactement le contraire.

Claude Code ne dispose actuellement que d'environ 20 outils, et l'équipe examine constamment si tous sont réellement nécessaires. La barre pour ajouter un nouvel outil est élevée, car cela représente une option supplémentaire que le modèle doit prendre en compte — chaque outil ajouté augmente la « charge cognitive » du modèle lors de ses prises de décision.

Cette découverte a fortement résonné dans la communauté. leon.M a partagé son expérience pratique :

La recherche CodeAct d'Apple apporte un soutien quantitatif à ce point de vue : une seule primitive d'exécution de code (code execution primitive) surpasse les ensembles d'outils spécialisés et complexes de jusqu'à 20 % sur les tâches difficiles. Moins peut effectivement signifier plus.

Les trois itérations de l'outil AskUserQuestion constituent le meilleur exemple de ce principe. L'équipe Claude Code souhaitait améliorer la capacité de Claude à poser des questions aux utilisateurs — bien que Claude puisse poser des questions en texte brut, y répondre semblait trop fastidieux. Comment réduire cette friction ?

Première tentative : ajouter un paramètre à ExitPlanTool pour qu'il présente un ensemble de questions en même temps que le plan. Résultat — Claude s'est embrouillé. Lui demander simultanément de produire un plan et des questions sur ce plan posait problème : que faire si la réponse de l'utilisateur entre en conflit avec le plan ?

Deuxième tentative : modifier les instructions de sortie pour que Claude pose des questions dans un format markdown spécifique, puis parser et formater côté frontend. Résultat — instable. Claude ajoutait des phrases supplémentaires, omettait des options, ou utilisait un format complètement différent.

Troisième tentative : créer un outil AskUserQuestion indépendant. Claude peut l'appeler à tout moment ; l'appel déclenche une fenêtre contextuelle affichant la question et bloque la boucle de l'agent jusqu'à ce que l'utilisateur réponde. Cela a fonctionné.

Thariq a écrit une phrase particulièrement intéressante dans l'article original :

Claude semble prendre plaisir à appeler cet outil, et nous avons constaté que la qualité de ses sorties était excellente. Même un outil parfaitement conçu ne fonctionne pas si Claude ne comprend pas comment l'appeler.

phuong a posé une question perspicace : « "Claude semble prendre plaisir à appeler cet outil" est la phrase la plus fascinante et la moins expliquée ici. Comment détectez-vous l'"affinité" du modèle pour un outil — en lisant les transcripts ou via des métriques internes de fréquence d'appel ? Si cette heuristique pouvait être plus précise, elle changerait la façon dont tout le monde conçoit les outils d'agent. »

Cette question est restée sans réponse, mais elle pointe vers une intuition importante : le critère de succès de la conception d'outils n'est pas "l'humain trouve ça logique", mais "le modèle comprend comment l'utiliser et a envie de l'utiliser".

Emeka a ajouté une leçon très directe du point de vue du développement d'outils en entreprise : « J'ai essayé de contrôler chaque entrée et sortie possible en construisant des outils pour un agent, et le modèle a tout simplement... contourné le système. Économisez vos efforts d'ingénierie, faites confiance au modèle pour gérer l'ambiguïté. »

---

Les outils deviennent obsolètes — l'effet de carcan après une montée en capacité

Si « moins c'est plus » concerne la dimension spatiale, « les outils deviennent obsolètes » est une leçon dans la dimension temporelle.

Un outil qui aidait le modèle peut, à mesure que le modèle progresse, devenir une contrainte.

Lors du lancement initial de Claude Code, l'équipe a réalisé que le modèle avait besoin d'une liste de tâches pour maintenir le cap — il pouvait y inscrire des éléments au démarrage, puis les cocher au fur et à mesure. Pour cela, ils ont fourni à Claude l'outil TodoWrite. Mais malgré cela, Claude oubliait fréquemment ce qu'il devait faire.

L'équipe a répondu en insérant un rappel système toutes les 5 itérations de conversation pour rappeler à Claude ses objectifs.

Mais avec les progrès du modèle, le problème s'est inversé : non seulement le modèle n'avait plus besoin qu'on lui rappelle sa liste de tâches, mais il percevait ces rappels comme une contrainte. Les rappels répétés de la liste de tâches donnaient à Claude l'impression qu'il devait suivre strictement la liste, au lieu de s'adapter de manière flexible selon les besoins. Parallèlement, Opus 4.5 s'était considérablement amélioré dans l'utilisation de sous-agents, mais comment coordonner une liste de tâches partagée entre sous-agents ?

L'équipe a donc remplacé TodoWrite par le Task Tool. La différence entre les deux est fondamentale : les Todos servaient à maintenir le modèle sur la bonne voie — comme un patron surveillant la liste de tâches d'un employé ; les Tasks sont davantage axés sur la communication entre agents — comme un tableau de collaboration d'équipe. Les Tasks supportent les dépendances, le partage de mises à jour entre sous-agents, et le modèle peut les modifier et les supprimer.

De TodoWrite à un rappel toutes les 5 itérations, puis au Task Tool — ce sont trois reconceptions. Non pas parce que les conceptions précédentes étaient « mauvaises », mais parce que le modèle avait évolué.

Le commentaire de modi résume parfaitement ce phénomène :

Cela soulève également un débat intéressant. Danny Cosson estime que AskUserQuestion est « en réalité une mauvaise conception » — il force le modèle de texte en entrée / texte en sortie très élégant de Claude Code dans un mode d'interaction spécifique, avec très peu de bénéfices.

Mais la réponse de @Toong est convaincante : la valeur d'AskUserQuestion réside en deux points — l'initiative (indiquer explicitement au modèle qu'il a le droit de poser des questions) et la gestion d'état (distinguer clairement la sortie texte standard de l'état de blocage « en attente d'intervention de l'utilisateur »).

Un même outil, deux évaluations radicalement différentes. Cela illustre parfaitement ce que Thariq dit en conclusion : la conception d'outils est un art, pas une science. Elle dépend du modèle que vous utilisez, des objectifs de l'agent et de l'environnement dans lequel il opère.

---

Laisser l'Agent trouver ses propres réponses — du « gavage » à la « recherche autonome »

C'est la partie de l'article que je considère comme la plus utile en pratique.

Claude Code utilisait initialement une base de données vectorielle RAG pour fournir du contexte à Claude. RAG est puissant et rapide, mais pose deux problèmes : d'une part, il nécessite une indexation et une configuration qui peuvent être fragiles selon les environnements ; d'autre part, et c'est plus fondamental — cette approche fournit le contexte à Claude au lieu de le laisser le trouver lui-même.

L'équipe a effectué un changement clé : puisque Claude sait chercher sur le web, pourquoi ne pourrait-il pas chercher dans votre base de code ? En fournissant à Claude l'outil Grep, ils l'ont laissé chercher les fichiers et construire son propre contexte.

Le commentaire de Beacon va droit au but :

En un an, Claude est passé d'une quasi-incapacité à construire son propre contexte à la capacité d'effectuer des recherches imbriquées sur plusieurs couches de fichiers pour trouver précisément le contexte nécessaire. La clé de cette évolution n'a pas été de donner plus d'informations à Claude, mais de lui donner de meilleures capacités de recherche.

Lorsque Claude Code a introduit les Agent Skills, l'équipe a formellement proposé le concept de divulgation progressive (Progressive Disclosure) : permettre à l'agent de découvrir progressivement le contexte pertinent par l'exploration.

L'implémentation concrète est élégante : Claude peut lire des fichiers skill, et ces fichiers peuvent référencer d'autres fichiers que le modèle peut lire récursivement. Un usage courant des skills est de donner à Claude des capacités de recherche supplémentaires — par exemple des instructions sur l'utilisation d'une API ou l'interrogation d'une base de données.

Brian Wagner a partagé sa pratique en trois couches, parfaitement alignée avec l'approche de Claude Code :

SKILL.md reste concis (environ 100 lignes), le contexte lourd est placé dans des fichiers que Claude découvre quand il en a besoin. J'appelle ça la troisième couche. Vous l'appelez divulgation progressive. C'est la même chose.

PrimeLine a même construit un système quantifié à trois niveaux : configuration JSON (environ 500 tokens) > résumé du schéma (environ 300 tokens) > markdown complet (environ 3K tokens). Un routeur de contexte décide quelle couche charger en fonction des mots-clés de la tâche.

La logique centrale de cette stratégie en couches est la suivante : le contexte est une ressource limitée à rendements marginaux décroissants. Déverser toutes les informations d'un coup dans l'agent gaspille non seulement des tokens, mais dilue aussi les informations vraiment importantes. Fournir l'information à la demande et laisser l'agent décider quand il a besoin de détails plus approfondis — voilà l'approche scalable.

Le sous-agent Claude Code Guide est une autre application ingénieuse de la divulgation progressive. L'équipe a remarqué que Claude ne connaissait pas suffisamment le fonctionnement de Claude Code lui-même — si vous lui demandiez comment ajouter un MCP ou ce que fait une commande slash, il ne pouvait pas répondre.

Ils auraient pu tout intégrer dans le prompt système, mais les utilisateurs posent rarement ce type de questions, et cela aurait augmenté l'érosion du contexte, interférant avec le travail principal de Claude Code : écrire du code.

Ils ont d'abord essayé de donner à Claude un lien vers la documentation pour qu'il cherche lui-même — ça fonctionnait, mais Claude chargeait un grand volume de résultats dans le contexte pour trouver la bonne réponse. La solution finale a été de construire un sous-agent dédié : Claude Code Guide. Ce sous-agent dispose d'instructions de recherche détaillées et sait comment chercher efficacement dans la documentation et quoi renvoyer. Sans ajouter le moindre nouvel outil, l'espace d'action de Claude a été élargi.

Lance Martin, dans son article sur les modèles de conception d'agents, propose une perspective complémentaire : plutôt que de définir des dizaines d'outils pour l'agent, donnez-lui un ordinateur et laissez-le orchestrer les outils par le code. L'abstraction fondamentale de Claude Code est le CLI — l'agent vit sur votre ordinateur et accomplit des tâches complexes à travers des primitives de base comme bash et le système de fichiers. Quelques outils atomiques (comme l'outil bash) sont plus flexibles et consomment moins de tokens qu'un vaste ensemble d'outils.

---

Empathie envers le modèle — penser comme un Agent

Les trois thèmes précédents — moins c'est plus, les outils deviennent obsolètes, laisser l'agent trouver ses propres réponses — partagent une méta-méthodologie commune. Thariq l'a clairement énoncé dès le début de l'article : voir le monde comme un agent.

Ce n'est pas un ensemble de règles, mais un mode de pensée. David Zhang lui a donné un nom :

L'empathie envers le modèle — il ne s'agit pas de concevoir des outils « logiques » du point de vue humain, mais de réfléchir du point de vue du modèle à ce qu'il voit réellement, comment il va comprendre et comment il va utiliser l'outil.

Terminally Drifting a résumé en trois étapes la leçon que chaque équipe agent finit par apprendre :

1. Vous concevez des outils pour des humains
2. Le modèle les utilise comme un raton laveur avec les droits administrateur
3. Vous les reconceptualisez pour l'économie de tokens et les effets secondaires prévisibles

« Penser comme un agent » est la percée décisive.

Vish a partagé son expérience de déclic : « Nous construisions sans cesse des interfaces d'outils logiques pour les humains, sans comprendre pourquoi l'agent faisait des choix étranges. Dès que vous inversez le modèle mental et que vous réfléchissez à ce que le modèle voit réellement dans la définition de l'outil, tout change. »

Emeka a exprimé la même idée du point de vue du développement d'outils en entreprise : « Tout est par défaut conçu selon le modèle mental humain — les schémas, les noms de champs, les processus, tout est optimisé pour la lecture humaine. Mais pour un agent, c'est le mauvais cadre de référence. »

Cette « inversion du modèle mental » est simple à énoncer, mais demande une pratique constante. Vous devez lire attentivement les sorties de l'agent — non pas pour voir ce qu'il a bien fait, mais pour comprendre pourquoi il a fait certains choix, où il a hésité, où il a fait des détours. Ces « comportements anormaux » ne sont souvent pas des bugs du modèle, mais des bugs de conception d'outils.

Plusieurs perspectives complémentaires intéressantes ont émergé des discussions de la communauté.

OAIR a soulevé un angle mort : toutes ces itérations d'outils supposent que l'agent est sans état — chaque session repart de zéro. Et si l'« outil » le plus important ne se trouvait pas dans l'espace d'action, mais dans une mémoire persistante sur le fonctionnement de la base de code ? Claude Code a partiellement répondu à cette question par la suite avec les fichiers CLAUDE.md et le système de mémoire, mais la gestion de l'état persistant reste un problème ouvert dans la conception d'agents.

Clinker a proposé un autre principe de conception : optimiser la récupérabilité (recoverability) plutôt que la capacité brute — des préconditions d'outils explicites, un état observable et des tentatives peu coûteuses sont souvent plus efficaces que l'ajout rapide de nouveaux outils. Cela rejoint le principe du génie logiciel qui consiste à « rendre le système tolérant aux pannes plutôt qu'infaillible ».

Le résumé de 范式折叠 est le plus incisif :

La conception de l'action space est fondamentalement une conception de pouvoir — les permissions que vous donnez à l'IA déterminent son rôle. C'est exactement comme gérer une équipe : vous pensez que le goulot d'étranglement est la compétence des gens, alors qu'en réalité c'est le périmètre de permissions que vous avez tracé.

---

En conclusion

Revenons à la conclusion de Thariq :

Expérimentez davantage, lisez vos sorties, essayez de nouvelles approches. Observez comme un agent.

En tant qu'utilisateur assidu de Claude Code, ma principale impression après avoir lu cet article est la suivante : ces fonctionnalités qui semblent « naturelles » sont le fruit d'innombrables itérations de type « ça ne marche pas, essayons autrement ». AskUserQuestion a nécessité trois tentatives, TodoWrite a été reconçu trois fois, RAG a été remplacé par Grep. Chaque amélioration n'est pas venue d'une idée plus brillante, mais d'une observation attentive du comportement réel du modèle.

Le sous-titre de cet article est « Seeing like an Agent » — voir le monde comme un agent. Mais vu sous un autre angle, c'est aussi l'essence de toute bonne pratique d'ingénierie : ne pas concevoir un système depuis sa propre perspective, mais depuis celle de l'utilisateur. Sauf que cette fois, l'utilisateur est un modèle d'IA.

À l'avenir, chaque développeur construisant des agents devra probablement maîtriser ce que David Zhang appelle l'« empathie envers le modèle ». Ce n'est pas une capacité mystérieuse — elle repose sur trois choses : observer le comportement réel du modèle, lire ses sorties, puis ajuster la conception en fonction de ce que vous observez.

Observez comme un agent.

---

Lectures complémentaires :