Claude Code : subagents pour isoler le contexte et déléguer les tâches longues

Vous déclenchez une exploration large (« relis tout app/ et dis-moi où ajouter l'endpoint ») et d'un coup, la session principale est encombrée de fichiers lus, de résumés intermédiaires, d'hypothèses abandonnées. Le contexte de travail est pollué avant même que vous ayez écrit la première ligne. Les subagents Claude Code répondent à ce problème : vous déléguez la tâche à un agent isolé qui ne remonte que son rapport final. La session principale garde sa lisibilité, et vous pouvez spécialiser chaque subagent (explorateur, relecteur, auditeur) avec ses propres outils et son propre prompt système.

Ce que vous allez apprendre

• Créer un subagent projet dans .claude/agents/<nom>.md
• Scoper finement les outils disponibles pour le subagent
• Choisir entre invocation automatique (via description) et invocation manuelle
• Distinguer subagent (contexte isolé, rapport final) et skill (procédure dans la session courante)
• Choisir entre exécution au premier plan et en arrière-plan
• Donner une mémoire persistante à un subagent, et connaître ses trois portées
• Reprendre un subagent au lieu d'en relancer un neuf
• Savoir quand regarder du côté de l'Agent SDK plutôt que des subagents natifs

Dans quel contexte utiliser cette fonctionnalité ?

Le point commun de ces quatre situations est le besoin d'isoler un contexte : soit parce que la sous-tâche va lire beaucoup et polluerait la session, soit parce que vous voulez la rejouer à l'identique, soit parce que vous voulez restreindre ce qu'elle a le droit de faire. Si aucun de ces besoins ne se présente, un subagent est une complication inutile, un simple prompt suffit.

• Tâche exploratoire coûteuse en lecture (plusieurs dizaines de fichiers) dont vous voulez juste la conclusion
• Tâche répétable avec un prompt système stable (ex : revue de diff, audit de sécurité léger)
• Besoin de paralléliser plusieurs explorations indépendantes sans mélanger leurs contextes
• Besoin de restreindre les outils d'une sous-tâche (ex : un agent qui ne peut que lire, jamais écrire)

Prérequis

• Claude Code CLI opérationnel, lab-claude en place
• Skills déjà testés (voir skills Claude Code)
• settings.json projet avec permissions de base (voir settings.json avancé)
• À l'aise avec les modes de permission (voir mode plan, diff et validations)

Subagent vs skill : la différence-clé

Critère	Skill	Subagent
Contexte	Poursuit la session courante	Contexte isolé, ne revient qu'un rapport
Durée	Court, quelques étapes	Peut être long (exploration large)
Outils	allowed-tools scopés	tools scopés, prompt système dédié
Bon pour	Procédure répétée (valider, préparer PR)	Exploration, revue, audit

Glissez pour voir

Règle simple : si vous voulez les étapes visibles dans la session, c'est un skill. Si vous voulez juste la conclusion, c'est un subagent.

Structure d'un subagent

Un subagent est un fichier Markdown à plat dans .claude/agents/<nom>.md, avec frontmatter YAML et un corps qui sert de prompt système pour l'agent.

lab-claude/
├── .claude/
│   └── agents/
│       ├── explorer.md
│       └── reviewer.md
└── ...

Frontmatter minimal :

---
name: explorer
description: Explore le code en lecture seule et résume la structure, les points d'entrée et les zones à risque. À utiliser quand l'utilisateur demande une vue d'ensemble d'un module ou d'un dossier.
tools: Read, Glob, Grep
model: inherit
---

Tu es un agent d'exploration en lecture seule sur un projet Python FastAPI.

Ta sortie doit tenir en 3 sections courtes :
- Structure observée (3 à 5 points)
- Points d'entrée et dépendances clés
- Zones à risque ou à clarifier

Ne modifie aucun fichier. Ne lance aucune commande shell.

Les champs de frontmatter utiles :

Champ	Effet
name	Identifiant interne du subagent
description	Guide Claude pour décider quand déléguer automatiquement, rédigez-la comme une consigne d'orchestrateur
tools	Liste des outils autorisés. Omis = hérite de la session (à éviter). Explicite = garantit l'isolation
model	inherit (recommandé) ou un alias précis (sonnet, haiku, opus)

Glissez pour voir

Une description précise vaut mieux qu'un long prompt

Claude déclenche le subagent principalement en fonction de sa description. Formulez-la comme une règle d'aiguillage (« À utiliser quand… »), pas comme un résumé du prompt système. Une description vague = subagent jamais invoqué automatiquement.

Application sur lab-claude

Objectif : deux subagents utiles, explorer pour les vues d'ensemble en lecture seule, reviewer pour relire un diff avant commit.

Subagent 1 : explorer

Ce premier subagent applique la règle du moindre privilège de la façon la plus stricte : trois outils de lecture seule (Read, Glob, Grep), aucun outil d'écriture, aucun accès au shell. Suivez les étapes dans l'ordre, la dernière est la plus instructive, vous y comparez ce qui remonte dans la session (une synthèse compacte) avec ce qui serait remonté sans délégation (des dizaines de fichiers lus).

1. Créez le dossier .claude/agents/

   cd ~/Projets/lab-claude
   mkdir -p .claude/agents

2. Écrivez .claude/agents/explorer.md

   ---
   name: explorer
   description: Explore un dossier ou un module en lecture seule et produit une synthèse courte. À utiliser quand l'utilisateur demande une vue d'ensemble, une carte du code, ou avant de proposer un plan de modification.
   tools: Read, Glob, Grep
   model: inherit
   ---
   
   Tu es un agent d'exploration strictement en lecture seule pour un projet Python FastAPI géré avec uv, ruff et pytest.
   
   Méthode :
   1. Repère les points d'entrée et les dépendances clés
   2. Liste les fichiers significatifs avec leur rôle en une ligne
   3. Identifie les zones à risque (code dupliqué, absence de tests, TODO anciens)
   
   Format de sortie (trois sections, rien de plus) :
   - Structure observée (3 à 5 puces)
   - Points d'entrée et dépendances
   - Zones à risque ou à clarifier
   
   Ne modifie aucun fichier. Ne lance aucune commande shell. Si la demande exige d'écrire, réponds que ce n'est pas ton rôle et rends la main.

3. Invoquez-le depuis la session principale

   Je veux une vue d'ensemble de app/ avant de décider où ajouter un endpoint
   /items. Délègue à l'agent explorer.

4. Observez le retour : une synthèse compacte, pas un log d'exploration

Subagent 2 : reviewer

Objectif : relire un diff, lister les remarques, ne toucher à rien.

---
name: reviewer
description: Relit un diff git et liste les remarques (risques, incohérences, points de style). À utiliser avant commit ou avant push, jamais pour modifier du code.
tools: Bash(git diff *), Bash(git log *), Bash(git status), Read, Grep
model: inherit
---

Tu es un reviewer de code pour un projet Python FastAPI (uv, ruff, pytest).

Procédure :
1. Lance `git diff` pour voir les changements non commités
2. Au besoin, lis les fichiers touchés pour comprendre le contexte
3. Produit une liste de remarques classées :
   - Bloquant (bug probable, faille, test manquant critique)
   - À discuter (choix de design, nommage, périmètre)
   - Mineur (typo, style, commentaire obsolète)

Contraintes :
- N'écris dans aucun fichier
- Ne lance ni `ruff` ni `pytest` (c'est le rôle d'un autre geste)
- Si le diff est vide, dis-le et rends la main

Invocation typique :

Délègue au reviewer : relis mon diff courant avant que je commit.

Invocation : automatique vs manuelle

Deux chemins coexistent :

Chemin	Déclencheur	Quand c'est pertinent
Auto-délégation	Claude repère que la demande matche la description	Description précise, usage régulier
Manuelle	Vous écrivez « délègue à l'agent X » dans le prompt	Tâche ambiguë, ou vous voulez garantir l'isolation du contexte

Glissez pour voir

Au début, invoquez manuellement : c'est plus lisible et vous constatez l'effet de l'isolation. Une fois les description bien rodées, laissez Claude aiguiller.

Scoper les outils : la règle du moins privilégié

Un subagent doit avoir le minimum d'outils pour faire son job. Quelques patrons utiles :

Intention du subagent	tools typique
Lecture seule	Read, Glob, Grep
Revue de diff	Bash(git diff *), Bash(git log *), Bash(git status), Read, Grep
Audit de secrets dans le dépôt	Read, Glob, Grep (pas de Bash, pas d'Edit)
Génération de documentation	Read, Glob, Grep, Write(docs/**)

Glissez pour voir

Règle : si vous hésitez, n'ajoutez pas l'outil. Un subagent trop puissant perd son intérêt d'isolation.

Premier plan ou arrière-plan : ce que le choix change

Un subagent ne bloque pas forcément votre session. C'est la bascule qui transforme la délégation en travail parallèle, et elle a des conséquences qu'il faut connaître avant de s'en servir.

	Premier plan	Arrière-plan
Votre session	bloquée jusqu'au résultat	vous continuez à travailler
Demandes de permission	vous arrivent directement	remontent dans la session principale, en nommant le subagent qui demande
Jeu d'outils	complet	plus restreint, sauf pour un fork de conversation ou un subagent repris

Glissez pour voir

La ligne du bas est la moins connue et la plus piégeuse. Un subagent lancé en arrière-plan dispose d'un jeu d'outils intégré plus petit qu'au premier plan. Un agent qui fonctionne parfaitement en bloquant peut donc échouer une fois passé en arrière-plan, non pas à cause de vos permissions, mais parce qu'un outil n'est tout simplement pas là.

Claude Code choisit selon le premier cas applicable : un coéquipier d'équipe d'agents impose le premier plan ; la variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 aussi ; sinon, en session interactive, l'arrière-plan est le défaut. Le champ background: true dans le frontmatter force le comportement pour un subagent donné.

Quand une demande de permission remonte d'un subagent d'arrière-plan, Esc refuse ce seul appel d'outil sans arrêter le subagent, qui poursuit son travail. C'est une nuance utile : vous pouvez recadrer sans tout perdre.

Un subagent en arrière-plan échappe à `/rewind`

Les modifications faites par un subagent ne sont généralement pas restaurées par le rembobinage de votre session. Il faut passer par git.

La seule exception est une skill forkée exécutée au premier plan : elle modifie l'arbre de travail pendant votre propre tour, donc /rewind la rattrape. Une skill forkée en arrière-plan, qui est son comportement par défaut, non.

Conséquence pratique, et elle vaut règle : committez avant de lancer une délégation en arrière-plan. Le détail des angles morts du rembobinage est traité dans sessions, contexte et checkpoints.

Donner une mémoire persistante à un subagent

Un subagent peut accumuler des connaissances d'une conversation à l'autre. Le champ memory lui attribue un répertoire qui survit à la session, ce qui change la nature de l'outil : un relecteur de code cesse de redécouvrir vos conventions à chaque fois.

---
name: code-reviewer
description: Relit le code et signale les écarts aux conventions du projet
memory: project
---

Tu relis du code. Au fil des revues, consigne dans ta mémoire les conventions,
les motifs récurrents et les défauts que tu retrouves d'une fois sur l'autre.

Trois portées existent, et le choix se fait sur une question simple : qui doit voir cette mémoire ?

Portée	Emplacement	Ce qu'elle sert
user	~/.claude/agent-memory/<nom>/	ce que le subagent apprend tous projets confondus
project	.claude/agent-memory/<nom>/	la connaissance du projet, partageable par git
local	.claude/agent-memory-local/<nom>/	la même chose, mais hors du dépôt

Glissez pour voir

Quand la mémoire est active, le prompt système du subagent reçoit les instructions de lecture et d'écriture, ainsi que les 200 premières lignes ou 25 Ko du fichier MEMORY.md de ce répertoire, avec la consigne de le curer au-delà.

La mémoire dépend de la mémoire automatique

Le champ memory fait partie de la mémoire automatique. Si vous l'avez désactivée par autoMemoryEnabled: false ou par CLAUDE_CODE_DISABLE_AUTO_MEMORY, le champ n'a aucun effet, sans message d'erreur. C'est un cas classique de configuration qui semble ignorée.

Reprendre un subagent plutôt qu'en relancer un

Chaque invocation crée une instance neuve, mais rien n'oblige à repartir de zéro. Un subagent repris conserve tout son historique : appels d'outils, résultats, raisonnement. Il reprend exactement où il s'était arrêté, et peut continuer de lire le cache de prompt que la première exécution avait chauffé.

C'est particulièrement utile quand un subagent s'est arrêté sur sa limite de tours : Claude Code marque alors sa sortie comme partielle et signale qu'elle peut être poursuivie.

Utilise le subagent code-reviewer sur le module d'authentification.
[le subagent rend son rapport]

Reprends cette revue et analyse maintenant la logique d'autorisation.

Deux agents font exception : les agents intégrés Explore et Plan sont à usage unique et ne renvoient pas d'identifiant. Ils ne se reprennent pas, il faut en relancer un.

Imbriquer les subagents pour paralléliser

Un subagent peut lui-même déléguer, jusqu'à trois niveaux sous la conversation principale. C'est ce qui permet à une tâche déléguée de se découper en sous-tâches parallèles sans que rien de tout cela ne remonte chez vous : seul le résumé du subagent de premier niveau vous revient.

Au niveau limite, Claude Code retire l'outil Agent du subagent, qui fait donc lui-même le travail délégué et rend un unique résumé. La profondeur se règle :

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

La valeur 1 désactive complètement l'imbrication. C'est le réglage à poser si vous voulez garder une topologie simple et prévisible, par exemple sur un dépôt partagé où plusieurs personnes déclenchent les mêmes agents.

Subagent vs skill vs hook : la bonne case

Claude Code offre plusieurs briques d'extension qui se ressemblent au premier abord, et choisir la mauvaise mène à des configurations bancales. Ce tableau associe chaque besoin à la brique adaptée. La ligne à retenir oppose skill et subagent : un skill exécute une procédure visible dans la session courante, un subagent délègue à un contexte isolé qui ne renvoie qu'un rapport. Les autres lignes (hook, settings.json, MCP) répondent à des besoins tout autres, respectivement réagir à un événement, autoriser un outil, ou brancher un service externe.

Besoin	Brique
Exécuter une procédure invocable par /nom dans la session	Skill
Déléguer une exploration isolée et récupérer un rapport	Subagent
Exécuter une commande shell autour d'un événement	Hook
Autoriser ou bloquer un outil	settings.json
Étendre Claude vers un outil externe	Serveur MCP

Glissez pour voir

Agent SDK : quand y aller

Les subagents natifs couvrent la délégation à l'intérieur d'une session Claude Code. Quand vous voulez construire une application autonome, un agent qui tourne dans votre infra, appelé par une API, piloté par un cron, vous sortez de la CLI et vous utilisez l'Agent SDK d'Anthropic :

• @anthropic-ai/claude-agent-sdk (Node.js / TypeScript)
• claude-agent-sdk (Python)

Le SDK expose les mêmes primitives (outils, permissions, hiérarchie d'agents) mais dans votre propre programme. Bascule typique : vous prototypez un subagent dans .claude/agents/, puis vous le réimplémentez via le SDK quand il doit tourner en dehors d'une session interactive.

Pas de pont automatique entre les deux

Un .claude/agents/<nom>.md n'est pas directement consommable par le SDK. Les concepts sont alignés, mais le code doit être réécrit dans l'API du SDK. Gardez vos subagents natifs comme terrain de prototypage, pas comme source unique.

Erreurs fréquentes

La majorité de ces erreurs remontent à deux causes récurrentes : une description trop vague, qui empêche l'auto-délégation, et un tools mal cadré, qui laisse le subagent déborder de son rôle. La première ligne est de loin la plus fréquente au démarrage : tant que la description n'est pas formulée en « À utiliser quand… » avec un déclencheur précis, Claude ne saura jamais quand basculer sur le subagent tout seul.

Symptôme	Cause probable	Correction
Le subagent n'est jamais invoqué automatiquement	description vague ou trop générique	Reformuler en « À utiliser quand… » avec déclencheur précis
Le subagent modifie des fichiers que vous ne vouliez pas toucher	tools trop large ou omis	Lister explicitement les outils en retirant Edit/Write
La session principale reste polluée	Invocation manuelle oubliée, Claude a fait l'exploration en direct	Redemander explicitement « délègue à l'agent X »
Le rapport du subagent est trop long	Prompt système sans format imposé	Imposer une structure de sortie (sections, nombre max de points)
Le subagent redemande les mêmes infos à chaque appel	Prompt système trop vague, trop de libre arbitre	Resserrer la procédure en étapes numérotées

Glissez pour voir

Checklist de fin de guide

Reprenez cette liste avant de considérer un subagent comme opérationnel. Chaque point correspond à un piège traité plus haut : une description actionnable pour l'auto-délégation, un tools minimal pour l'isolation, un format de sortie imposé pour un rapport lisible. Si une case reste vide, le subagent fonctionnera peut-être, mais pas de façon fiable.

• J'ai au moins un subagent dans .claude/agents/
• Sa description commence par « À utiliser quand… » et est actionnable
• Son tools est explicite et au minimum nécessaire
• Son prompt système impose un format de sortie court
• J'ai testé une invocation manuelle et vérifié que le contexte principal reste propre
• Je sais quand utiliser un skill plutôt qu'un subagent

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Un subagent = contexte isolé + rapport final, un skill = procédure dans la session courante
• La description est le vrai levier d'auto-délégation, pas le prompt système
• Scoper tools au minimum garantit que le subagent reste spécialisé
• Invocation manuelle au début, automatique une fois les description rodées
• Pour un agent qui tourne hors session interactive, regardez l'Agent SDK

Pour aller plus loin

• Choisir le modèle : Opus, Sonnet, Haiku : Le choix du modèle par agent, levier direct sur le coût d'une délégation massive.
• Claude Code dans VS Code : Le suivi d'un agent délégué depuis l'éditeur, diff et historique de session sous les yeux.
• Dépannage avancé : permissions, config, diff : La marche à suivre quand un subagent rend un résultat vide ou se heurte à une permission.

×

📖 Voir la documentation →