4 principes de conception d'outils que Claude Code a appris après 3 refontes

Moins d’outils, et l’IA a mieux fonctionné. Quand on construit un agent, l’instinct le plus naturel est de se dire : « s’il manque une fonctionnalité, ajoutons un outil de plus. » L’équipe d’Anthropic a passé un an à développer Claude Code et a découvert exactement l’inverse. Chaque outil supplémentaire augmente la charge cognitive de l’IA — « dois-je appeler cet outil ou non ? » — et ce coût s’accumule.

J’ai vécu exactement le même piège en construisant mes propres agents, c’est pourquoi le récit de Thariq, développeur de l’équipe Claude Code, m’a autant marqué. Voici la chronologie de comment ils ont ajouté, supprimé et reconçu leurs outils.

Un outil, un rôle — sinon l’IA se bloque

C’est le tout premier problème auquel l’équipe Claude Code s’est heurtée. Ils avaient besoin d’une fonctionnalité pour poser des questions aux utilisateurs, alors ils l’ont intégrée dans l’outil de « planification ». L’implémentation a été rapide, mais l’IA essayait de formuler un plan et une question simultanément. Quand la réponse de l’utilisateur contredisait le plan, l’IA ne savait plus trancher.

Leur deuxième tentative consistait à faire produire les questions en format Markdown. L’IA ignorait constamment le format ou ajoutait du texte superflu. C’est au troisième essai, en séparant la fonctionnalité en un outil dédié — AskUserQuestion — que tout s’est enfin stabilisé. Un outil, un rôle. Ça semble évident, mais on ne le comprend vraiment qu’après s’être brûlé.

• Plan + question combinés — L’IA appelait le même outil deux fois par erreur
• Sortie en format Markdown — L’IA ajoutait des phrases ou ignorait la structure
• Outil dédié séparé — Les réponses structurées sont enfin devenues fiables
• Peu importe la qualité de la conception, si l’IA ne veut pas appeler l’outil, c’est inutile

Les outils ont une date de péremption

Avoir bien séparé les outils ne suffit pas. J’appellerais ça la « péremption des outils (tool decay) » — le phénomène où un outil autrefois essentiel devient un frein après une mise à jour du modèle.

Au début, Claude Code avait un outil de liste de tâches (Todo), et le système envoyait des rappels toutes les cinq interactions : « N’oubliez pas votre liste de tâches. » Après l’amélioration du modèle, ces rappels ont eu l’effet inverse. L’IA s’accrochait obstinément à son plan initial même quand elle aurait dû l’adapter. Quand Opus 4.5 a rendu possible la collaboration entre sous-agents, la structure Todo existante ne permettait tout simplement pas le partage de tâches entre agents.

Ils ont fini par tout remplacer par le Task Tool.

• TodoWrite remplacé par Task Tool — Partage des dépendances entre agents rendu possible
• « Cet outil est-il encore pertinent ? » nécessite un examen périodique, aussi important qu’ajouter de nouveaux outils
• Prendre en charge moins de modèles accélère ces décisions
• La forme de l’outil compte plus que leur nombre — elle doit correspondre aux capacités du modèle

Servir le contexte sur un plateau rend l’IA moins performante

Au fil du processus d’ajout et de suppression d’outils, l’équipe Claude Code a découvert un schéma plus fondamental : laisser l’IA trouver l’information elle-même donne de meilleurs résultats que de la lui injecter.

Au départ, ils utilisaient une base de données vectorielle RAG pour pré-charger le contexte. C’était rapide et puissant, mais l’indexation se cassait selon les environnements, et l’IA devenait passive — ne s’appuyant que sur ce qu’on lui donnait. En lui fournissant un outil Grep pour chercher directement dans le code, la qualité du contexte s’est améliorée. En ajoutant des fichiers Skills par-dessus, ils ont créé une structure où l’IA pouvait explorer récursivement les fichiers référencés dans d’autres fichiers.

C’est ce que j’appelle la divulgation progressive (progressive disclosure) — au lieu de tout donner d’un coup, l’IA découvre ce dont elle a besoin par elle-même.

• RAG — Forte dépendance à l’environnement, l’IA consomme passivement le contexte
• Grep + Skills — L’IA explore activement plusieurs couches de fichiers
• En un an, passage d’une « IA incapable de trouver le contexte » à une « IA qui le trouve elle-même »
• Extension des capacités via les fichiers Skills seuls, sans nouvel outil

Étendre les capacités sans ajouter d’outils

Ce schéma de divulgation progressive a brillé dans un autre cas. Les utilisateurs posaient des questions sur l’utilisation de Claude Code, et il ne savait pas répondre. L’équipe aurait pu tout mettre dans le prompt système, mais ce type de question n’arrive qu’occasionnellement. Quand des informations rarement utilisées occupent en permanence la fenêtre de contexte, elles dégradent la performance sur la tâche principale — écrire du code. J’appelle ça le bruit contextuel (context rot).

La solution a été un sous-agent dédié. Quand une question d’utilisation arrivait, un agent guide cherchait dans la documentation et ne renvoyait que la réponse. Le nombre d’outils restait identique, mais les capacités de l’IA augmentaient.

• Toutes les infos dans le prompt système — Le bruit contextuel dégrade la qualité du code
• Fournir uniquement des liens vers la documentation — L’IA charge trop de résultats dans le contexte
• Sous-agent dédié + consignes de recherche — Réponses propres et ciblées
• Résolu en changeant la structure, pas en ajoutant des outils

Il n’y a pas de formule magique

Ajouter, supprimer et reconcevoir des outils — il n’existe pas de formule universelle pour ce processus. Quand les modèles changent, les outils doivent changer aussi. La structure optimale d’hier peut devenir le goulot d’étranglement de demain.

Une chose que l’équipe Anthropic a répétée tout au long de l’année : lire les sorties de l’IA, expérimenter et corriger à nouveau. Au final, ceux qui construisent les meilleurs agents sont ceux qui savent se mettre à la place de l’IA.