Accueil › Claude Code › Subagents

Subagents et Agent Teams dans Claude Code : le guide multi-agent

Claude Code propose deux patterns de parallélisation : les subagents (travailleurs isolés qui rapportent au parent) et les Agent Teams (équipes coordonnées qui communiquent entre elles). Le choix entre les deux dépend d’un critère simple : vos agents ont-ils besoin de se parler ?

Claude Code ne se limite pas à un seul agent travaillant séquentiellement. Vous pouvez déléguer des tâches à des subagents spécialisés qui opèrent en parallèle dans leur propre fenêtre de contexte, ou orchestrer des Agent Teams complets avec communication inter-agents, listes de tâches partagées et coordination automatique.

Ce guide couvre les deux patterns, leur configuration, les cas d’usage optimaux et les bonnes pratiques pour éviter les pièges courants du multi-agent.

Subagents : les travailleurs isolés

Concept

Un subagent est une instance Claude spécialisée qui tourne dans sa propre fenêtre de contexte, isolée de l’agent principal. Le subagent reçoit une tâche, l’exécute en autonomie, et retourne un résultat compressé au parent. Seul le résultat final revient, pas le raisonnement intermédiaire ni les étapes explorées.

L’analogie : vous êtes un directeur de recherche. Vous ne lisez pas chaque source primaire vous-même. Vous déléguez des questions ciblées à des chercheurs, ils reviennent avec des résultats synthétisés, et vous assemblez le tout. C’est exactement ce que font les subagents.

L’intérêt principal n’est pas seulement la parallélisation : c’est la compression. Un subagent peut explorer des centaines de fichiers, lire de la documentation et exécuter des commandes. Toute cette exploration est condensée en un signal propre qui entre dans le contexte du parent sans le polluer.

Utilisation

Vous déclenchez un subagent en demandant à Claude Code de déléguer. Exemples de prompts :

# Délégation explicite
Utilise un subagent pour explorer le système d'authentification
et me faire un résumé des fichiers impliqués et du flux complet.

# Délégation via "use subagents"
Use subagents to investigate the performance of our database
queries and identify the N+1 problems.

Claude Code lance automatiquement le subagent dans un contexte séparé. Le subagent a accès aux outils standard (Read, Grep, Glob, Bash) mais opère dans sa propre fenêtre de contexte.

Configuration des subagents

Pour des subagents spécialisés et réutilisables, créez des fichiers Markdown dans .claude/agents/ avec un frontmatter YAML :

---
name: qa-reviewer
description: Agent spécialisé en review de qualité de code
model: sonnet
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
maxTurns: 20
---

Tu es un agent QA senior. Analyse le code fourni et identifie :
- Bugs potentiels et edge cases non gérés
- Problèmes de performance (N+1, boucles inutiles)
- Violations des conventions du projet (voir CLAUDE.md)
- Imports manquants ou inutilisés

Ne modifie aucun fichier. Produis un rapport structuré.

Les champs du frontmatter :

Bonnes pratiques subagents

Utilisez les subagents pour la recherche, pas pour l’écriture simultanée. Plusieurs subagents qui écrivent du code en parallèle font des hypothèses incompatibles. Quand vous mergez leur travail, les décisions implicites entrent en conflit. Réservez les subagents pour l’exploration, la recherche et l’analyse. L’écriture de code devrait rester dans l’agent principal ou dans des Agent Teams avec coordination.

Utilisez Sonnet ou Haiku pour les subagents. Les subagents font des tâches ciblées qui ne nécessitent pas la puissance (ni le coût) d’Opus 4.6. Spécifiez model: sonnet ou model: haiku dans le frontmatter pour économiser des tokens.

Limitez les outils au strict nécessaire. Un subagent de review ne devrait pas avoir accès à Write ou Edit. Un subagent de recherche n’a pas besoin de Bash. Le champ disallowedTools est votre ami.

Gardez les tâches ciblées. Chaque subagent doit avoir un objectif clair, un format de sortie attendu, des limites explicites sur ce qu’il ne doit pas couvrir. Sans ça, deux subagents travaillent sur la même chose sans le savoir.

Agent Teams : l’orchestration collaborative

Concept

Les Agent Teams sont une évolution des subagents. Au lieu de travailleurs isolés qui rapportent au parent, les teammates sont des sessions Claude Code complètes qui communiquent directement entre elles, partagent une liste de tâches et se coordonnent sans passer par le lead à chaque échange.

