Le guide complet de Claude Subagent

Introduction

Lorsque vous travaillez sur des tâches complexes avec Claude Code, vous avez peut-être rencontré ce dilemme : le contexte de la conversation principale ne cesse de croître, l'IA commence à « oublier » des informations importantes mentionnées plus tôt, et la qualité des réponses se dégrade progressivement.

Les Subagents ont été conçus pour résoudre exactement ce problème.

Si les Skills sont les « manuels de procédures » de Claude, alors les Subagents sont les « spécialistes dédiés » que vous engagez — ils disposent de leur propre espace de travail (contexte), se concentrent sur des types de travail spécifiques et vous rendent compte des résultats une fois leur mission accomplie.

Comprendre les Subagents

Imaginez que vous êtes le PDG d'une entreprise. Lorsque l'entreprise est petite, vous gérez tout vous-même. Mais à mesure que l'activité se développe, vous commencez à embaucher des spécialistes : un comptable pour les finances, un responsable RH pour le recrutement, des ingénieurs pour le développement. Chaque employé travaille à son propre poste, accomplit ses tâches et vous rend compte.

Les Subagents jouent exactement ce rôle dans Claude Code.

D'un point de vue technique, les Subagents sont des assistants IA spécialisés présentant les caractéristiques suivantes :

Pourquoi le contexte isolé est important

C'est le principe de conception le plus fondamental des Subagents, et il mérite d'être bien compris.

Dans une conversation classique, toutes les informations s'accumulent dans le même contexte. Lorsque vous demandez à Claude de rechercher dans la base de code, d'analyser des fichiers, puis d'effectuer des modifications, toutes ces étapes intermédiaires consomment de l'espace de contexte. À mesure que la conversation s'approfondit, le contexte devient de plus en plus encombré, et Claude peut commencer à « oublier » des informations importantes du début.

Les Subagents changent cette dynamique :

Conversation principale (concentrée sur les objectifs de haut niveau)
│
├── Utilisateur : Aidez-moi à optimiser les performances de ce module
│
├── Claude : Laissez-moi analyser cela...
│   │
│   └── [Appel du Subagent Explore]
│       │ Dans un contexte isolé :
│       ├── Recherche des fichiers pertinents
│       ├── Analyse de la structure du code
│       ├── Identification des goulots d'étranglement
│       └── Retour : 3 points d'optimisation trouvés...
│
└── Claude : D'après l'analyse, j'ai trouvé 3 points d'optimisation...

Le processus d'analyse du Subagent ne pollue pas la conversation principale. La conversation principale ne reçoit que des résultats synthétisés, maintenant clarté et concentration.

Comme le recommande Anthropic dans ses bonnes pratiques :

Types de Subagents intégrés

Claude Code est livré avec trois Subagents intégrés couramment utilisés, prêts à l'emploi :

Ces agents intégrés sont automatiquement invoqués en fonction du type de tâche.

Ma compréhension et ma pratique

Si vous observez attentivement les trois Subagents intégrés officiels, vous remarquerez un fil conducteur : ce sont tous des tâches de recherche et de planification. Explore gère l'exploration de la base de code, Plan gère la création de plans, et même General-purpose est principalement utilisé pour la recherche et l'analyse. Aucun d'entre eux n'est spécifiquement conçu pour écrire du code.

Cela confirme ma compréhension des Subagents : la valeur fondamentale des Subagents n'est pas « un contexte propre » — c'est de permettre à l'agent principal de rester concentré sur l'exécution du travail.

Répartition du travail

Mon mode d'utilisation est simple : les Subagents gèrent la recherche, la planification et la revue — le travail de « collecte d'informations » — tandis que l'agent principal se charge de l'exécution effective.

Subagent (Chercheur)               Agent principal (Exécuteur)
     │                                    │
     ├── Explorer la structure du code     │
     ├── Analyser les dépendances          │
     ├── Créer un plan de mise en œuvre    │
     └── Retourner le contexte synthétisé ─→ Exécuter les tâches selon le contexte
                                           │
                                           ├── Écrire le code
                                           ├── Modifier les fichiers
                                           └── Exécuter les tests

Pourquoi je ne laisse pas les Subagents écrire du code

Certaines personnes aiment faire dispatcher par l'agent principal plusieurs Subagents pour écrire du code. Je pense que cela ne fonctionne pas bien. La raison est simple : un déficit de contexte sévère.

Le contexte d'un Subagent est isolé — il ne sait pas ce qui a été discuté dans la conversation principale, quelles décisions ont été prises, ni quelles contraintes existent. Lui faire écrire du code, c'est comme demander à un employé fraîchement embauché de réaliser une tâche de manière autonome sans aucune information de contexte — le résultat risque fort de ne pas correspondre à vos attentes.

Positionner les Subagents comme des « chercheurs » est bien plus pertinent :

