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)
Savoir quand regarder du côté de l’Agent SDK plutôt que des subagents natifs

Dans quel contexte utiliser cette fonctionnalité ?

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
Analogie	« Une checklist que je déroule »	« Un collègue qui me rend un rapport »

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`)

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`

Créez le dossier .claude/agents/
Fenêtre de terminal
```
cd ~/Projets/lab-claude
mkdir -p .claude/agents
```

É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.

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.

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

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/**)`

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

Subagent vs skill vs hook : la bonne case

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

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 CLIet 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.

Erreurs fréquentes

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

Checklist de fin de guide

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

À 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

Prochaines étapes

Mode headless et CI Lancer Claude Code en non-interactif, dans un script ou un job GitHub Actions

Skills Claude Code Revisiter le bon usage des skills face aux subagents

Briques Claude Code : quand utiliser quoi Replacer les subagents dans l'ensemble CLAUDE.md, rules, settings, hooks, skills, MCP