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 spécifiques de tâches. 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 auxquelles 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 travaille de manière indépendante et retourne les résultats.

Avantages clés

Préservation du contexte

Chaque sous-agent opère dans son propre contexte, empêchant la pollution de la conversation principale et la gardant 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, conduisant à 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 spécifiques de sous-agents.

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 de créer un sous-agent au niveau du projet ou au niveau utilisateur
3

Définir le sous-agent

  • Recommandé : Générez d’abord avec Claude, puis personnalisez pour le rendre vôtre
  • Décrivez votre sous-agent en détail et quand il devrait être utilisé
  • Sélectionnez les outils auxquels vous voulez accorder l’accès (ou laissez vide pour hériter de tous les outils)
  • L’interface montre tous les outils disponibles, rendant la sélection facile
  • Si vous générez avec Claude, vous pouvez aussi éditer l’invite système dans votre propre éditeur en appuyant sur e
4

Sauvegarder et utiliser

Votre sous-agent est maintenant disponible ! Claude l’utilisera automatiquement quand approprié, ou vous pouvez l’invoquer explicitement :
> Utilise le sous-agent code-reviewer pour vérifier mes changements récents

Configuration des sous-agents

Emplacements des fichiers

Les sous-agents sont stockés comme fichiers Markdown avec frontmatter 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 faible
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 utilisateur.

Agents de plugin

Les Plugins peuvent fournir des sous-agents personnalisés qui s’intègrent parfaitement avec 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 : “Utilise l’agent code-reviewer du security-plugin”
  • Peuvent être invoqués automatiquement par Claude quand approprié
  • Peuvent être gérés (visualisés, inspectés) via l’interface /agents
Voir la référence des composants de plugin pour les détails sur la création d’agents de plugin.

Configuration basée sur CLI

