Subagents — Déléguer des tâches à des assistants spécialisés — Claude Code — Le guide pratique

Ce que tu vas apprendre

Créer un subagent en 2 minutes
Lui donner des outils limités pour réduire les risques
Le faire intervenir automatiquement ou sur demande
Comprendre quand un subagent est utile (et quand il ne l’est pas)

Prérequis

Claude Code v2.1+
Un projet avec un dossier .claude/

Le concept en 30 secondes

Un subagent est un assistant secondaire avec son propre contexte. Tu lui confies une tâche précise, il travaille isolé, puis te rend un résultat synthétisé. Le contexte principal reste propre.

@diagram:flow
Tâche précise :: Tu confies un objectif clair au subagent.
Travail isolé :: Il opère dans son propre contexte.
Résultat synthétisé :: Il rend une réponse ; le contexte principal reste propre.

Pense à un reviewer de code qui n’a pas besoin de savoir toute l’histoire de la conversation pour faire son boulot.

Étapes

1. Créer ton premier subagent

Crée le dossier .claude/agents/ à la racine de ton projet :

mkdir -p .claude/agents
```n
Crée un fichier `.claude/agents/code-reviewer.md` :

```yaml
---
name: code-reviewer
description: Expert en revue de code. Utilise PROACTIVEment après chaque modification.
tools: Read, Grep, Glob, Bash
---

Tu es un senior code reviewer. Quand on t'invoque :

1. Lancer `git diff` pour voir les changements récents
2. Te concentrer sur les fichiers modifiés
3. Signaler : sécurité, perf, lisibilité, tests manquants

Format de retour pour chaque problème :
- Sévérité : Critique / Haut / Moyen / Bas
- Fichier:ligne
- Description + suggestion de correction

2. Vérifier que Claude le reconnaît

Dans Claude Code, tape :

/agents

Tu dois voir code-reviewer dans la liste. Sinon, vérifie le chemin et le nom du fichier.

3. Invoquer le subagent

Méthode implicite — mentionne-le dans ta demande :

Fais une revue de ce module d'authentification

Si le description contient “Utilise PROACTIVEment”, Claude le déclenchera automatiquement après les modifications de code.

Méthode explicite — force l’invocation :

@"code-reviewer (agent)" regarde ce fichier

Méthode CLI — session entière avec cet agent :

claude --agent code-reviewer

4. Choisir les bons outils

Moins d’outils = moins de risques. Exemples de configurations :

@diagram:cc-subagents

Syntaxe dans le frontmatter :

tools: Read, Grep, Bash(npm:*), Bash(test:*)

Bash(npm:*) limite les commandes shell aux appels npm.

5. Utiliser la mémoire persistante

Un subagent peut garder des notes entre les sessions :

---
name: researcher
memory: user
---

Tu es un assistant de recherche. Stocke tes découvertes dans ton répertoire mémoire.
Lis MEMORY.md au début de chaque session pour reprendre le fil.

Scope	Chemin	Usage
`user`	`~/.claude/agent-memory/researcher/`	Perso, tous projets
`project`	`.claude/agent-memory/researcher/`	Partagé avec l’équipe
`local`	`.claude/agent-memory-local/researcher/`	Local, non versionné

6. Isoler avec un worktree git

Pour expérimenter sans toucher la branche courante :

---
name: feature-builder
isolation: worktree
description: Implémente des features dans un worktree isolé
tools: Read, Write, Edit, Bash, Grep, Glob
---

Le subagent travaille sur une branche temporaire. Si rien n’est modifié, le worktree est nettoyé automatiquement. Sinon, le chemin et la branche sont retournés pour review.

7. Lancer en arrière-plan

Pour les tâches longues :

---
name: long-analyzer
background: true
description: Analyse longue en arrière-plan
---

Raccourcis clavier :

Ctrl+B — mettre la tâche courante en arrière-plan
Ctrl+F (2x) — tuer tous les agents en arrière-plan

Vérification

Dossier .claude/agents/ créé
Fichier .md avec frontmatter YAML valide
/agents affiche le subagent
Invocation explicite fonctionne (@"nom (agent)")
Résultat retourné au contexte principal

Pièges courants

Nom en majuscules ou avec espaces → utilise uniquement minuscules et tirets. Depuis v2.1.140, code-reviewer et code_reviewer sont équivalents.
Oublier le frontmatter → le fichier est ignoré sans le --- initial.
Trop d’outils → un reviewer n’a pas besoin de Write. Restreins.
Contexte vide → le subagent part de zéro. Passe les infos nécessaires dans la demande.
Tâche trop simple → un subagent ajoute de la latence. Pas la peine pour un grep.

Récapitulatif

Action	Commande
Lister les agents	`/agents`
Invoquer explicitement	`@"nom-agent (agent)"`
Session avec un agent	`claude --agent nom-agent`
Lister en CLI	`claude agents`
Créer un agent projet	`.claude/agents/nom.md`
Créer un agent global	`~/.claude/agents/nom.md`
Mettre en arrière-plan	`Ctrl+B`

Pour aller plus loin

Doc officielle Subagents
Guide Agent Teams (expérimental)

Inspiré du guide claude-howto de luongnv89 (MIT)