Claude Code Sub-Agents : Guide Pratique pour Créer votre Équipe IA Spécialisée

Sommaire

---

Qu'est-ce qu'un sub-agent Claude Code ? {#introduction}

Un sub-agent est un agent enfant que Claude Code peut invoquer pour déléguer une tâche spécifique. Chaque sub-agent s'exécute dans son propre contexte isolé, avec son propre prompt système, ses outils autorisés et ses permissions indépendantes.

Pensez-y comme une équipe de spécialistes à la demande. Votre session Claude Code principale agit comme un chef de projet qui délègue les tâches au bon expert :

Pourquoi utiliser des sub-agents ?

Les sub-agents résolvent plusieurs problèmes concrets :

Si vous débutez avec Claude Code, consultez d'abord notre [guide complet](/blog/claude-code-guide-complet) pour maîtriser les bases avant de plonger dans les sub-agents.

---

Sub-agents vs Agent Teams : quelle différence ? {#difference}

Il est important de ne pas confondre les sub-agents avec les [Agent Teams](/blog/claude-code-agent-teams). Voici les distinctions clés :

En résumé : les sub-agents sont pour les micro-tâches spécialisées, les Agent Teams pour les projets de grande envergure.

---

Créer votre premier sub-agent {#premier-sub-agent}

Structure d'un fichier sub-agent

Les sub-agents se configurent dans des fichiers Markdown avec un frontmatter YAML. Vous pouvez les placer à deux niveaux :

\\\`markdown --- name: security-auditor description: Audite le code pour les vulnérabilités de sécurité model: claude-sonnet-4-6 tools:

---

Tu es un auditeur de sécurité spécialisé. Analyse le code source pour identifier les vulnérabilités OWASP Top 10.

Concentre-toi sur :

Fournis un rapport structuré avec :

\\\`

Invoquer le sub-agent

Une fois créé, Claude Code peut appeler votre sub-agent automatiquement quand le contexte le demande, ou vous pouvez le déclencher explicitement :

\\\`bash # Claude Code détecte et utilise les sub-agents disponibles # Exemple : demander un audit de sécurité claude "Fais un audit de sécurité du dossier src/api/"

# Claude va automatiquement déléguer au sub-agent security-auditor \\\`

---

Configuration avancée des sub-agents {#configuration}

Frontmatter complet

\\\`yaml --- name: test-writer description: Écrit des tests unitaires et d'intégration model: claude-sonnet-4-6 # Modèle à utiliser tools: # Outils autorisés

allowed_commands: # Commandes bash autorisées

--- \\\`

Prompt système efficace

Le prompt système de votre sub-agent doit être focalisé et concis. Évitez les instructions génériques et concentrez-vous sur le domaine d'expertise :

\\\`markdown Tu es un expert en tests unitaires JavaScript/TypeScript.

Règles :

\\\`

---

Routing de modèles : optimiser les coûts {#routing}

L'un des avantages les plus puissants des sub-agents est le routing de modèles. Vous pouvez diriger chaque tâche vers le modèle le plus adapté :

Stratégie de routing recommandée

Exemple concret de routing

\\\`markdown # .claude/agents/quick-formatter.md --- name: quick-formatter description: Formate et lint le code rapidement model: claude-haiku-4-5 tools:

allowed_commands:

---

Formate le code selon les conventions du projet. Utilise Prettier et ESLint si configurés. Corrige les erreurs de lint automatiquement. \\\`

En utilisant Haiku pour le formatage au lieu d'Opus, vous réduisez les coûts d'environ 90% sur ces tâches tout en maintenant une qualité équivalente.

Pour aller plus loin sur l'optimisation, consultez notre article sur les [meilleures pratiques Claude Code](/blog/meilleures-pratiques-claude-code).

---

Permissions et sécurité des sub-agents {#permissions}

Les sub-agents héritent des permissions de la session parente, mais vous pouvez les restreindre pour renforcer la sécurité.

Principe du moindre privilège

\\\`markdown # Sub-agent lecture seule pour l'analyse --- name: code-analyzer description: Analyse le code sans le modifier model: claude-sonnet-4-6 tools:

---

Analyse le code et fournis un rapport. Tu n'as PAS la permission de modifier les fichiers. \\\`

Restreindre les commandes bash

\\\`yaml allowed_commands:

# rm, git push, etc. sont implicitement interdits \\\`

Bonnes pratiques de sécurité

Pour approfondir les questions de sécurité, consultez notre article sur la [sécurité des assistants IA pour le code](/blog/securite-assistants-ia-code-2026).

---

Patterns d'architecture multi-agents {#patterns}

Pattern 1 : Pipeline séquentiel

Le sub-agent A produit un résultat qui alimente le sub-agent B :

\\\ Développeur → Sub-agent Tests → Sub-agent Review → Résultat final \\\

Exemple : écrire des tests puis les faire reviewer automatiquement.

Pattern 2 : Fan-out / Fan-in

Plusieurs sub-agents travaillent en parallèle sur différents aspects :

\\\ ┌→ Sub-agent Sécurité ──┐ Développeur ──→ ├→ Sub-agent Tests ─────┼→ Rapport consolidé └→ Sub-agent Perf ──────┘ \\\

Pattern 3 : Spécialiste à la demande

Le sub-agent est invoqué uniquement quand une expertise spécifique est nécessaire :

\\\ Développeur → Claude Code principal │ ├→ (détecte du SQL) → Sub-agent SQL Expert ├→ (détecte du CSS) → Sub-agent UI Expert └→ (détecte des tests) → Sub-agent Test Expert \\\

Ce pattern est particulièrement efficace avec les [hooks Claude Code](/blog/claude-code-hooks-automatiser-workflow) pour déclencher automatiquement le bon sub-agent.

---

Sub-agents utilisateur vs projet {#scope}

Sub-agents utilisateur (\`~/.claude/agents/\`)

Disponibles dans tous vos projets. Idéal pour :

Sub-agents projet (\`.claude/agents/\`)

Partagés avec toute l'équipe via Git. Idéal pour :

\\\bash # Structure recommandée .claude/ ├── agents/ │ ├── security-auditor.md │ ├── test-writer.md │ ├── doc-generator.md │ └── code-reviewer.md ├── settings.json └── CLAUDE.md \\\

---

Exemples concrets de sub-agents spécialisés {#exemples}

Sub-agent Review de PR

\\\`markdown --- name: pr-reviewer description: Review approfondi des pull requests model: claude-sonnet-4-6 tools:

allowed_commands:

---

Tu es un reviewer de code senior. Analyse les changements avec un œil critique.

Checklist de review :

Ton de la review : constructif et spécifique. Propose des alternatives concrètes. \\\`

Sub-agent Migration de Base de Données

\\\`markdown --- name: db-migration-checker description: Vérifie la sécurité des migrations de base de données model: claude-opus-4-7 tools:

---

Tu es un DBA expert. Analyse les migrations pour détecter :

Classe chaque problème : BLOQUANT / AVERTISSEMENT / INFO \\\`

Sub-agent Optimisation de Performance

\\\`markdown --- name: perf-analyzer description: Détecte les problèmes de performance dans le code model: claude-sonnet-4-6 tools:

allowed_commands:

---

Tu es un expert en performance web. Identifie :

Fournis des métriques avant/après quand possible. \\\`

---

Debugging et monitoring des sub-agents {#debugging}

Problèmes courants

Le sub-agent ne se déclenche pas :

Le sub-agent est trop lent :

Le sub-agent produit des résultats incohérents :

Optimisation des coûts

Anthropic a récemment corrigé un bug où les résumés des sub-agents continuaient à se déclencher même quand le transcript du sub-agent était statique, réduisant les coûts de cache de \cache_creation\ d'environ 3x.

Pour surveiller l'utilisation de vos sub-agents, consultez notre guide sur les [analytics et métriques Claude Code](/blog/claude-code-analytics-api-metriques-equipe).

---

FAQ {#faq}

Combien de sub-agents puis-je créer ?

Il n'y a pas de limite technique au nombre de sub-agents. Cependant, un nombre trop élevé peut rendre le routage ambigu. Visez 5 à 10 sub-agents bien définis par projet.

Les sub-agents peuvent-ils appeler d'autres sub-agents ?

Non, les sub-agents ne peuvent pas invoquer d'autres sub-agents. C'est une limitation intentionnelle pour éviter les boucles infinies et maintenir la traçabilité. Seul l'agent principal peut orchestrer les appels.

Un sub-agent peut-il modifier les fichiers du projet ?

Oui, si vous lui donnez les outils Write et Edit dans sa configuration. Mais appliquez le principe du moindre privilège : ne donnez l'accès en écriture qu'aux sub-agents qui en ont réellement besoin.

Comment partager mes sub-agents avec l'équipe ?

Placez-les dans \.claude/agents/\ à la racine du projet et commitez-les dans Git. Toute l'équipe y aura accès automatiquement.

Les sub-agents consomment-ils mes quotas ?

Oui, chaque appel à un sub-agent consomme des tokens de votre plan. C'est pourquoi le routing de modèles est important : utilisez Haiku pour les tâches simples afin de préserver vos quotas pour les tâches complexes.

Quelle est la différence avec les Skills ?

Les [Skills](/blog/claude-code-skills-creer-commandes-personnalisees) sont des commandes personnalisées invoquées explicitement avec \/nom-skill\. Les sub-agents sont invoqués automatiquement par Claude Code quand le contexte le demande, ou via l'outil Agent dans le code.

---

*Sources : Anthropic Claude Code Documentation, Claude Code Changelog, Anthropic Engineering Blog.*