Concevoir des sous-agents efficaces

Un sous-agent mal conçu se déclenche au mauvais moment, s’égare, rapporte trop ou pas assez, ou touche à ce qu’il ne devait pas toucher.

Le cours officiel retient quelques motifs qui rendent un sous-agent fiable : une mission unique, une description qui le désigne sans ambiguïté, un **format de sortie structuré**, le **signalement des obstacles** et un **accès limité aux outils**. Cette leçon les détaille, avec les champs de configuration qui les mettent en œuvre.

Une mission, une description

La première règle de la documentation : chaque sous-agent doit exceller dans une tâche précise. Un « assistant qualité » qui relit, teste, documente et optimise ne fait rien de bien ; un relecteur, un lanceur de tests et un rédacteur de documentation séparés font chacun leur travail.

La description est ce que Claude lit pour choisir à qui déléguer. Écrivez-la pour qu’elle désigne un seul sous-agent : ce qu’il fait, et quand l’utiliser. Comparez « Reviews code » et la description officielle du relecteur : « Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. » Gardez-la courte, car toutes les descriptions sont chargées en permanence : au-delà de 15 000 jetons cumulés pour vos sous-agents, Claude Code affiche un avertissement au démarrage. Le détail va dans le corps du fichier, qui ne se charge que lorsque le sous-agent tourne.

Un format de sortie structuré

Seul le rapport final du sous-agent revient dans la conversation. C’est donc la pièce qui compte, et il faut la spécifier. Les exemples officiels le font tous. Le relecteur de code termine ses instructions ainsi :

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Le débogueur, lui, doit fournir pour chaque problème : l’explication de la cause, les éléments qui étayent le diagnostic, la correction précise, la façon de la tester et des recommandations pour éviter qu’il se reproduise. Un format fixe a trois avantages : Claude sait où trouver l’information dans le rapport, vous comparez facilement deux exécutions, et vous évitez les rapports fleuves. Les bonnes pratiques officielles le rappellent : demandez des résumés courts, pour que vingt résultats ne remplissent pas votre contexte malgré tout.

Signaler les obstacles

Un sous-agent ne peut pas vous poser de question : l’outil qui sert à interroger l’utilisateur (AskUserQuestion) fait partie de ceux que Claude Code retire à tous les sous-agents. Face à un fichier introuvable, une commande qui échoue ou une consigne ambiguë, il n’a que deux options : deviner, ou le dire dans son rapport. Le cours officiel recommande la seconde. Prévoyez-le dans ses instructions. Par exemple :

If you cannot complete the task — a file is missing, a command fails,
or the request is ambiguous — stop and report:
- what you were trying to do
- what blocked you, with the exact error
- what you already tried
- what you need to continue
Never guess to fill a gap.

Cette formulation est un exemple, pas un texte officiel : adaptez-la. Ce qui compte, c’est qu’un échec revienne sous une forme exploitable. Claude peut alors corriger la consigne, vous demander l’information manquante, ou reprendre le sous-agent : un sous-agent reprend avec tout son historique, ses appels d’outils et ses résultats, à condition que ce ne soit pas Explore ou Plan, qui sont à usage unique.

Finir à temps

Le champ maxTurns fixe le nombre maximal de tours d’action. À la limite, le sous-agent s’arrête, Claude Code renvoie sa sortie marquée comme partielle, et Claude peut le reprendre pour continuer. C’est un garde-fou contre le sous-agent qui tourne en rond. Le champ effort règle la profondeur de réflexion du sous-agent, et model son modèle : pour une tâche simple, comme lister les fichiers qui importent un module ou vérifier les liens d’une documentation, model: haiku coûte beaucoup moins cher par requête.

Limiter l’accès aux outils

Donnez à chaque sous-agent les seuls outils dont il a besoin. Deux champs s’en chargent :

• tools, une liste blanche : tools: Read, Grep, Glob donne un relecteur qui ne peut rien modifier ;
• disallowedTools, une liste noire : disallowedTools: Write, Edit garde tout le reste, Bash et les outils MCP compris.

La différence avec une consigne dans le prompt est fondamentale : cette limite est appliquée par Claude Code, pas demandée au modèle. Un relecteur sans Edit ne peut pas modifier un fichier, quoi qu’il décide. Pour aller plus finement, un hook PreToolUse dans l’en-tête du sous-agent peut autoriser un outil sous condition. L’exemple officiel db-reader n’a que l’outil Bash, et un script vérifie chaque commande avant son exécution pour bloquer, par le code de sortie 2, tout ce qui n’est pas une requête en lecture seule.

D’autres réglages complètent ce cloisonnement :

• permissionMode fixe le mode de permission du sous-agent ; mais si la conversation principale est en mode Auto, acceptEdits ou bypassPermissions, le sous-agent prend ce mode-là et la valeur indiquée est ignorée ;
• mcpServers donne au sous-agent des serveurs MCP que la conversation principale n’a pas, connectés à son démarrage et déconnectés à la fin ;
• retirer l’outil Agent de la liste l’empêche de lancer ses propres sous-agents.

Donner le bon contexte

• skills précharge le contenu complet de skills, par exemple vos conventions d’API, pour que le sous-agent n’ait pas à les découvrir.
• memory lui donne une mémoire persistante d’une conversation à l’autre (project est la portée recommandée, partageable par git). Demandez-lui de consulter sa mémoire avant le travail et d’y noter ce qu’il a appris après.
• omitClaudeMd: true le fait démarrer sans vos CLAUDE.md, pour un sous-agent qui trouve tout ce qu’il lui faut dans la consigne. Inversement, si une règle de CLAUDE.md doit absolument l’atteindre, comme « ignore le dossier vendor/ », répétez-la dans la consigne de délégation.
• isolation: worktree le fait travailler dans une copie temporaire du dépôt ; elle est supprimée automatiquement s’il n’a rien modifié.

Un exemple complet

Voici le relecteur que proposent les bonnes pratiques officielles, dans .claude/agents/reviewer.md : une mission, une description qui dit quand l’utiliser, des outils en lecture seule, un format de sortie et une consigne qui borne le rapport.

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

À vous de jouer

Rendre votre sous-agent fiable. Reprenez le sous-agent test-runner de la leçon précédente. Ajoutez-lui un format de sortie fixe (nombre de tests lancés, liste des échecs avec fichier et message), une consigne de signalement des obstacles et maxTurns: 15. Lancez-le une fois sur un projet où la commande de test est mal configurée, et vérifiez que le rapport dit clairement ce qui a bloqué.

Sources officielles : Designing effective subagents (Claude Academy) · Create custom subagents (documentation Claude Code : champs, outils, hooks, mémoire) · Best practices

Points clés à retenir

• Une mission par sous-agent, et une description courte qui le désigne sans ambiguïté
• Spécifiez le format du rapport final : c’est la seule chose qui revient
• Un sous-agent ne peut pas vous interroger : demandez-lui de signaler ce qui le bloque au lieu de deviner
• maxTurns, effort et model bornent sa durée et son coût
• tools et disallowedTools limitent ses outils, et cette limite est appliquée par Claude Code, pas laissée au modèle