Un subagent Claude Code est un assistant specialise a qui l'agent principal delegue une tache ciblee, qui tourne dans son propre context window separe avec son propre system prompt et son propre jeu de tools restreint. Au lieu que la session principale fasse tout et se remplisse d'output bruyant, elle passe un job (revise ce code, recherche cette question, execute ces tests) a un subagent qui travaille en isolation et ne renvoie qu'un resume propre. Ce guide explique ce que sont les subagents, quand ils valent le coup, quels subagents integres Claude Code fournit et exactement comment creer les votres avec la commande /agents ou un fichier Markdown dans .claude/agents.
Une partie de: Tutoriel Claude Code pour debutants
Ce qu'est vraiment un subagent
Chaque subagent tourne dans son propre context window avec son propre system prompt, un acces tools specifique et des permissions independantes. Quand Claude rencontre une tache qui correspond a la description d'un subagent, il delegue a ce subagent, qui travaille independamment et renvoie son resultat. Le mot cle est isolation: tout le travail intermediaire desordonne, la douzaine de fichiers qu'il a lus, les approches ratees, l'output brut des commandes, reste dans la fenetre du subagent et ne touche jamais la conversation principale. L'agent principal ne recoit que la conclusion.
- Context window separe: le subagent n'herite pas de toute votre conversation principale.
- System prompt propre: un briefing court et cible, taille sur son unique job.
- Tools et permissions restreints: seulement ce dont la tache a besoin, souvent en read-only.
- Renvoie un resume: le travail bruyant est absorbe, la session principale recoit le resultat propre.
Quand utiliser un subagent
Prenez un subagent quand une tache annexe inonderait votre conversation principale de resultats de recherche, de logs ou de contenus de fichiers auxquels vous ne reviendrez jamais. Le subagent fait ce travail dans son propre contexte et ne renvoie que la reponse, pour que votre fenetre principale reste nette et que vous evitiez la falaise de performance qui frappe quand un context window se remplit de bruit. Definissez un subagent dedie quand vous lancez sans cesse le meme genre de travailleur avec les memes instructions: un code reviewer, un test writer, un generateur de docs.
- Menager le contexte: gardez exploration et lecture de masse hors de votre conversation principale.
- Imposer des contraintes: limitez un subagent aux tools read-only, pour qu'un reviewer ne puisse pas editer.
- Specialiser le comportement: un system prompt cible le rend plus fiable sur son unique job.
- Piloter les couts: dirigez le travail etroit vers un modele plus rapide et moins cher comme Haiku.
Les subagents integres que vous avez deja
Claude Code fournit des subagents integres qu'il utilise automatiquement, donc vous profitez des subagents avant meme d'en creer un. Explore est un agent rapide, read-only, pour parcourir et comprendre une codebase, souvent sur Haiku pour rester economique. Plan est l'agent de recherche qui rassemble le contexte en mode plan avant de proposer un plan. General-purpose gere les taches complexes et multi-etapes qui demandent a la fois exploration et modifications. Vous pouvez bloquer un type integre via les permissions au besoin, mais la plupart du temps vous les laissez faire leur job.
- Explore: recherche et analyse de codebase rapides et read-only (souvent Haiku).
- Plan: agent de recherche read-only qui rassemble le contexte en mode plan.
- General-purpose: agent full-tool pour du travail complexe et multi-etapes.
Creer votre propre subagent
Les subagents sont des fichiers Markdown avec un frontmatter YAML. Le moyen le plus simple d'en creer un est la commande /agents, qui ouvre une interface guidee ou vous nommez le subagent, ecrivez sa description, choisissez ses tools et son modele, et pouvez laisser Claude rediger le system prompt pour vous. Les subagents de projet vivent dans .claude/agents/ (committez-les dans la version control pour que votre equipe les partage); les personnels vivent dans ~/.claude/agents/ et vous suivent d'un projet a l'autre. Dans le frontmatter, seuls name et description sont obligatoires; la description est ce que Claude lit pour decider quand deleguer, donc redigez-la clairement.
<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a senior code reviewer. When invoked, analyse the changed code and
return a concise, prioritised list of issues covering correctness, security
and readability. Do not edit files; only report. Cite the file and line for
each issue and suggest the smallest fix.Les fichiers crees directement sur le disque sont charges au demarrage de la session, donc relancez Claude Code (ou creez-le via /agents, qui prend effet immediatement) pour prendre en compte un nouveau fichier. Le champ model accepte sonnet, opus, haiku ou inherit; le champ tools herite par defaut de tous les tools si vous l'omettez.
Invoquer les subagents et travailler avec eux
La plupart du temps, vous n'invoquez pas un subagent a la main: Claude lit la description de chaque subagent et delegue automatiquement quand une tache correspond. Vous pouvez aussi le declencher explicitement, par exemple "utilise l'agent code-reviewer pour reviser ce diff". Un bon motif est d'ecrire la fonctionnalite avec votre agent principal puis de deleguer la review a un subagent reviewer read-only, qui inspecte le diff dans son propre contexte et renvoie une liste d'issues concise, apres quoi l'agent principal les corrige. Comme le raisonnement de review n'a jamais ete charge dans votre fenetre principale, la session reste propre.
Pas à pas
Ouvrir l'interface des subagents
Dans une session Claude Code, executez /agents pour ouvrir l'interface guidee de creation et de gestion des subagents.
Choisir un scope et creer
Choisissez Project (.claude/agents/, partage via version control) ou Personal (~/.claude/agents/, tous vos projets), puis creez un nouvel agent. Vous pouvez laisser Claude generer l'identifiant, la description et le system prompt.
Ecrire une description claire
La description est ce avec quoi Claude decide quand deleguer, donc dites exactement quand ce subagent doit etre utilise. name et description sont les seuls champs obligatoires.
Restreindre tools et modele
Limitez les tools a ce dont la tache a besoin (pour un reviewer: read-only), et choisissez un modele. Dirigez le travail etroit vers un modele moins cher comme Haiku pour piloter les couts.
Sauvegarder et essayer
Sauvegardez le subagent et testez-le en demandant a Claude de l'utiliser. Si vous avez cree le fichier directement sur le disque, relancez la session pour qu'il soit charge.