Sous-agents Claude Code : garder le chat principal propre

Un sous-agent fait un type de travail dans sa propre fenêtre et renvoie un résumé. Utilisez-en un quand une recherche, une exécution de test, ou une revue fichier par fichier ensevelirait la conversation dont vous avez encore besoin. Ce lab écrit cinq agents que vous pouvez valider. Les commandes de session et les flags se trouvent dans la feuille de triche Claude Code.

Qu’est-ce qu’un sous-agent

Chaque sous-agent personnalisé est un fichier Markdown. Le front matter définit le nom auquel Claude délègue, les outils qu’il peut appeler, et le modèle sur lequel il s’exécute. Le corps remplace le prompt système normal de Claude Code pour cet agent. Il reçoit toujours les détails d’environnement de base comme le répertoire de travail.

La session parent voit une courte ligne d’outils, le nom de l’agent et le résultat final. Les lectures intermédiaires restent dans la transcription du sous-agent sous les fichiers de session du projet dans ~/.claude. Cette séparation est la raison de créer un agent que vous sinon reprojeteriez chaque jour.

Les agents intégrés existent déjà. Explore parcourt l’arborescence sans éditer. Plan recueille le contexte alors que la session principale est en mode plan. Vous n’avez pas besoin de les redéfinir. Un agent de projet ou utilisateur dont le name est Explore remplace l’agent intégré.

Les sous-agents sont une forme de travail agentic : un modèle, une liste d’outils et une condition d’arrêt. Ils ne sont pas des serveurs MCP. MCP expose des outils externes. Un sous-agent est une autre session Claude avec un prompt plus étroit.

Format de fichier

Seuls name et description sont obligatoires. Les clés non reconnues sont ignorées. name ne peut pas dépasser 256 caractères et ne peut pas contenir :, car les noms avec deux-points sont réservés aux plugins. Le nom du fichier n’a pas besoin de correspondre à name, mais le faire rend le dossier lisible.

Autres champs supportés que vous utiliserez réellement :

isolation: worktree branche à partir de la branche par défaut du repo, pas à partir de votre HEAD actuel. Le worktree est supprimé quand l’agent ne fait aucun changement. Laissez-le off quand l’agent doit voir la branche sur laquelle vous avez basculé.

Un cd à l’intérieur de l’agent ne persiste pas entre les appels de shell, et ne change pas le répertoire de la session principale.

Où le fichier vit

Les agents de projet sont découverts en remontant du répertoire de travail à la racine du repo. Si deux de ces dossiers définissent le même name, celui plus proche du répertoire de travail gagne. Claude Code balaye aussi les sous-dossiers, donc .claude/agents/review/security.md est une disposition valide. Validez les agents de projet. Gardez les expériences personnelles dans ~/.claude/agents/.

Claude Code regarde ~/.claude/agents/ et le .claude/agents/ du projet. Les éditions s’affichent en quelques secondes. Trois cas nécessitent toujours un redémarrage : le répertoire agents a été créé après le démarrage de la session, le fichier se trouve dans un répertoire que vous avez ajouté avec --add-dir, ou la session a démarré avec --disable-slash-commands.

/agents dans les versions actuelles affiche un rappel d’éditer ces fichiers. Sur Claude Code v2.1.197 et antérieur, il ouvrait une UI de gestionnaire. Les agents d’arrière-plan déjà en cours d’exécution sont listés avec /tasks, que la feuille de triche inclut.

Vérifiez le front matter avec claude plugin validate .claude/agents. Cette vérification nécessite Claude Code v2.1.233 ou ultérieur. Elle signale les fichiers qui ne s’analysent pas. Elle ne se plaint pas d’un name manquant si le YAML lui-même s’analyse.

Quand Claude délègue

