Passer au contenu principal
Les sous-agents personnalisés dans Claude Code sont des assistants IA spécialisés qui peuvent être invoqués pour gérer des types de tâches spécifiques. Ils permettent une résolution de problèmes plus efficace en fournissant des configurations spécifiques aux tâches avec des invites système personnalisées, des outils et une fenêtre de contexte séparée.

​
Que sont les sous-agents ?

Les sous-agents sont des personnalités IA préconfigurées que Claude Code peut déléguer à des tâches. Chaque sous-agent :
  • A un objectif spécifique et un domaine d’expertise
  • Utilise sa propre fenêtre de contexte séparée de la conversation principale
  • Peut être configuré avec des outils spécifiques qu’il est autorisé à utiliser
  • Inclut une invite système personnalisée qui guide son comportement
Lorsque Claude Code rencontre une tâche qui correspond à l’expertise d’un sous-agent, il peut déléguer cette tâche au sous-agent spécialisé, qui fonctionne indépendamment et retourne les résultats.

​
Avantages clés

Préservation du contexte

Chaque sous-agent fonctionne dans son propre contexte, évitant la pollution de la conversation principale et la maintenant concentrée sur les objectifs de haut niveau.

Expertise spécialisée

Les sous-agents peuvent être affinés avec des instructions détaillées pour des domaines spécifiques, ce qui entraîne des taux de réussite plus élevés sur les tâches désignées.

Réutilisabilité

Une fois créés, les sous-agents peuvent être utilisés dans différents projets et partagés avec votre équipe pour des flux de travail cohérents.

Permissions flexibles

Chaque sous-agent peut avoir différents niveaux d’accès aux outils, vous permettant de limiter les outils puissants à des types de sous-agents spécifiques.

​
Démarrage rapide

Pour créer votre premier sous-agent :
1

Ouvrir l'interface des sous-agents

Exécutez la commande suivante :
/agents
2

Sélectionner « Créer un nouvel agent »

Choisissez si vous souhaitez créer un sous-agent au niveau du projet ou au niveau de l’utilisateur
3

Définir le sous-agent

  • Recommandé : Générer d’abord avec Claude, puis personnaliser pour le rendre vôtre
  • Décrivez votre sous-agent en détail et quand il doit être utilisé
  • Sélectionnez les outils auxquels vous souhaitez accorder l’accès (ou laissez vide pour hériter de tous les outils)
  • L’interface affiche tous les outils disponibles, ce qui facilite la sélection
  • Si vous générez avec Claude, vous pouvez également modifier l’invite système dans votre propre éditeur en appuyant sur e
4

Enregistrer et utiliser

Votre sous-agent est maintenant disponible ! Claude l’utilisera automatiquement le cas échéant, ou vous pouvez l’invoquer explicitement :
> Use the code-reviewer subagent to check my recent changes

​
Configuration du sous-agent

​
Emplacements des fichiers

Les sous-agents sont stockés sous forme de fichiers Markdown avec un préambule YAML dans deux emplacements possibles :
TypeEmplacementPortéePriorité
Sous-agents de projet.claude/agents/Disponible dans le projet actuelLa plus élevée
Sous-agents utilisateur~/.claude/agents/Disponible dans tous les projetsPlus basse
Lorsque les noms de sous-agents entrent en conflit, les sous-agents au niveau du projet ont la priorité sur les sous-agents au niveau de l’utilisateur.

​
Agents de plugin

Les plugins peuvent fournir des sous-agents personnalisés qui s’intègrent de manière transparente à Claude Code. Les agents de plugin fonctionnent de manière identique aux agents définis par l’utilisateur et apparaissent dans l’interface /agents. Emplacements des agents de plugin : Les plugins incluent des agents dans leur répertoire agents/ (ou des chemins personnalisés spécifiés dans le manifeste du plugin). Utilisation des agents de plugin :
  • Les agents de plugin apparaissent dans /agents aux côtés de vos agents personnalisés
  • Peuvent être invoqués explicitement : « Utiliser l’agent code-reviewer du security-plugin »
  • Peuvent être invoqués automatiquement par Claude le cas échéant
  • Peuvent être gérés (visualisés, inspectés) via l’interface /agents
Consultez la référence des composants de plugin pour plus de détails sur la création d’agents de plugin.

​
Configuration basée sur CLI

Vous pouvez également définir des sous-agents dynamiquement en utilisant le drapeau CLI --agents, qui accepte un objet JSON : 
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Priorité : Les sous-agents définis par CLI ont une priorité inférieure aux sous-agents au niveau du projet mais une priorité supérieure aux sous-agents au niveau de l’utilisateur. Cas d’utilisation : Cette approche est utile pour :
  • Tester rapidement les configurations de sous-agents
  • Les sous-agents spécifiques à une session qui n’ont pas besoin d’être enregistrés
  • Les scripts d’automatisation qui ont besoin de sous-agents personnalisés
  • Partager les définitions de sous-agents dans la documentation ou les scripts
