# Subagents Claude Code : les créer et les utiliser

URL: https://agentvera.dev/fr/blog/claude-code-subagents/ · Publié: 2026-10-23

Ce que sont les subagents de Claude Code, comment en écrire un dans .claude/agents, ce que font les champs tools et model, et quand préférer des agents séparés.

**En bref:**

- Un subagent s’exécute dans sa propre fenêtre de contexte, avec son propre prompt, ses outils et son modèle, et seule sa réponse finale revient dans la conversation principale.
- Les subagents sont des fichiers Markdown dans .claude/agents/ où seuls name et description sont obligatoires ; sans tools, le subagent reçoit tous les outils de la session principale.
- Les subagents conviennent aux tâches courtes comme la recherche et la revue, tandis que des agents parallèles séparés conviennent aux fonctionnalités et aux longues tâches qui finissent dans leur propre branche.

Les subagents de Claude Code sont des assistants à qui la session principale confie une seule tâche. Chacun s’exécute dans sa propre fenêtre de contexte, avec son propre prompt système, sa liste d’outils et son modèle, et seule sa réponse finale revient dans la conversation principale. Vous définissez un subagent sous forme de fichier Markdown dans `.claude/agents/`, et Claude l’utilise automatiquement quand la tâche correspond à sa description, ou quand vous le demandez par son nom.