Claude compare votre demande, la description de l’agent, et le contexte actuel. Une description qui dit quand exécuter est plus utile qu’une description qui dit seulement ce que l’agent est. La doc met en évidence la phrase « utiliser proactivement » comme moyen d’encourager la délégation. Gardez les descriptions courtes. Si les descriptions combinées de vos agents personnalisés dépassent 15 000 tokens, Claude Code avertit au démarrage et charge toujours chaque agent. Déplacez les longues instructions dans le corps, qui se charge seulement quand cet agent s’exécute.

La délégation est un choix. Une description vague perd contre Explore ou la session principale faisant le travail elle-même.

L’invocation explicite a trois niveaux :

La syntaxe de mention qui montre les agents dans la liste de suggestions ressemble à ceci :

@"code-reviewer (agent)" examine les changements d'authentification

Vous pouvez aussi taper @agent-code-reviewer sans le sélecteur. Pendant que vous taper cette forme, le menu affiche les fichiers. La mention se résout toujours quand vous l’envoyez. Votre phrase va au parent. Le parent écrit le prompt de tâche que le sous-agent reçoit réellement.

Un agent de plugin apparaît en tant que nom scopé, par exemple @agent-my-plugin:code-reviewer. Si le fichier de plugin se trouve dans un sous-dossier, le scope inclut ce dossier : my-plugin:review:security.

--agent persiste quand vous reprenez la session. Si le fichier d’agent a disparu au moment de la reprise, la session continue avec les outils par défaut et affiche un avertissement.

Les agents uniques peuvent être passés en JSON. Cette forme est pour un lancement unique, pas pour un fichier que vous validez :

claude --agents '{"reviewer":{"description":"Revises code","prompt":"You are a code reviewer"}}'

En mode print sur v2.1.281 ou ultérieur, --agents peut pointer sur un fichier JSON. Une session interactive refuse un chemin de fichier là.

Cinq agents

Les noms d’outils ci-dessous sont ceux que la référence du sous-agent utilise : Read, Grep, Glob, Edit, Write, et Bash. Lister les outils est ce qui empêche un reviewer d’éditer. Un champ tools omis hérite de l’ensemble complet du sous-agent.

Réviseur de code

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revise les diffs locales pour les bugs de justesse et tests manquants. À utiliser proactivement après les changements de code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Vous êtes un réviseur de code pour ce repository.

Exécutez git status et git diff. Lisez seulement les fichiers que diff touche, plus les tests à côté.
Signalez les constatations comme bloquantes, should-fix, ou note.
Chaque constatation nécessite un chemin de fichier et le mode d'échec.
Ignorez les nits de style qu'un formateur corrigerait.
N'éditez pas les fichiers et ne validez pas.

Bash est sur cet agent pour qu’il puisse exécuter git diff. Il peut aussi exécuter d’autres commandes shell, donc le prompt doit interdire les édits et commits. Si vous avez besoin d’un arrêt dur, supprimez Bash et acceptez que le parent doive coller la diff dans le prompt de délégation.

Auteur de tests

.claude/agents/test-writer.md

---
name: test-writer
description: Ajoute ou met à jour les tests pour le code qui vient de changer. À utiliser quand l'utilisateur demande des tests ou qu'un changement n'a pas de couverture.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

Vous écrivez des tests qui correspondent au runner et à la disposition existante de ce repo.

Lisez le code modifié et un fichier de test à proximité avant d'ajouter quoi que ce soit.
Couvrez le comportement qui a régressé ou que le changement prétend ajouter.
Ne changez pas le code de production sauf pour exposer un hook de test que le projet utilise déjà.
Exécutez la commande de test la plus étroite qui exécute le nouveau test.
Si elle échoue, corrigez le test. Si le code de production est faux, arrêtez et signalez cela à la place de le réécrire.

Auditeur de sécurité

.claude/agents/security-auditor.md

---
name: security-auditor
description: Passage en lecture seule sur l'auth, les secrets et le shell ou SQL risqué. À utiliser proactivement avant qu'un changement sensible à la sécurité ne se fusionne.
tools: Read, Grep, Glob
model: sonnet
---

