Sous-Agents Claude Code : Orchestrer des Tâches Complexes 2026

Table des Matières

• →Que Sont les Sous-Agents ?
• →Pourquoi Utiliser des Sous-Agents ?
• →Types d'Agents et Permissions
• →Lancer des Sous-Agents
• →Modèles d'Orchestration
• →Exemples Concrets
• →Dépannage
• →Articles Connexes
• →Points Clés à Retenir

Que Sont les Sous-Agents ?

Les sous-agents sont des instances Claude isolées lancées depuis votre session principale. Chaque sous-agent :

• →Possède sa propre fenêtre de contexte
• →Exécute des outils spécifiques avec des permissions spécifiques
• →Rapporte à l'agent orchestrateur
• →Peut travailler en parallèle avec d'autres sous-agents

Architecture des Sous-Agents :

Agent Principal ("Refactoriser l'authentification dans toute la base de code")

↓ Lance des agents en parallèle ↓

• →Agent Explore → Analyse src/
• →Agent Explore → Analyse lib/
• →Agent Explore → Analyse tests/

↓ Les résultats remontent ↓

Agent Principal synthétise les conclusions

Pourquoi Utiliser des Sous-Agents ?

Sans Sous-Agents

Les tâches volumineuses consomment rapidement votre contexte :

> Analyse tous les composants React pour les problèmes d'accessibilité

Analyse de src/components/Button.tsx...
Analyse de src/components/Modal.tsx...
Analyse de src/components/Form.tsx...
[... 50 fichiers de plus ...]

⚠️ Limite de contexte approchant. Certains fichiers pourraient être tronqués.

Avec des Sous-Agents

Répartissez le travail entre des contextes isolés :

> Analyse tous les composants React pour les problèmes d'accessibilité

Lancement des sous-agents :
- Agent 1 : Analyse de src/components/ui/*
- Agent 2 : Analyse de src/components/forms/*
- Agent 3 : Analyse de src/components/layout/*

[Agents en cours de travail...]

Tous les agents terminés. Synthèse des conclusions :
12 problèmes d'accessibilité trouvés dans 47 composants.

Chaque agent dispose du contexte complet pour sa portion de travail.

Types d'Agents Intégrés

Claude Code inclut plusieurs agents intégrés :

Agent Explore

Exploration rapide en lecture seule de la base de code :

> Utilise l'agent Explore pour comprendre le système d'authentification

[Agent Explore]
Analyse de l'authentification...

Résumé du Système d'Auth :
- Authentification JWT dans src/auth/
- Gestion des sessions dans src/session/
- Fournisseurs OAuth dans src/auth/providers/
- Middleware : src/middleware/auth.ts

Fichiers clés :
- src/auth/jwt.ts (génération de tokens)
- src/auth/verify.ts (validation de tokens)
- src/middleware/auth.ts (protection des routes)

[Agent terminé]

Explore est en lecture seule — il ne peut pas modifier de fichiers, réduisant les risques lors de l'exploration autonome.

Agent Plan

Orienté architecture et planification :

> Utilise l'agent Plan pour concevoir une couche de cache

[Agent Plan]
Conception de la solution de cache...

Architecture Recommandée :
1. Couche de Cache : Redis pour le cache distribué
2. Clés de Cache : Basées sur endpoint + hash des paramètres
3. Stratégie TTL : 5min pour les listes, 1h pour le statique
4. Invalidation : Événementielle via file de messages

Étapes d'Implémentation :
1. Configurer la connexion Redis (src/cache/client.ts)
2. Créer le middleware de cache (src/middleware/cache.ts)
3. Ajouter des décorateurs de cache pour les services
4. Implémenter les gestionnaires d'invalidation

[Agent terminé]

Plan se concentre sur l'analyse et la conception sans faire de modifications.

Agent Général

L'agent par défaut avec des capacités complètes :

> Crée un sous-agent pour implémenter la fonctionnalité de profil utilisateur

[Agent Général]
Implémentation du profil utilisateur...

Créé :
- src/components/UserProfile.tsx
- src/api/profile.ts
- src/types/profile.ts
- tests/profile.test.ts

[Agent terminé]

Les agents généraux peuvent lire, écrire et exécuter des commandes.

Gestion des Agents

Voir les Agents Disponibles

> /agents

Menu interactif :

Agents Disponibles :

Intégrés :
  [1] explore - Exploration rapide en lecture seule
  [2] plan - Architecture et planification
  [3] general-purpose - Capacités complètes

Personnalisés :
  [4] security-audit - Analyse orientée sécurité
  [5] docs-generator - Création de documentation

[c] Créer un agent  [e] Modifier un agent  [d] Supprimer un agent
[Esc] Quitter

Créer un Agent Personnalisé

Définissez des agents spécialisés pour votre workflow :

> /agents
[c] Créer un agent

Nom : security-audit
Description : Analyse de code orientée sécurité
Outils autorisés : Read, grep_search, semantic_search
Prompt système : Tu es un expert en sécurité. Analyse le code pour détecter
les vulnérabilités, secrets exposés, risques d'injection et bonnes pratiques
de sécurité. Sois minutieux et rapporte toutes les conclusions avec des
niveaux de sévérité.

Lancer des Sous-Agents

En Conversation

Demandez à Claude de lancer des agents naturellement :

> Utilise des sous-agents pour analyser chaque module en parallèle

Lancement des agents pour chaque module :
- Module 1 : src/auth (agent Explore)
- Module 2 : src/api (agent Explore)
- Module 3 : src/components (agent Explore)
- Module 4 : src/utils (agent Explore)

[Tous les agents en cours de travail...]

Demande Explicite d'Agent

Spécifiez quel type d'agent utiliser :

> Demande à l'agent Explore de cartographier toutes les requêtes base de données dans la base de code

[Agent Explore]
Cartographie des requêtes base de données...

Exécution Parallèle

> Exécute ces tâches en parallèle avec des sous-agents :
  1. Trouver tous les commentaires TODO
  2. Vérifier l'utilisation d'API dépréciées
  3. Identifier les exports inutilisés

Lancement de 3 agents parallèles...

Agent 1 (TODO) : 23 commentaires TODO trouvés
Agent 2 (Dépréciés) : 5 appels d'API dépréciés trouvés
Agent 3 (Inutilisés) : 12 exports inutilisés trouvés

Tous les agents terminés.

Configuration des Agents

Définition d'Agent Personnalisé

Créez des agents dans les paramètres :

// .claude/settings.json
{
  "agents": {
    "security-scan": {
      "description": "Scanner de vulnérabilités de sécurité",
      "model": "claude-sonnet",
      "allowedTools": ["Read", "grep_search", "Bash(grep:*)"],
      "systemPrompt": "Tu es un expert en sécurité. Recherche les vulnérabilités, identifiants exposés et anti-modèles de sécurité."
    },
    "docs-writer": {
      "description": "Générateur de documentation",
      "model": "claude-sonnet",
      "allowedTools": ["Read", "Write(docs/**)"],
      "systemPrompt": "Tu es un rédacteur technique. Génère une documentation claire et complète."
    },
    "test-creator": {
      "description": "Spécialiste de la génération de tests",
      "model": "claude-sonnet",
      "allowedTools": ["Read", "Write(**/*.test.*)", "Bash(npm:test)"],
      "systemPrompt": "Tu es un expert en tests. Crée des suites de tests complètes avec une bonne couverture."
    }
  }
}

