"Seeing like an Agent" — lessons from building Claude Code (tool design first-party)¶

Resume¶

Article first-party de l'equipe Claude Code (4M vues, 28.5K bookmarks) sur le design des tools pour agents. Principe fondateur : "see like an agent" — se mettre a la place du modele pour designer les outils qu'il sait utiliser.

4 lecons concretes, chacune documentee avec les echecs avant la solution retenue :

1. AskUserQuestion — 3 tentatives¶

Conclusion : meme le meilleur tool ne sert a rien si le modele ne comprend pas quand l'utiliser.

2. TodoWrite → Task Tool (evolution avec les capabilities du modele)¶

• V1 : TodoWrite + rappels systeme toutes les 5 turns pour garder Claude on track
• Probleme : les rappels rendaient Claude rigide — il s'accrochait a la liste au lieu de l'adapter
• Opus 4.5 : meilleur en subagents, mais comment coordonner sur une todo partagee ?
• V2 : Task Tool — dependances, partage inter-subagents, modification/suppression dynamique

Principe : "As model capabilities increase, the tools that your models once needed might now be constraining them."

3. RAG → Grep → Progressive Disclosure (construction de contexte)¶

• V1 : RAG vectoriel (indexation + setup, fragile, contexte donne a Claude au lieu de cherche par Claude)
• V2 : Grep tool — Claude cherche lui-meme dans le codebase
• V3 : Progressive Disclosure via Skills — fichiers qui referencent d'autres fichiers, decouverte recursive

"Over the course of a year Claude went from not really being able to build its own context, to being able to do nested search across several layers of files to find the exact context it needed."

4. Guide Agent (ajouter des capabilities sans ajouter de tools)¶

• Probleme : Claude ne connaissait pas ses propres features (MCP, slash commands, etc.)
• Option A : system prompt → context rot, interfere avec le coding
• Option B : lien vers les docs → Claude charge trop de resultats
• Option C : Subagent specialise qui cherche dans les docs et retourne juste la reponse

Principe : "We were able to add things to Claude's action space without adding a tool."

Analyse critique approfondie¶

Interet reel¶

C'est le meilleur article first-party sur le design de tools pour agents. Les 3 raisons :

1. Honnetete sur les echecs : chaque solution finale est precedee de 2-3 tentatives ratees. Ca documente le processus de design, pas juste le resultat. Rare dans la communication officielle d'un lab.

2. Principe "see like an agent" : designer des tools en se mettant a la place du modele est evident a posteriori, mais presque personne ne le formule. La metaphore du probleme de maths (papier vs calculette vs ordinateur) est limpide : l'outil doit correspondre aux capacites du modele, pas aux attentes humaines.

3. Progressive disclosure : la formalisation du pattern "fichiers qui referencent des fichiers" comme mecanisme d'ajout de capabilities sans ajouter de tools est directement applicable. C'est plus elegant qu'un tool par use case et plus robuste qu'un system prompt geant.

Limites¶

• L'article est descriptif, pas prescriptif. "It's an art, not a science" est honnete mais ne donne pas de framework actionnable
• Les exemples sont specifiques a Claude Code (IDE/terminal). Le transfert vers d'autres agents (orchestrateur, reviewer, deployer) n'est pas couvert
• Pas de metriques. "Claude seemed to like calling this tool" est une observation, pas une mesure

Impact pour /gov (workflow de gouvernance)¶

AskUserQuestion → gov_ask_po¶

Le parcours AskUserQuestion (3 tentatives) resonne directement avec l'evolution de gov_ask_po dans ProbatioVault :

ProbatioVault est arrive a la meme conclusion (tool/fonction dediee avec types confirm/choice/text) par un chemin different (besoin LOTR). La convergence valide l'approche.

Action possible : s'inspirer du parametrage AskUserQuestion (options multiples + default) pour enrichir gov_ask_po choice avec des options pre-formatees au lieu d'une saisie libre. Reduirait les ambiguites dans les reponses PO.

TodoWrite → Task Tool : impact One Ring¶

C'est la lecon la plus impactante pour le One Ring. Le passage TodoWrite → Task Tool adresse exactement le probleme de coordination inter-Ringbearers :

Situation actuelle du One Ring : - Chaque Ringbearer a sa propre progression (step 0-10), pas de visibilite croisee - Le Lord poll l'etat de chaque Ringbearer via broker (lord_rb_status_update) - Si un Ringbearer bloque sur une dependance inter-story (ex: PD-285 attend le merge de PD-286), le Lord doit detecter le blocage et orchestrer manuellement

Ce que le Task Tool apporte comme inspiration : - Des taches avec dependances explicites entre Ringbearers : "PD-285 task 3 depends on PD-286 task 7 (merge)" - Du partage de statut inter-agents sans passer par le Lord pour chaque update - De la modification dynamique : un Ringbearer peut ajouter/supprimer des taches selon ce qu'il decouvre pendant l'implementation

Implementation possible : ajouter dans lord-state.json un champ dependencies par Ringbearer, et un mecanisme ou le Lord verifie automatiquement les dependances avant de debloquer un step. Pas besoin d'un "Task Tool" formel — un champ JSON + une verification dans la boucle de supervision suffit.

Effort : 1-2j. Prerequis : [L7] Tests E2E LOTR (pour valider le mecanisme de dependances).

Progressive Disclosure → Skills /gov¶

Le pattern "fichiers qui referencent des fichiers" est exactement l'architecture des skills ProbatioVault :

/gov → lit gov.md → reference gov-step-0.md → reference gov-learnings-inject.md
                  → reference gov-gate.md → reference CONSTITUTIONAL.md
                  → reference gov-impl.md → reference assemble-prompt.sh

C'est de la progressive disclosure native. Claude ne charge gov-gate.md que quand il atteint une gate, pas au demarrage. Le cout en tokens est proportionnel a la profondeur atteinte dans le workflow, pas a la taille totale du systeme.

Confirmation : l'article valide que c'est la bonne architecture. Ne pas fusionner les skills en un mega-fichier "pour simplifier" — la profondeur recursive EST le mecanisme d'efficacite.

Amelioration possible : formaliser les cross-references entre skills avec un format standard (ex: → Voir skill /gov-gate en fin de section) pour que Claude sache qu'il peut aller chercher plus de contexte sans qu'on le force. C'est du progressive disclosure explicite vs implicite.

Guide Agent → Palantir / Scribe¶

Le pattern "subagent specialise qui cherche dans les docs" est deja implemente dans le One Ring sous deux formes :

• Palantir : session Claude Code dediee a la veille — l'equivalent du Guide Agent mais pour la veille tech
• Scribe : commande scribe spec PD-XXX qui envoie un artefact en PJ Signal — l'equivalent du Guide Agent mais pour les artefacts

Ce qui manque : un equivalent du Guide Agent pour le workflow lui-meme. Quand un Ringbearer ne sait pas quelle etape lancer ou quel skill invoquer, il n'a pas de subagent "gov-guide" a interroger. Aujourd'hui il lit CLAUDE.md + le skill /gov-help. Un subagent dedie serait plus efficace sur les cas limites (ex: "est-ce que je dois relancer la gate ou passer a l'etape suivante ?").

Pas prioritaire : le systeme fonctionne sans. Mais si les Ringbearers montrent des patterns de confusion recurrents dans les audit logs, un "Gov Guide Agent" serait la bonne reponse.

Resume des actions possibles¶