Vous auditez ce repository pour les problèmes de sécurité qu'un réviseur peut vérifier à partir du code.

Cherchez les secrets dans l'arborescence, les vérifications d'auth qui font confiance au client, l'injection de commande, et les requêtes construites avec concaténation de chaînes.
Citez le fichier et le motif. Dites comment cela pourrait être frappé.
N'éditez pas les fichiers. N'exécutez pas d'exploits. Ne demandez pas d'identifiants.
Si vous êtes incertain, étiquetez l'élément comme needs-human et citez la ligne.

Pas de Bash et pas d’outils d’écriture. L’agent ne peut pas « simplement curl la production » pour vérifier une idée.

Auteur de documentation

.claude/agents/doc-writer.md

---
name: doc-writer
description: Met à jour README ou docs pour qu'ils correspondent au code. À utiliser quand le comportement a changé et que les docs n'étaient pas partie de l'édition.
tools: Read, Grep, Glob, Edit, Write
model: haiku
---

Vous mettez à jour la documentation pour qu'elle corresponde au code.

Lisez d'abord l'implémentation. Éditez la page de doc existante qui décrit déjà la fonctionnalité.
Décrivez le comportement qu'un appelant peut observer. N'inventez pas de flags ou chemins.
Si le code est ambigu, écrivez la question en haut de votre résumé et ignorez l'édition de doc.

model: haiku garde une passe de formulation sur le plus petit alias. Le parent peut rester sur Sonnet. Voir la section des coûts ci-dessous.

Debuggeur

.claude/agents/debugger.md

---
name: debugger
description: Trouve pourquoi un test ou une commande qui échoue échoue. À utiliser quand l'utilisateur colle une trace de pile ou dit qu'une vérification est rouge.
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
maxTurns: 12
---

Vous débuggez un échec.

Reproduisez-le avec la commande dans la tâche avant d'éditer.
Changez la plus petite surface qui explique l'échec.
Réexécutez cette commande. Si elle échoue toujours, signalez ce que vous avez essayé et arrêtez.
Ne nettoyez pas les fichiers non relatifs.

model: inherit suit le modèle de session. maxTurns: 12 arrête un debuggeur qui boucle. Le résultat revient marqué comme partiel, et vous pouvez demander à Claude de reprendre cet agent plutôt que d’en commencer un nouveau.

Pièges

L’agent ne voit pas votre chat. Un sous-agent non-fork démarre propre. Il n’obtient pas votre historique, les compétences que vous avez déjà exécutées, ou les fichiers que le parent a déjà ouverts. Il obtient son propre prompt système, le message de délégation, CLAUDE.md des niveaux que le parent a chargés (sauf si omitClaudeMd est défini), un snapshot de git status quand vous êtes dans un repo git, et toutes compétences nommées dans skills. Explore et Plan ignorent le chargement de CLAUDE.md et le snapshot git.

Mettez les faits que l’agent ne doit pas manquer dans la phrase que vous envoyez, ou dans son corps Markdown. « Utilise le debuggeur sur l’échec dont nous avons discuté » est une délégation faible. « Utilise le debuggeur sur npm test -- auth.test.ts. L’assertion est expected 401. » est une complète.

Un fork, que vous pouvez commencer avec /subtask, hérite de la conversation parent à la place. C’est l’outil quand reposer le contexte coûterait plus que le partager. Les forks sont une fonctionnalité différente des cinq fichiers ci-dessus.

Vous payez pour le second modèle. Les requêtes du sous-agent comptent comme les limites d’utilisation du même plan que la session principale. Les descriptions de chaque agent personnalisé sont aussi chargées dans le parent, jusqu’à l’avertissement de 15 000 tokens. Un critique haiku de doc est moins cher qu’un critique Opus pour une passe de formulation. Une fenêtre de contexte du sous-agent est la fenêtre de son propre modèle, donc un modèle plus petit est une fenêtre plus petite aussi.