Vous pouvez aussi définir des sous-agents dynamiquement en utilisant le flag CLI --agents, qui accepte un objet JSON :
claude --agents '{
  "code-reviewer": {
    "description": "Expert réviseur de code. Utilise proactivement après les changements de code.",
    "prompt": "Tu es un réviseur de code senior. Concentre-toi sur la qualité du code, la sécurité et les meilleures pratiques.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Priorité : Les sous-agents définis par CLI ont une priorité plus faible que les sous-agents au niveau du projet mais une priorité plus élevée que les sous-agents au niveau utilisateur. Cas d’usage : Cette approche est utile pour :
  • Tester rapidement les configurations de sous-agents
  • Sous-agents spécifiques à la session qui n’ont pas besoin d’être sauvegardés
  • Scripts d’automatisation qui ont besoin de sous-agents personnalisés
  • Partager des 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, voir la documentation de référence CLI.

Format de fichier

Chaque sous-agent est défini dans un fichier Markdown avec cette structure :
---
name: votre-nom-de-sous-agent
description: Description de quand ce sous-agent devrait être invoqué
tools: outil1, outil2, outil3  # Optionnel - hérite de tous les outils si omis
model: sonnet  # Optionnel - spécifier l'alias du modèle ou 'inherit'
---

L'invite système de votre sous-agent va ici. Cela peut être plusieurs paragraphes
et devrait clairement définir le rôle du sous-agent, ses capacités et son approche
pour résoudre les problèmes.

Incluez des instructions spécifiques, les meilleures pratiques et toutes les contraintes
que le sous-agent devrait suivre.

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. Si 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. Si omis, utilise par défaut le modèle de sous-agent configuré

Sélection de modèle

Le champ model vous permet de contrôler quel modèle IA le sous-agent utilise :
  • Alias de modèle : Utilisez 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 : Si non spécifié, utilise le modèle par défaut configuré pour les sous-agents (sonnet)
Utiliser 'inherit' est particulièrement utile quand vous voulez 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 uniforme tout au long de votre session.

Outils disponibles

Les sous-agents peuvent se voir accorder l’accès à n’importe lequel des outils internes de Claude Code. Voir 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 liste tous les outils disponibles, y compris tous les outils de serveur MCP connectés, rendant plus facile 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 des outils individuels comme une liste séparée par des virgules pour un contrôle plus granulaire (peut être édité manuellement ou via /agents)
Outils MCP : Les sous-agents peuvent accéder aux outils MCP des serveurs MCP configurés. Quand le champ tools est omis, les sous-agents héritent de tous les outils MCP disponibles au 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 :
  • Voir tous les sous-agents disponibles (intégrés, utilisateur et projet)
  • Créer de nouveaux sous-agents avec une configuration guidée
  • Éditer 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 quand des doublons existent
  • Gérer facilement les permissions d’outils avec une liste complète des outils disponibles

Gestion directe des fichiers

Vous pouvez aussi gérer les sous-agents en travaillant directement avec leurs fichiers :
# Créer un sous-agent de projet
mkdir -p .claude/agents
echo '---
name: test-runner
description: Utilise proactivement pour exécuter les tests et corriger les échecs
---

Tu es un expert en automatisation de tests. Quand tu vois des changements de code, exécute proactivement les tests appropriés. Si les tests échouent, analyse les échecs et corrige-les tout en préservant l'intention originale du test.' > .claude/agents/test-runner.md

# Créer un sous-agent utilisateur
mkdir -p ~/.claude/agents
# ... créer le fichier de sous-agent

Utilisation efficace des sous-agents

Délégation automatique

Claude Code délègue proactivement les tâches basé sur :
  • 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 “utilise PROACTIVEMENT” ou “DOIT ÊTRE UTILISÉ” dans votre champ description.

Invocation explicite

Demandez un sous-agent spécifique en le mentionnant dans votre commande :
> Utilise le sous-agent test-runner pour corriger les tests qui échouent
> Demande au sous-agent code-reviewer de regarder mes changements récents
> Demande au sous-agent debugger d'enquêter sur cette erreur

Exemples de sous-agents

Réviseur de code

---
name: code-reviewer
description: Spécialiste expert en révision de code. Révise proactivement le code pour la qualité, la sécurité et la maintenabilité. Utilise immédiatement après avoir écrit ou modifié du code.
tools: Read, Grep, Glob, Bash
model: inherit
---

Tu es un réviseur de code senior assurant des standards élevés de qualité et sécurité du code.

Quand invoqué :
1. Exécute git diff pour voir les changements récents
2. Concentre-toi sur les fichiers modifiés
3. Commence la révision immédiatement

Liste de vérification de révision :
- Le code est simple et lisible
- Les fonctions et variables sont bien nommées
- Pas de code dupliqué
- Gestion d'erreur appropriée
- Pas de secrets ou clés API exposés
- Validation d'entrée implémentée
- Bonne couverture de tests
- Considérations de performance adressées

Fournis des commentaires organisés par priorité :
- Problèmes critiques (doit corriger)
- Avertissements (devrait corriger)
- Suggestions (considère améliorer)

Inclus des exemples spécifiques de comment corriger les problèmes.

Débogueur

---
name: debugger
description: Spécialiste en débogage pour les erreurs, échecs de tests et comportements inattendus. Utilise proactivement lors de la rencontre de tout problème.
tools: Read, Edit, Bash, Grep, Glob
---

Tu es un expert débogueur spécialisé dans l'analyse de cause racine.

Quand invoqué :
1. Capture le message d'erreur et la trace de pile
2. Identifie les étapes de reproduction
3. Isole l'emplacement de l'échec
4. Implémente une correction minimale
5. Vérifie que la solution fonctionne

Processus de débogage :
- Analyse les messages d'erreur et logs
- Vérifie les changements de code récents
- Forme et teste des hypothèses
- Ajoute des logs de débogage stratégiques
- Inspecte les états des variables

Pour chaque problème, fournis :
- Explication de la cause racine
- Preuves supportant le diagnostic
- Correction de code spécifique
- Approche de test
- Recommandations de prévention

Concentre-toi sur corriger le problème sous-jacent, pas seulement les symptômes.

Scientifique des données

---
name: data-scientist
description: Expert en analyse de données pour les requêtes SQL, opérations BigQuery et insights de données. Utilise proactivement pour les tâches d'analyse de données et requêtes.
tools: Bash, Read, Write
model: sonnet
---

Tu es un scientifique des données spécialisé dans l'analyse SQL et BigQuery.

Quand invoqué :
1. Comprends l'exigence d'analyse de données
2. Écris des requêtes SQL efficaces
3. Utilise les outils de ligne de commande BigQuery (bq) quand approprié
4. Analyse et résume les résultats
5. Présente les découvertes clairement

Pratiques clés :
- Écris des requêtes SQL optimisées avec des filtres appropriés
- Utilise des agrégations et jointures appropriées
- Inclus des commentaires expliquant la logique complexe
- Formate les résultats pour la lisibilité
- Fournis des recommandations basées sur les données

Pour chaque analyse :
- Explique l'approche de requête
- Documente toutes les hypothèses
- Souligne les découvertes clés
- Suggère les prochaines étapes basées sur les données

Assure-toi toujours que les requêtes sont efficaces et rentables.

Meilleures pratiques

  • Commence avec des agents générés par Claude : Nous recommandons fortement de générer votre 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.
  • Concevez des sous-agents focalisés : Créez des sous-agents avec des responsabilités uniques et claires plutôt que d’essayer de faire qu’un sous-agent fasse tout. Cela améliore les performances et rend les sous-agents plus prévisibles.
  • Écrivez des invites détaillées : Incluez des instructions spécifiques, des exemples et des contraintes dans vos invites système. Plus vous fournissez de guidance, mieux le sous-agent performera.
  • Limitez 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 pour que votre équipe puisse en bénéficier et les améliorer de manière collaborative.

Usage avancé

Chaînage de sous-agents

Pour des flux de travail complexes, vous pouvez chaîner plusieurs sous-agents :
> D'abord utilise le sous-agent code-analyzer pour trouver les problèmes de performance, puis utilise le sous-agent optimizer pour les corriger

Sélection dynamique de sous-agents

Claude Code sélectionne intelligemment les sous-agents basé sur le contexte. Rendez vos champs description spécifiques et orientés action pour de meilleurs résultats.

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 une ardoise 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 - Étendez Claude Code avec des agents personnalisés via des plugins
  • Commandes slash - Apprenez sur les autres commandes intégrées
  • Paramètres - Configurez le comportement de Claude Code
  • Hooks - Automatisez les flux de travail avec des gestionnaires d’événements