Pour des informations détaillées sur le format JSON et toutes les options disponibles, consultez la documentation de référence CLI.

​
Format de fichier

Chaque sous-agent est défini dans un fichier Markdown avec cette structure : 
---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sonnet  # Optional - specify model alias or 'inherit'
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
Champs de configuration

ChampRequisDescription
nameOuiIdentifiant unique utilisant des lettres minuscules et des tirets
descriptionOuiDescription en langage naturel de l’objectif du sous-agent
toolsNonListe séparée par des virgules d’outils spécifiques. S’il est omis, hérite de tous les outils du thread principal
modelNonModèle à utiliser pour ce sous-agent. Peut être un alias de modèle (sonnet, opus, haiku) ou 'inherit' pour utiliser le modèle de la conversation principale. S’il est omis, utilise par défaut le modèle de sous-agent configuré

​
Sélection du modèle

Le champ model vous permet de contrôler quel modèle IA le sous-agent utilise :
  • Alias de modèle : Utilisez l’un des alias disponibles : sonnet, opus ou haiku
  • 'inherit' : Utilisez le même modèle que la conversation principale (utile pour la cohérence)
  • Omis : S’il n’est pas spécifié, utilise le modèle par défaut configuré pour les sous-agents (sonnet)
L’utilisation de 'inherit' est particulièrement utile lorsque vous souhaitez que vos sous-agents s’adaptent au choix de modèle de la conversation principale, assurant des capacités cohérentes et un style de réponse tout au long de votre session.

​
Outils disponibles

Les sous-agents peuvent avoir accès à n’importe quel outil interne de Claude Code. Consultez la documentation des outils pour une liste complète des outils disponibles.
Recommandé : Utilisez la commande /agents pour modifier l’accès aux outils - elle fournit une interface interactive qui répertorie tous les outils disponibles, y compris tous les outils de serveur MCP connectés, ce qui facilite la sélection de ceux dont vous avez besoin.
Vous avez deux options pour configurer les outils :
  • Omettre le champ tools pour hériter de tous les outils du thread principal (par défaut), y compris les outils MCP
  • Spécifier les outils individuels sous forme de liste séparée par des virgules pour un contrôle plus granulaire (peut être modifié manuellement ou via /agents)
Outils MCP : Les sous-agents peuvent accéder aux outils MCP des serveurs MCP configurés. Lorsque le champ tools est omis, les sous-agents héritent de tous les outils MCP disponibles pour le thread principal.

​
Gestion des sous-agents

​
Utilisation de la commande /agents (Recommandé)

La commande /agents fournit une interface complète pour la gestion des sous-agents : 
/agents
Cela ouvre un menu interactif où vous pouvez :
  • Afficher tous les sous-agents disponibles (intégrés, utilisateur et projet)
  • Créer de nouveaux sous-agents avec une configuration guidée
  • Modifier les sous-agents personnalisés existants, y compris leur accès aux outils
  • Supprimer les sous-agents personnalisés
  • Voir quels sous-agents sont actifs en cas de doublons
  • Gérer facilement les permissions des outils avec une liste complète des outils disponibles

​
Gestion directe des fichiers

Vous pouvez également gérer les sous-agents en travaillant directement avec leurs fichiers : 
# Create a project subagent
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# Create a user subagent
mkdir -p ~/.claude/agents
# ... create subagent file

​
Utilisation efficace des sous-agents

​
Délégation automatique

Claude Code délègue proactivement les tâches en fonction de :
  • La description de la tâche dans votre demande
  • Le champ description dans les configurations de sous-agents
  • Le contexte actuel et les outils disponibles
Pour encourager une utilisation plus proactive des sous-agents, incluez des phrases comme « use PROACTIVELY » ou « MUST BE USED » dans votre champ description.

​
Invocation explicite

Demandez un sous-agent spécifique en le mentionnant dans votre commande : 
> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

​
Sous-agents intégrés

Claude Code inclut des sous-agents intégrés disponibles prêts à l’emploi :

​
Sous-agent Plan

Le sous-agent Plan est un agent intégré spécialisé conçu pour être utilisé pendant le mode plan. Lorsque Claude fonctionne en mode plan (mode sans exécution), il utilise le sous-agent Plan pour mener des recherches et rassembler des informations sur votre base de code avant de présenter un plan. Caractéristiques clés :
  • Modèle : Utilise Sonnet pour une analyse plus capable
  • Outils : A accès aux outils Read, Glob, Grep et Bash pour l’exploration de la base de code
  • Objectif : Recherche des fichiers, analyse la structure du code et rassemble le contexte
  • Invocation automatique : Claude utilise automatiquement cet agent en mode plan lorsqu’il a besoin de rechercher la base de code