Il y a un cap de concurrence. Une fois que 20 sous-agents s’exécutent, un autre spawn depuis l’outil Agent échoue avec une erreur concurrent-limit jusqu’à ce qu’un termine. Ce cap nécessite Claude Code v2.1.217 ou ultérieur, et les sessions avec ultracode activé en sont exemptes. L’augmenter est CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Vous voulez rarement un cap plus haut sur un laptop.

Les worktrees ne sont pas votre branche. isolation: worktree démarre à partir de la branche par défaut. Un agent demandé de réviser le travail non-validé sur une branche de feature ne verra pas ce travail si vous activez l’isolation.

La reprise est explicite. Chaque délégation démarre une nouvelle instance. Quand l’agent termine, le parent reçoit un id d’agent et peut le reprendre, gardant la transcription de cet agent. Explore et Plan ne retournent pas d’id. Demandez au parent de continuer le code-reviewer, ou commencez un nouveau si le premier passage était suffisant.

Les hooks à l’intérieur de l’agent ne sont pas des hooks de session. Le front matter hooks s’exécute pendant que cet agent s’exécute. Un hook Stop écrit là se déclenche en tant que SubagentStop. Les hooks de projet dans settings.json s’exécutent aussi pour les outils que l’agent appelle, avec agent_id et agent_type sur l’entrée. Le guide des hooks affiche le fichier de paramètres. Les agents de plugin ignorent hooks, mcpServers, et permissionMode dans leur propre front matter.

Une checklist répétée qui devrait rester dans le chat principal est une commande slash, pas un agent. Un agent est pour le milieu bruyant d’une tâche.

FAQ

Qu’est-ce qu’un sous-agent Claude Code ?

Un sous-agent est un assistant distinct avec sa propre fenêtre de contexte, son propre prompt système, sa liste d’outils et son modèle. Claude délègue une tâche auxiliaire et ramène un résumé, de sorte que les dumps de recherche et les fichiers journaux restent hors de la conversation principale. Chaque appel de sous-agent est sa propre requête de modèle et compte comme les limites d’utilisation du chat principal.

Comment ajouter un sous-agent personnalisé ?

Créez un fichier Markdown dans .claude/agents/ pour un seul repo, ou dans ~/.claude/agents/ pour tous vos projets. Le front matter doit contenir name et description. tools et model sont facultatifs. Le corps Markdown est le prompt système. Si le répertoire agents n’existait pas au démarrage de la session, redémarrez Claude Code une fois pour que le nouveau dossier soit reconnu.

Comment forcer Claude à utiliser un sous-agent particulier ?

Tapez @ et choisissez l’agent dans la liste de suggestions, ou écrivez @agent-code-reviewer dans le prompt. Cette mention garantit que cet agent s’exécute pour la tâche. Le nommer dans une phrase, comme « utilise le sous-agent code-reviewer », demande à Claude de déléguer et laisse le choix ouvert. claude --agent code-reviewer rend cet agent la session entière.

Pourquoi mon sous-agent a-t-il ignoré la conversation ?

Un sous-agent normal démarre avec un contexte vierge. Il ne voit pas votre historique de chat, les compétences que vous avez déjà invoquées, ou les fichiers que la session principale a déjà lus. Claude écrit un message de délégation, et le sous-agent travaille à partir de cela plus son propre prompt et les fichiers CLAUDE.md qu’il est autorisé à charger. Un fork est l’exception : il hérite de la conversation parent.

Les sous-agents coûtent-ils extra ?

Ils envoient leurs propres requêtes sur le modèle que vous avez attribué, et ces requêtes comptent comme les limites du même plan ou utilisation API que la session principale. Un critique haiku dépense moins qu’un critique opus. Les champs de description de vos sous-agents personnalisés siègent aussi dans le contexte parent, et Claude Code avertit au démarrage quand ces descriptions dépassent ensemble 15 000 tokens.