L’analogie : les subagents sont des freelances envoyés sur des missions séparées. Les Agent Teams sont une équipe Scrum : les membres communiquent, se passent le travail et résolvent les blocages entre eux.

Activation

Agent Teams est une fonctionnalité expérimentale, désactivée par défaut. Activez-la via l’environnement ou le fichier de configuration :

# Via variable d'environnement
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Ou dans settings.json
# Ajoutez CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"

Version requise : Claude Code v2.1.32 ou ultérieure. Vérifiez avec claude --version.

Optionnel mais recommandé : installez tmux pour voir chaque agent dans son propre panneau terminal. Sans tmux, tous les outputs apparaissent dans un seul thread de conversation.

Fonctionnement

Quand vous lancez une tâche qui bénéficie de travail parallèle, Claude crée une équipe avec un lead (orchestrateur) et des teammates (exécutants) :

1. Le lead comprend la tâche globale et la décompose en sous-tâches.
2. Il crée les teammates avec des rôles spécifiques (frontend, backend, tests, docs).
3. Chaque teammate travaille en autonomie dans sa propre fenêtre de contexte.
4. Les teammates communiquent directement entre eux via messages.
5. Les dépendances entre tâches sont gérées automatiquement.
6. Le lead synthétise les résultats quand tout est terminé.

Vous pouvez aussi interagir directement avec un teammate individuel sans passer par le lead. Dans l’interface, descendez jusqu’au teammate voulu et tapez votre message.

Cas d’usage optimaux

Subagents vs Agent Teams : le tableau décisif

La règle simple : si vos travailleurs n’ont pas besoin de se parler, utilisez des subagents. Si la découverte d’un agent change ce qu’un autre agent devrait faire, utilisez des Agent Teams.

Coût et optimisation

Le multi-agent consomme significativement plus de tokens qu’une session solo. Chaque subagent a sa propre fenêtre de contexte, et les tokens s’accumulent linéairement avec le nombre d’agents.

Estimations de coût :

Subagents : 4 subagents consomment environ 4x les tokens d’une session solo. L’overhead de coordination est minimal (le parent synthétise les résultats).

Agent Teams : une équipe de 3 teammates consomme environ 7x les tokens d’une session solo. La communication inter-agents et la coordination du lead ajoutent un overhead significatif. Sur un plan Max à 100 $/mois, comptez 8 à 10 tâches complexes par fenêtre de 5 heures.

Optimisations :

Utilisez model: sonnet pour les teammates (pas Opus). Sonnet offre un excellent rapport qualité/coût pour la coordination et les tâches de codage standard. Gardez les équipes petites (2 à 4 teammates). Au-delà, l’overhead de coordination dépasse les gains de parallélisation. Nettoyez les teams quand le travail est terminé : les teammates actifs mais idle continuent de consommer des tokens.

Hooks et subagents

Les hooks s’appliquent récursivement à tous les subagents. Si vous avez un hook PreToolUse qui bloque rm -rf, ce blocage s’applique aussi quand un subagent essaie d’exécuter cette commande. Vos filets de sécurité couvrent toute la chaîne d’exécution.

Les subagents peuvent aussi définir leurs propres hooks dans le frontmatter YAML. Un hook Stop défini dans le frontmatter d’un subagent est automatiquement converti en événement SubagentStop, ce qui permet de lancer des validations quand un subagent termine sa tâche.

Exemples concrets

Subagents : audit de codebase parallèle

Lance 3 subagents en parallèle pour auditer notre codebase :
1. Un subagent sécurité : cherche les injections SQL,
   les XSS, les secrets hardcodés et les dépendances vulnérables.
2. Un subagent performance : identifie les requêtes N+1,
   les boucles O(n²), et les imports inutiles.
3. Un subagent conventions : vérifie la conformité avec
   notre CLAUDE.md (TypeScript strict, pas de any, patterns React).

Chaque subagent produit un rapport structuré.
Synthétise les 3 rapports en un seul avec les problèmes
classés par sévérité.

L’agent principal lance les 3 subagents en parallèle. Chacun explore la codebase dans sa propre fenêtre de contexte. Seuls les rapports finaux reviennent au parent qui les fusionne. Le contexte du parent reste propre et léger.