Comment cela fonctionne : Lorsque vous êtes en mode plan et que Claude a besoin de comprendre votre base de code pour créer un plan, il délègue les tâches de recherche au sous-agent Plan. Cela évite l’imbrication infinie d’agents (les sous-agents ne peuvent pas générer d’autres sous-agents) tout en permettant à Claude de rassembler le contexte nécessaire. Scénario d’exemple : 
User: [In plan mode] Help me refactor the authentication module

Claude: Let me research your authentication implementation first...
[Internally invokes Plan subagent to explore auth-related files]
[Plan subagent searches codebase and returns findings]
Claude: Based on my research, here's my proposed plan...
Le sous-agent Plan n’est utilisé qu’en mode plan. En mode exécution normal, Claude utilise l’agent à usage général ou d’autres sous-agents personnalisés que vous avez créés.

​
Exemples de sous-agents

​
Examinateur de code

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​
Débogueur

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

​
Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​
Bonnes pratiques

  • Commencer par les agents générés par Claude : Nous recommandons vivement de générer votre sous-agent initial avec Claude, puis d’itérer dessus pour le rendre personnellement vôtre. Cette approche vous donne les meilleurs résultats - une base solide que vous pouvez personnaliser selon vos besoins spécifiques.
  • Concevoir des sous-agents ciblés : Créez des sous-agents avec des responsabilités uniques et claires plutôt que d’essayer de faire faire tout à un seul sous-agent. Cela améliore les performances et rend les sous-agents plus prévisibles.
  • Écrire des invites détaillées : Incluez des instructions spécifiques, des exemples et des contraintes dans vos invites système. Plus vous fournissez de conseils, mieux le sous-agent fonctionnera.
  • Limiter l’accès aux outils : N’accordez que les outils nécessaires à l’objectif du sous-agent. Cela améliore la sécurité et aide le sous-agent à se concentrer sur les actions pertinentes.
  • Contrôle de version : Vérifiez les sous-agents de projet dans le contrôle de version afin que votre équipe puisse en bénéficier et les améliorer de manière collaborative.

​
Utilisation avancée

​
Chaînage de sous-agents

Pour les flux de travail complexes, vous pouvez chaîner plusieurs sous-agents : 
> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

​
Sélection dynamique de sous-agents

Claude Code sélectionne intelligemment les sous-agents en fonction du contexte. Rendez vos champs description spécifiques et orientés vers l’action pour de meilleurs résultats.

​
Sous-agents reprennables

Les sous-agents peuvent être repris pour continuer les conversations précédentes, ce qui est particulièrement utile pour les tâches de recherche ou d’analyse longues qui doivent être poursuivies sur plusieurs invocations. Comment cela fonctionne :
  • Chaque exécution de sous-agent se voit attribuer un agentId unique
  • La conversation de l’agent est stockée dans un fichier de transcription séparé : agent-{agentId}.jsonl
  • Vous pouvez reprendre un agent précédent en fournissant son agentId via le paramètre resume
  • Lorsqu’il est repris, l’agent continue avec le contexte complet de sa conversation précédente
Exemple de flux de travail : Invocation initiale : 
> Use the code-analyzer agent to start reviewing the authentication module

[Agent completes initial analysis and returns agentId: "abc123"]
Reprendre l’agent : 
> Resume agent abc123 and now analyze the authorization logic as well

[Agent continues with full context from previous conversation]
Cas d’utilisation :
  • Recherche longue : Décomposer l’analyse de grande base de code en plusieurs sessions
  • Affinement itératif : Continuer à affiner le travail d’un sous-agent sans perdre le contexte
  • Flux de travail multi-étapes : Faire travailler un sous-agent sur des tâches connexes séquentiellement tout en maintenant le contexte
Détails techniques :
  • Les transcriptions d’agent sont stockées dans votre répertoire de projet
  • L’enregistrement est désactivé lors de la reprise pour éviter de dupliquer les messages
  • Les agents synchrones et asynchrones peuvent être repris
  • Le paramètre resume accepte l’ID d’agent d’une exécution précédente
Utilisation programmatique : Si vous utilisez le SDK Agent ou interagissez directement avec AgentTool, vous pouvez passer le paramètre resume : 
{
  "description": "Continue analysis",
  "prompt": "Now examine the error handling patterns",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from previous execution
}
Gardez une trace des ID d’agent pour les tâches que vous pourriez vouloir reprendre ultérieurement. Claude Code affiche l’ID d’agent lorsqu’un sous-agent termine son travail.

​
Considérations de performance

  • Efficacité du contexte : Les agents aident à préserver le contexte principal, permettant des sessions globales plus longues
  • Latence : Les sous-agents commencent avec un contexte vierge à chaque fois qu’ils sont invoqués et peuvent ajouter de la latence car ils rassemblent le contexte dont ils ont besoin pour faire leur travail efficacement.

​
Documentation connexe

  • Plugins - Étendre Claude Code avec des agents personnalisés via des plugins
  • Commandes slash - En savoir plus sur les autres commandes intégrées
  • Paramètres - Configurer le comportement de Claude Code
  • Hooks - Automatiser les flux de travail avec des gestionnaires d’événements