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 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. 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 :

---
name: security-auditor
description: Audite le code pour les vulnérabilités de sécurité
model: claude-sonnet-4-6
tools:
  - Read
  - Bash
  - Grep
  - Glob
---

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 :
- Injection SQL et NoSQL
- XSS (Cross-Site Scripting)
- CSRF (Cross-Site Request Forgery)
- Gestion des secrets et credentials
- Validation des entrées utilisateur

Fournis un rapport structuré avec :
1. Sévérité (Critique / Haute / Moyenne / Basse)
2. Fichier et ligne concernés
3. Description de la vulnérabilité
4. Correctif recommandé

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 :

# 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

---
name: test-writer
description: Écrit des tests unitaires et d'intégration
model: claude-sonnet-4-6      # Modèle à utiliser
tools:                          # Outils autorisés
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
allowed_commands:               # Commandes bash autorisées
  - "npx jest"
  - "npx vitest"
  - "npm test"
---

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 :

Tu es un expert en tests unitaires JavaScript/TypeScript.

Règles :
- Utilise le framework de test déjà configuré dans le projet
- Couvre les cas nominaux ET les cas d'erreur
- Préfère les assertions explicites aux snapshots
- Nomme les tests avec le pattern "should [expected behavior] when [condition]"
- Mock les dépendances externes, jamais la base de données
- Vise un coverage de branche > 80%

---

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

# .claude/agents/quick-formatter.md
---
name: quick-formatter
description: Formate et lint le code rapidement
model: claude-haiku-4-5
tools:
  - Read
  - Edit
  - Bash
allowed_commands:
  - "npx prettier"
  - "npx eslint"
---

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.

---

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

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

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

Restreindre les commandes bash

allowed_commands:
  - "npm test"           # Autorisé
  - "npx jest"           # Autorisé
  # 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.

---

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 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 :

# 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

---
name: pr-reviewer
description: Review approfondi des pull requests
model: claude-sonnet-4-6
tools:
  - Read
  - Bash
  - Glob
  - Grep
allowed_commands:
  - "git diff"
  - "git log"
  - "git show"
---

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

Checklist de review :
- [ ] Logique métier correcte
- [ ] Gestion des erreurs appropriée
- [ ] Tests suffisants
- [ ] Pas de régression de performance
- [ ] Nommage clair et cohérent
- [ ] Pas de code mort ou commenté
- [ ] Documentation mise à jour si nécessaire

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

Sub-agent Migration de Base de Données

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

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

- Migrations irréversibles sans rollback
- Locks de tables en production (ALTER TABLE sur tables volumineuses)
- Perte de données potentielle (DROP COLUMN sans backup)
- Index manquants sur les nouvelles colonnes de requête
- Incohérences entre le schéma et les modèles ORM

Classe chaque problème : BLOQUANT / AVERTISSEMENT / INFO

Sub-agent Optimisation de Performance

---
name: perf-analyzer
description: Détecte les problèmes de performance dans le code
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
allowed_commands:
  - "npx lighthouse"
  - "npm run build"
---

Tu es un expert en performance web. Identifie :

- Requêtes N+1 dans les API
- Re-renders inutiles dans React
- Bundles JavaScript surdimensionnés
- Images non optimisées
- Requêtes bloquantes
- Mémoire non libérée (event listeners, intervals)

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.

---

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 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.*