Propriétés des Agents

Communication des Sous-Agents

Agrégation des Résultats

Les sous-agents rapportent à l'agent principal :

Principal : Analysez chaque microservice pour les incohérences d'API

Sous-agent 1 (user-service) :
  - 3 formats de réponse incohérents
  - Codes d'erreur manquants sur 2 endpoints

Sous-agent 2 (order-service) :
  - Modèles cohérents ✓
  - 1 endpoint déprécié utilisé

Sous-agent 3 (payment-service) :
  - 2 formats de date incohérents
  - Codes de statut non standards

Principal : Synthèse des conclusions...

Passage de Contexte

L'agent principal fournit du contexte aux sous-agents :

Principal : Je dois refactoriser la gestion des erreurs. D'abord,
           lancez des agents Explore pour cartographier les modèles
           d'erreurs actuels dans chaque service.

Contexte transmis aux sous-agents :
- Le projet utilise TypeScript
- Modèles d'erreurs actuels à rechercher
- Format de rapport attendu

Les sous-agents reçoivent un contexte ciblé, pas toute la conversation.

Modèles Concrets

Modèle 1 : Exploration de Base de Code

Cartographier une grande base de code inconnue :

> Utilise des agents Explore pour comprendre la structure de cette base de code

[Lancement des agents Explore...]

Agent 1 : Architecture cœur (src/core)
Agent 2 : Couche API (src/api)
Agent 3 : Composants UI (src/components)
Agent 4 : Utilitaires (src/utils)
Agent 5 : Configuration (config, *.config.*)

[Synthèse...]

Vue d'Ensemble de la Base de Code :
- Framework : Next.js 14 avec App Router
- État : Zustand + React Query
- API : tRPC avec Prisma ORM
- Auth : NextAuth.js avec JWT
- Tests : Vitest + Playwright

Modèles architecturaux clés :
- Structure de dossiers par fonctionnalité
- Séparation composants serveur/client
- Gestion des erreurs centralisée dans src/core/errors