• Les tâches de recherche nécessitent intrinsèquement moins de contexte
• Ils retournent des informations plutôt que du code, que l'agent principal peut exploiter avec le contexte complet
• Même si les résultats de recherche sont légèrement décalés, l'agent principal peut corriger le tir

Mon utilisation quotidienne

1. Avant de commencer une nouvelle tâche : faire explorer rapidement la structure du code pertinent par l'agent Explore
2. Planification de tâches complexes : faire analyser les besoins et créer les étapes de mise en œuvre par l'agent Plan
3. Revue de code : faire vérifier la qualité du code et les problèmes de sécurité par un agent Review
4. Écriture du code : l'agent principal écrit le code en s'appuyant sur le contexte collecté

Voici ma liste actuelle d'agents :

L'avantage de cette approche est que la fenêtre de contexte de l'agent principal reste propre — elle ne contient que « les informations dont j'ai besoin », et non « un amas de résultats intermédiaires issus du processus de recherche du Subagent ».

Comment utiliser les Subagents

Voir les agents disponibles

Utilisez la commande /agents pour voir tous les Subagents disponibles dans votre environnement actuel :

/agents

Cela affichera les agents intégrés ainsi que vos agents personnalisés.

Délégation automatique

Dans la plupart des cas, vous n'avez pas besoin de spécifier manuellement quel Subagent utiliser. Claude sélectionnera automatiquement l'agent approprié en fonction du type de tâche :

• Tâches d'exploration du code → Subagent Explore
• Besoin de créer un plan → Subagent Plan
• Tâches complexes en plusieurs étapes → Subagent General-purpose

Invocation explicite

Si vous souhaitez utiliser explicitement un agent spécifique, vous pouvez le préciser directement dans votre prompt :

Utilise l'agent Explore pour rechercher tous les fichiers contenant authentication

Ou :

Lance un subagent pour analyser le graphe de dépendances de ce module

Où trouver des Subagents

Agents intégrés

Les trois agents intégrés livrés avec Claude Code (Explore, Plan, General-purpose) fonctionnent directement sans aucune configuration nécessaire.

Ressources communautaires

wshobson/agents — Un dépôt de modèles de Subagents de qualité avec des agents courants pour la revue de code, l'exécution de tests, et plus encore :

Visiter

Claude Plugin Hub — Une place de marché de plugins où vous pouvez trouver divers agents et extensions :

Visiter

Créer des Subagents personnalisés

Au-delà des agents intégrés et des ressources communautaires, vous pouvez créer vos propres Subagents.

Emplacement des fichiers de configuration

Format de configuration

Chaque Subagent est un fichier Markdown contenant un frontmatter YAML et un prompt système :

---
name: code-reviewer
description: Reviews code for security and style issues. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer focusing on:
- Security vulnerability detection
- Code style and best practices
- Performance optimization

## Review Output
1. **Critical Issues**: Security, correctness
2. **Warnings**: Style, performance
3. **Suggestions**: Refactoring opportunities

Référence des champs

Permissions des outils

Configurez les permissions minimales nécessaires en fonction du rôle de l'agent :

Capacités avancées

En tant qu'entités indépendantes, les Subagents peuvent accéder à la plupart des capacités de l'agent principal :

Accès aux outils MCP

Omettre le champ tools hérite automatiquement de tous les outils MCP. Pour les spécifier explicitement, utilisez ce format :

tools: Read, Grep, mcp__github__create_issue, mcp__linear__list_issues

Connaissances des Skills

Si vous avez besoin qu'un Subagent utilise les connaissances d'un Skill spécifique, référencez-le dans le corps du prompt système :

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Follow the guidelines in the code-standards skill.

When reviewing:
- Apply project coding standards
- Check for security issues

De cette manière, le Subagent se référera aux directives du Skill concerné lors de l'exécution.

Modes de permission

Limitations

• Ne peut pas appeler d'autres Subagents (pour éviter la récursion infinie)
• Ne prend pas en charge la planification étape par étape

Bonnes pratiques

• Responsabilité unique : chaque agent se concentre sur un objectif clair
• Moindre privilège : n'accordez que les outils nécessaires
• Description claire : le champ description détermine la qualité de l'invocation automatique — précisez clairement « quand l'utiliser »
• Contrôle de version : validez les configurations au niveau projet dans Git pour faciliter le partage en équipe

Pour conclure

La valeur fondamentale des Subagents est de permettre à l'agent principal de rester concentré sur le travail en cours. Positionnez les Subagents comme des chercheurs plutôt que des exécuteurs, et vous constaterez une amélioration significative de l'efficacité de Claude Code.

Si vous n'êtes pas encore familier avec les bases de Claude Code, je vous recommande de lire d'abord Mes bonnes pratiques Claude Code pour comprendre les commandes essentielles et les flux de travail.

Pour aller plus loin

• Architecture du système Claude expliquée — La place des Subagents dans l'ensemble du système Claude
• Qu'est-ce que Claude Skills — La différence et la complémentarité entre Skills et Subagents