Cet article couvre le fonctionnement des subagents, le format du fichier, les champs `tools` et `model`, la façon de les appeler, et la frontière entre un subagent et un agent séparé qui tourne à côté du premier. Les faits viennent de la [documentation officielle des subagents](https://code.claude.com/docs/en/sub-agents "Documentation des subagents de Claude Code"). Pour la version en un paragraphe, voyez l’[entrée du glossaire sur les subagents](/fr/glossary/subagent/ "Subagent").

## Comment fonctionnent les subagents

Quand Claude décide de déléguer, il appelle l’outil Agent (appelé Task avant la version 2.1.63) avec un court brief. Le subagent démarre avec un contexte vierge. Il reçoit son propre prompt système, le message de délégation, votre `CLAUDE.md`, l’état de git et les skills que vous avez préchargés pour lui. Il ne voit pas l’historique de la conversation principale.

Il traite ensuite la tâche avec les outils autorisés et renvoie un seul résultat. Tout ce qu’il a lu en chemin, comme des dizaines de fichiers, de longues sorties de grep ou des journaux de tests, reste dans son propre contexte. C’est la raison principale d’utiliser des subagents : la conversation principale reçoit un résumé, pas le bruit.

Quelques limites à connaître :

- Les subagents peuvent lancer leurs propres subagents, sur trois niveaux au maximum par défaut.
- Jusqu’à 20 peuvent tourner en même temps par défaut.
- Leurs requêtes comptent dans les mêmes limites d’utilisation que la session principale.
- Un subagent peut s’exécuter au premier plan, où l’agent principal attend, ou en arrière-plan pendant que l’agent principal continue.

## Les subagents intégrés

Claude Code fournit quelques subagents utilisables sans rien écrire :

| Subagent | Outils | Usage typique |
| --- | --- | --- |
| Explore | Lecture seule | Chercher et lire dans toute la base de code, en profondeur rapide, moyenne ou très approfondie |
| Plan | Lecture seule | Recherche en mode plan |
| General-purpose | Tous les outils | Tâches en plusieurs étapes qui demandent à la fois de la recherche et des modifications |

Explore est celui que vous verrez le plus. Quand Claude doit trouver où quelque chose est défini ou comment une fonctionnalité traverse plusieurs fichiers, il le confie souvent à Explore pour que les vidages de fichiers n’atterrissent pas dans votre contexte principal.

## Où vivent les fichiers de subagents

Les subagents sont des fichiers Markdown avec un frontmatter YAML. Claude Code les charge depuis plusieurs endroits, et quand deux portent le même nom, celui qui est le plus haut dans cette liste l’emporte :

| Emplacement | Portée |
| --- | --- |
| Réglages gérés | Toute l’organisation, définis par les administrateurs |
| Option `--agents` (JSON) | Une session |
| `.claude/agents/` | Un projet, partagé via git |
| `~/.claude/agents/` | Tous vos projets |
| Le dossier `agents/` d’un plugin | Partout où le plugin est installé |

Les subagents de projet dans `.claude/agents/` sont ceux à commiter, pour que toute l’équipe partage le même relecteur ou le même exécuteur de tests.

## Le format du fichier de subagent

Seuls `name` et `description` sont obligatoires. Le corps après le frontmatter est le prompt système du subagent.

```markdown
---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.
```

La `description` compte plus qu’il n’y paraît. C’est ce que Claude lit pour décider de déléguer ou non : dites donc ce que fait le subagent et quand l’utiliser. Des formules comme « à utiliser après avoir écrit du code » aident Claude à le choisir de lui-même.

### Le champ tools

`tools` est une liste d’autorisation. Avec `tools: Read, Grep, Glob, Bash`, le relecteur ci-dessus peut lire et lancer des commandes mais ne peut pas modifier de fichiers. Si vous omettez `tools`, le subagent hérite de tous les outils de la session principale, y compris les outils MCP. Il existe aussi `disallowedTools` quand il est plus simple de dire ce qu’il faut retirer que ce qu’il faut garder.

Gardez la liste aussi courte que la tâche le permet. Un relecteur n’a pas besoin d’Edit. Un chercheur n’a pas besoin de Bash. Moins d’outils, c’est moins de surprises et une mission plus claire.

### Le champ model

`model` accepte un alias (`sonnet`, `opus`, `haiku`), un identifiant complet de modèle, ou `inherit` pour utiliser le modèle de la session principale. Quand le subagent est appelé, Claude Code choisit le modèle dans cet ordre : un modèle passé avec cet appel, puis le champ `model` du fichier, puis la variable d’environnement `CLAUDE_CODE_SUBAGENT_MODEL`, puis le modèle de la session principale.

C’est ici que les subagents peuvent vraiment économiser de l’argent. Les recherches larges dans les fichiers et la lecture de journaux demandent rarement le modèle le plus puissant. Mettez-les sur Haiku et gardez la session principale sur le plus gros modèle pour les décisions. L’article sur la consommation de tokens de Claude Code présente d’autres moyens de réduire les dépenses.

### Autres champs utiles

| Champ | Ce qu’il fait |
| --- | --- |
| `permissionMode` | Mode de permission du subagent, par exemple plan ou acceptEdits |
| `skills` | Skills à charger dans le contexte du subagent au démarrage |
| `mcpServers` | Serveurs MCP que le subagent peut utiliser |
| `hooks` | Hooks qui s’appliquent pendant l’exécution de ce subagent |
| `memory` | Mémoire persistante à la portée utilisateur, projet ou locale |
| `maxTurns` | Limite haute du nombre de tours du subagent |
| `background` | Exécuter en arrière-plan par défaut |
| `isolation: worktree` | Exécuter dans un worktree git temporaire |
| `effort` | Effort de raisonnement du subagent |

## Comment appeler un subagent

Il y a trois façons :

1. **Laisser Claude décider.** Si la demande correspond à la description d’un subagent, Claude délègue de lui-même.
2. **Le demander par son nom.** « Utilise le subagent code-reviewer pour vérifier mon dernier commit. » Vous pouvez aussi le mentionner avec @ depuis le menu.
3. **Lancer toute une session sous son identité.** `claude --agent code-reviewer` démarre une session qui utilise le prompt, les outils et le modèle de ce subagent.

Pour une session ponctuelle, vous pouvez passer des subagents en JSON sans créer de fichiers :

```bash
claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
```

Pour empêcher Claude d’utiliser un subagent précis, ajoutez-le à la liste deny de vos permissions, par exemple `Agent(Explore)`.

## Subagents ou agents parallèles séparés

Les subagents et les agents parallèles répartissent tous deux le travail, mais ils résolvent des problèmes différents.

| | Subagents | Agents parallèles séparés |
| --- | --- | --- |
| Qui les lance | La session principale de Claude | Vous |
| Ce que vous voyez | Le résultat final, dans le chat principal | La session complète de chaque agent |
| Contexte | Neuf à chaque tâche, jeté ensuite | De longue durée, un par agent |
| Fichiers | Le même dossier de travail, sauf `isolation: worktree` | En général un worktree git chacun |
| Votre intervention en cours de tâche | Aucune, c’est l’agent principal qui lui parle | Vous pouvez orienter chacun |
| Idéal pour | Recherche, revue, exploration, tâches courtes et ciblées | Fonctionnalités, refactorings, longues tâches qui finissent dans une branche |

Utilisez un subagent quand l’agent principal a besoin d’une réponse pour continuer : « trouve tous les appelants de cette fonction », « relis ce diff », « résume ces journaux ». Le travail est court, son résultat est ce qui compte, et vous n’avez pas besoin de le regarder.

Utilisez des agents séparés quand chaque morceau est un vrai travail en soi : une fonctionnalité, une migration, une suite de tests. Vous voulez voir ce que chacun fait, répondre à ses questions et relire ses changements comme une branche. C’est la configuration décrite dans [agents de code parallèles](/fr/blog/parallel-coding-agents/ "Agents de code parallèles") et [exécuter plusieurs agents Claude Code](/fr/blog/run-multiple-claude-code-agents/ "Exécuter plusieurs agents Claude Code"), chaque agent dans son propre [worktree git](/fr/blog/git-worktree-parallel-agents/ "Git worktree pour agents parallèles").

Les deux se combinent bien. Un agent séparé peut toujours utiliser des subagents pour ses propres recherches et revues. Une bonne règle par défaut : des agents séparés pour le travail que vous confieriez à une personne, et des subagents pour les courses que ces agents effectuent. Pour des équipes plus grandes, l’article sur l’équipe d’agents IA couvre les rôles et les passages de relais, et l’entrée sur l’orchestration multi-agents présente l’idée générale.

Claude Code a aussi une fonctionnalité distincte appelée agent teams, où plusieurs sessions Claude travaillent ensemble. Ce n’est pas la même chose que les subagents, et cela sort du cadre de cet article.

## Des conseils pour des subagents qui marchent

- **Une mission par subagent.** « Relecteur » et « exécuteur de tests » marchent mieux que « assistant ».
- **Écrivez la description pour Claude.** Dites quand l’utiliser, pas seulement ce que c’est.
- **Limitez les outils.** Des subagents en lecture seule pour la recherche et la revue, des outils de modification seulement quand c’est nécessaire.
- **Choisissez le modèle exprès.** Haiku pour la recherche et les résumés, un modèle plus puissant pour la conception et les corrections délicates.
- **Demandez un rapport court.** Le résultat va dans le contexte principal : dites donc au subagent de renvoyer des conclusions, pas des vidages de fichiers.
- **Versionnez vos subagents de projet.** `.claude/agents/` dans git donne les mêmes assistants à tout le monde.

## Comment AgentVera montre les subagents

AgentVera est une application de bureau pour exécuter côte à côte de nombreux agents de code, Claude Code, Codex et d’autres. Elle gère les subagents de deux façons.

**Vous pouvez les voir.** Dans le volet d’un agent Claude Code, le bouton « Subagents » ouvre une vue en direct des subagents lancés par cet agent et de ce qu’ils font en ce moment. Chacun affiche son état (Running, Done, Error, Stopped), s’il s’exécute « in background », l’« Assigned task » reçue et son « Report ». Pendant que certains travaillent, une ligne « {count} subagents running — show » apparaît pour que vous ne les manquiez pas. La [visite du projet et la carte du code](/fr/features/project-tour-and-code-map/ "Visite du projet et carte du code") a aussi une chronologie des subagents avec le type, l’état, le nombre d’outils et la durée. Les deux lisent des transcriptions locales et ne concernent pour l’instant que les agents Claude Code.

**Un Explore moins cher.** Dans Settings → « Token saving », l’option « Explorer subagent » donne aux agents Claude un explorateur en lecture seule pour les recherches larges. L’analyse des fichiers tourne sur un modèle moins cher, Haiku par défaut, et seul le résultat revient dans la conversation principale. Si vous avez déjà votre propre fichier de subagent Explore, AgentVera laisse le vôtre en place. L’option se trouve à côté des smart tools, dans la même section.

**Des agents séparés quand le travail est plus gros.** La [vue d’équipe](/fr/features/team-view/ "Vue d’équipe") montre jusqu’à 24 agents à la fois. [Parallel team](/fr/features/parallel-team/ "Parallel team") (offres Pro et Team) découpe un objectif en parties, exécute chacune dans son propre worktree et les fusionne en une seule PR. La messagerie entre agents leur permet de se poser des questions, même d’une CLI à l’autre, et la coordination des agents prévient quand deux agents touchent le même fichier. Cela vous donne le côté agents séparés du tableau ci-dessus, avec les subagents toujours disponibles dans chaque agent Claude.

## Pour conclure

Les subagents sont l’outil adapté quand l’agent principal a besoin d’une réponse et que vous n’avez pas besoin de surveiller le travail : recherche, revue, exploration. Écrivez un fichier Markdown avec une description claire, une courte liste d’outils et un modèle choisi avec soin. Quand le travail est assez gros pour mériter sa propre branche et votre attention, lancez plutôt un agent séparé.

Pour aller plus loin :

- [Subagent (glossaire)](/fr/glossary/subagent/ "Subagent")
- [Agents de code parallèles](/fr/blog/parallel-coding-agents/ "Agents de code parallèles")
- [Visite du projet et carte du code](/fr/features/project-tour-and-code-map/ "Visite du projet et carte du code")
- [Parallel team](/fr/features/parallel-team/ "Parallel team")
- [Agent Claude Code](/fr/agents/claude-code/ "Claude Code dans AgentVera")

Pour essayer AgentVera, commencez par la [page d’accueil](/fr/ "AgentVera").

## Questions fréquentes

**Qu’est-ce qu’un subagent dans Claude Code ?** Un subagent est un assistant que la session principale de Claude Code lance pour une seule tâche. Il s’exécute dans sa propre fenêtre de contexte, avec son propre prompt système, ses outils et son modèle, et seul son résultat final revient dans la conversation principale.

**Comment créer un subagent Claude Code ?** Ajoutez un fichier Markdown dans .claude/agents/ de votre projet, ou dans ~/.claude/agents/ pour tous vos projets. Le frontmatter YAML demande un name et une description ; le corps est le prompt système. Les champs facultatifs incluent tools, model, permissionMode et isolation.

**Quel modèle un subagent utilise-t-il ?** Le champ model accepte un alias comme sonnet, opus ou haiku, un identifiant complet de modèle, ou inherit. S’il n’est pas défini, le subagent utilise le modèle de la session principale, sauf si la variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL dit autre chose.

**Les subagents économisent-ils des tokens ?** Ils gardent le contexte principal propre, car les lectures de fichiers et les résultats de recherche restent dans le subagent. Ils ne rendent pas le travail gratuit : leurs requêtes comptent dans les mêmes limites d’utilisation, et c’est l’envoi des recherches larges vers un modèle moins cher comme Haiku qui économise le plus.

**Quand utiliser des agents séparés plutôt que des subagents ?** Quand les tâches sont longues, modifient beaucoup de fichiers, demandent votre relecture en route ou doivent finir dans des branches séparées. Des agents séparés, chacun dans son worktree git, offrent cela ; les subagents conviennent aux tâches courtes et ciblées dont l’agent principal a besoin du résultat.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/