Agent Teams : feature full-stack

Crée une équipe d'agents pour implémenter le système de
notifications en temps réel :
- Agent API : crée les endpoints REST et WebSocket dans le backend
- Agent Frontend : implémente les composants React de notification
- Agent Tests : écrit les tests E2E avec Playwright
- Agent Docs : met à jour la documentation API

L'agent API doit communiquer les types TypeScript à l'agent Frontend.
L'agent Tests attend que API et Frontend soient terminés pour tester.
Maintiens un haut standard de qualité sur tout le code produit.

Le lead décompose la tâche, crée les 4 teammates, gère les dépendances (Frontend attend les types de API, Tests attend les deux). Les teammates communiquent directement : quand l’agent API finit les types, il les envoie au Frontend sans repasser par le lead.

Agent Teams : QA automatisée

Un cas d’usage particulièrement efficace : lancer une équipe QA sur un site en cours de développement :

Utilise une équipe d'agents pour faire du QA sur mon blog.
Il tourne sur http://localhost:4321/
Vérifie l'accessibilité, les liens cassés, la performance,
la responsivité mobile et les erreurs de console.

Le lead vérifie que le site tourne, crée une équipe (typiquement 5 agents sur Sonnet pour limiter les coûts), chaque agent couvre un aspect du QA. Les résultats sont synthétisés en un rapport unique avec les problèmes classés par sévérité.

Erreurs courantes du multi-agent

Trois patterns d’échec reviennent systématiquement :

1. Descriptions de tâches vagues. Sans objectif clair, format de sortie attendu et limites explicites, deux agents finissent par travailler sur la même chose sans le savoir. Chaque subagent ou teammate doit savoir exactement ce qu’il produit et ce qu’il ne couvre pas.

2. Agents de vérification qui déclarent victoire sans vérifier. Un agent « testeur » qui dit « tout est OK » sans avoir lancé de tests réels est inutile. Soyez explicite : « Lance la suite de tests complète. Ne marque pas la tâche comme terminée tant que chaque test ne passe pas. Liste les cas testés et les résultats. »

3. Découper par rôle au lieu de par contexte. L’instinct est de découper par rôle (planificateur, implémenteur, testeur). Mais ça crée un téléphone arabe où l’information se dégrade à chaque handoff. Découpez plutôt par contexte : demandez-vous « de quel contexte cette sous-tâche a-t-elle réellement besoin ? » Si deux tâches nécessitent un contexte très similaire, elles appartiennent au même agent.

Comparaison avec Cursor

Le multi-agent dans Cursor fonctionne différemment. Les Background Agents de Cursor sont des sessions indépendantes qui clonent votre repo dans des VMs cloud et travaillent sur des branches séparées. Ils ne communiquent pas entre eux et ne se coordonnent pas. Chaque Background Agent produit une PR indépendante.

Cursor propose aussi jusqu’à 8 agents en parallèle sur un même prompt (via git worktrees), mais sans la communication inter-agents des Agent Teams. C’est plus proche des subagents de Claude Code que des Agent Teams.

Les Agent Teams de Claude Code sont uniques dans l’écosystème : aucun autre outil de coding IA ne propose de communication directe entre agents avec gestion automatique des dépendances et coordination distribuée. C’est un avantage significatif pour les tâches complexes nécessitant de la coordination, mais au prix d’un overhead de tokens important (~7x).

Approche progressive recommandée

Ne sautez pas directement aux Agent Teams. Construisez votre maîtrise progressivement :

Semaine 1 : subagents manuels. Demandez à Claude Code « utilise un subagent pour explorer X » sur des tâches de recherche. Observez comment le contexte reste propre.

Semaine 2 : subagents configurés. Créez 2 ou 3 fichiers dans .claude/agents/ pour vos tâches récurrentes (review de code, recherche de bugs, génération de documentation). Spécifiez les outils et le modèle.

Semaine 3 : parallélisation. Lancez plusieurs subagents en parallèle sur une tâche d’audit ou de tests. Mesurez le gain de temps vs le coût en tokens.

Semaine 4 : Agent Teams. Activez la fonctionnalité expérimentale et testez sur une feature multi-couche. Comparez avec l’approche subagents sur la même tâche. Vous saurez alors quand chaque pattern est le bon choix.