Modèle 2 : Refactoring Parallèle

Refactoriser plusieurs fichiers simultanément :

> Refactorise toutes les routes API pour utiliser le nouveau modèle de gestion d'erreurs

[Création des agents de refactoring...]

Agent 1 : src/api/users/* (5 fichiers)
Agent 2 : src/api/products/* (8 fichiers)
Agent 3 : src/api/orders/* (6 fichiers)
Agent 4 : src/api/auth/* (4 fichiers)

[Agents en cours de travail en parallèle...]

Progression :
- Agent 1 : ████████░░ 80% (4/5 fichiers)
- Agent 2 : ██████░░░░ 60% (5/8 fichiers)
- Agent 3 : ████████░░ 67% (4/6 fichiers)
- Agent 4 : ██████████ 100% (4/4 fichiers)

[Tous les agents terminés]

Résumé :
- 23 fichiers refactorisés
- 89 gestionnaires d'erreurs mis à jour
- 12 définitions de types ajoutées

Modèle 3 : Génération de Tests

Générer des tests sur toute la base de code :

> Crée des tests complets pour tous les services

[Lancement des agents test-creator...]

Agent 1 : Tests UserService
Agent 2 : Tests OrderService
Agent 3 : Tests PaymentService
Agent 4 : Tests NotificationService

[Agents en cours de travail...]

Fichiers de tests créés :
- tests/services/user.test.ts (15 tests)
- tests/services/order.test.ts (22 tests)
- tests/services/payment.test.ts (18 tests)
- tests/services/notification.test.ts (12 tests)

Total : 67 tests couvrant 94% des méthodes de service

Modèle 4 : Sprint de Documentation

Générer des docs en parallèle :

> Documente toutes les API publiques avec des agents docs-writer

[Lancement des agents docs-writer...]

Agent 1 : Documentation API REST
Agent 2 : Documentation schéma GraphQL
Agent 3 : Référence SDK
Agent 4 : Guide de démarrage

[Agents en cours de travail...]

Généré :
- docs/api/rest.md (45 endpoints)
- docs/api/graphql.md (schéma complet)
- docs/sdk/reference.md (toutes les méthodes publiques)
- docs/getting-started.md (guide de démarrage rapide)

Modèle 5 : Audit de Sécurité

Scan de sécurité complet :

> Lance un audit de sécurité avec des agents security-scan

[Lancement des agents security-scan...]

Agent 1 : Vulnérabilités des dépendances
Agent 2 : Modèles de sécurité du code
Agent 3 : Revue de configuration
Agent 4 : Audit d'authentification

[Scan en cours...]

Rapport de Sécurité :

CRITIQUE (2) :
- Clé API exposée dans src/config/legacy.ts
- Risque d'injection SQL dans src/api/search.ts

HAUTE (5) :
- 3 paquets npm avec des vulnérabilités connues
- Limitation de débit manquante sur les endpoints d'auth
- Validation de mot de passe faible

MOYENNE (12) :
- Diverses failles de prévention XSS
- Tokens CSRF manquants
- CORS trop permissif

Rapport complet : .claude/reports/security-audit.md

Limites et Bonnes Pratiques des Agents

Gestion du Contexte

Chaque sous-agent a sa propre limite de contexte :

• →Agent principal : 200k tokens
• →Sous-agent 1 : 200k tokens (isolé)
• →Sous-agent 2 : 200k tokens (isolé)
• →Sous-agent 3 : 200k tokens (isolé)

Contexte effectif total : 800k tokens pour la même tâche.

Bonnes Pratiques

1. Délimitez les agents précisément

# Bien : Périmètre spécifique
"Analyse les fichiers d'authentification dans src/auth"

# Mauvais : Trop large
"Analyse tout dans src"

2. Utilisez les types d'agents appropriés

# Tâche en lecture seule → Agent Explore
# Tâche de planification → Agent Plan
# Implémentation → Agent Général

3. Limitez les agents parallèles

# Bien : 3-5 agents parallèles
# Risqué : 20 agents parallèles (plus difficile à coordonner)

4. Fournissez des livrables clairs

"Rapportez avec :
- Liste des problèmes trouvés
- Sévérité pour chacun
- Fichier et numéro de ligne
- Correctif suggéré"

5. Validez les résultats des agents

L'agent principal devrait vérifier les résultats des sous-agents
avant d'agir sur leur base.

Agents en Automatisation

Lancement d'Agents en Mode Headless

Dans les scripts automatisés :

claude --print -p "Utilise des agents Explore pour cartographier la structure de la base de code"

Intégration CI/CD

# .github/workflows/analysis.yml
- name: Exécuter l'analyse parallèle
  run: |
    claude --dangerously-skip-permissions -p \
      "Utilise des sous-agents pour analyser : 1) couverture de tests 2) sécurité des types 3) problèmes de lint"

Voir Claude Code GitHub Actions : Automatisation CI/CD Propulsée par l'IA.

Utilisation SDK

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 8096,
  messages: [{
    role: "user",
    content: "Utilise des sous-agents pour analyser chaque module en parallèle"
  }]
});

Voir Claude Code Headless et Programmatique : SDK et Automatisation.

Intégration avec d'Autres Fonctionnalités

Agents + Hooks

Les hooks s'appliquent aussi aux actions des sous-agents :

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "command": "python .claude/hooks/validate.py"
    }]
  }
}

Tous les appels d'outils des sous-agents passent par vos hooks.

Voir Claude Code Hooks : Automatisez Votre Workflow de Développement.

Agents + MCP

Les sous-agents peuvent utiliser les outils MCP :

{
  "agents": {
    "github-helper": {
      "allowedTools": ["mcp__github__*", "Read"],
      "systemPrompt": "Tu aides avec les opérations GitHub."
    }
  }
}

Voir Model Context Protocol (MCP) pour Claude Code : Guide Complet.

Agents + Commandes Personnalisées

Les commandes peuvent spécifier l'utilisation d'agents :

<!-- .claude/commands/audit.md -->
---
description: Audit complet de la base de code
---

Lance un audit complet avec des sous-agents :

1. Lance des agents Explore pour cartographier la base de code
2. Lance des agents security-scan pour les vulnérabilités
3. Lance un agent Plan pour prioriser les conclusions
4. Synthétise en un rapport final

Voir Commandes Slash Personnalisées dans Claude Code : Créez les Vôtres.

Débogage des Agents

Mode Verbose

claude --verbose

Affiche le cycle de vie des agents :

[AGENT] Lancement de l'agent Explore pour src/auth
[AGENT] Contexte : 2 340 tokens
[AGENT] Outils : Read, grep_search
[AGENT] Démarré : abc123
[AGENT] abc123 : Lecture de src/auth/jwt.ts
[AGENT] abc123 : Terminé (4.2s)
[AGENT] Résultat : 1 200 tokens

Journaux des Agents

Les sous-agents écrivent dans les journaux de session :

> /export

Session exportée avec :
- Conversation de l'agent principal
- Transcriptions des sous-agents
- Historique d'exécution des outils

Problèmes Courants

Agent bloqué :

• →Vérifiez les boucles infinies dans la tâche
• →Vérifiez les permissions des outils
• →Essayez un périmètre plus réduit

Résultats incohérents :

• →Ajoutez des instructions plus spécifiques
• →Utilisez une temperature plus basse
• →Vérifiez que le contexte est correctement transmis

Dépassement de contexte :

• →Réduisez le périmètre par agent
• →Utilisez plus d'agents avec des portions plus petites
• →Activez la compaction

Articles Connexes

Approfondissez vos connaissances sur les agents Claude Code :

• →Claude Code GitHub Actions - Automatisez les workflows avec une CI/CD propulsée par l'IA
• →Claude Code SDK Mode Headless - Modèles d'automatisation programmatique
• →Installation et Configuration de Claude Code - Démarrez avec la configuration
• →Référence des Commandes Slash Claude Code - Guide complet des commandes
• →Claude Code vs Copilot vs Cursor 2026 - Comparaison des fonctionnalités

Points Clés à Retenir

1. →

   Diviser pour mieux régner : Les sous-agents permettent de s'attaquer aux grandes tâches en répartissant le travail.

2. →

   Choisissez le bon agent : Explore pour la lecture, Plan pour la conception, General pour les modifications.

3. →

   Contextes isolés : Chaque sous-agent possède sa propre fenêtre de contexte.

4. →

   Exécution parallèle : Plusieurs agents peuvent travailler simultanément.

5. →

   Contrôle par les permissions : Limitez ce que chaque type d'agent peut faire.

Maîtrisez l'Orchestration d'Agents

Les sous-agents sont puissants, mais les orchestrer efficacement nécessite de comprendre les modèles d'agents et les flux de contrôle.

Dans notre Module 6 — Agents Autonomes, vous apprendrez :

• →Fondamentaux de l'architecture d'agents
• →Modèles d'orchestration
• →Gestion des erreurs et récupération
• →Construction de workflows d'agents fiables

→ Explorer le Module 6 : Agents Autonomes

Dernière mise à jour : janvier 2026. Couvre les sous-agents Claude Code avec Claude Sonnet 4.5 et les dernières fonctionnalités d'orchestration multi-agents.