Module 10 — Sous-agents, agents en parallèle et équipes d'agents

Une conversation avec Claude Code est puissante tant qu'elle tient dans un contexte lisible. Passé un certain volume — audit de vingt-cinq fichiers, migration de trois cents composants —, on noie le fil principal, on épuise le budget de tokens. La solution n'est pas de « prompter plus fort », mais de déléguer. Claude Code offre quatre familles complémentaires : sous-agents, forks, équipes d'agents et workflows dynamiques.

Pourquoi et quand déléguer

Règle mnémonique : chaque nouveau sous-agent est un contexte neuf. Il ne voit pas votre historique, pas votre /clear, pas les fichiers déjà lus. Il reçoit son prompt système, un message de tâche, et les CLAUDE.md hérités.

L'intérêt est exact : cette isolation isole aussi le bruit. Un pytest -x -vv qui produit deux mille lignes de traces, une recherche Grep sur trois cents fichiers, une lecture de logs Kubernetes : tout reste dans le sous-agent, seule la synthèse remonte. Le contrepoint est la latence : un sous-agent démarre à froid.

Approche	Ce que vous obtenez	Quand l'utiliser
Sous-agents	Travailleurs délégués dans une seule session, contexte isolé, renvoient une synthèse	Une tâche noierait le fil principal (logs, recherche, sortie de tests)
Vue « agent view »	Un écran qui dispatche et surveille des sessions en tâche de fond (claude agents)	Plusieurs tâches indépendantes à lancer et à surveiller
Équipes d'agents	Sessions coordonnées, liste de tâches partagée, messagerie inter-agents. Expérimental, désactivé par défaut	Claude découpe un projet, assigne les morceaux, synchronise les ouvriers
Workflows dynamiques	Un script Claude orchestre de nombreux sous-agents et croise leurs résultats	Audit de dépôt entier, migration de plusieurs centaines de fichiers, recherche à sources croisées

Trois outils viennent en support sans être eux-mêmes des façons d'exécuter des agents : les worktrees (chaque session dans un checkout git séparé, plus de conflits d'édition), la messagerie inter-sessions pour se passer des trouvailles, et la commande /batch qui empile sous-agents et worktrees dans un même geste.

Sous-agents : les blocs de base

Un sous-agent personnalisé est un fichier Markdown avec en-tête YAML dans .claude/agents/ (projet, versionné) ou ~/.claude/agents/ (utilisateur). Claude Code surveille ces dossiers et recharge en quelques secondes ; redémarrage nécessaire pour la première création dans un scope. Seuls name et description sont obligatoires.

Champs de frontmatter documentés :

Champ	Rôle
name	Identifiant unique en minuscules et tirets ; : interdit (réservé aux plugins)
description	Quand Claude doit déléguer
tools / disallowedTools	Liste blanche / liste noire d'outils (denylist appliquée en premier)
model	sonnet, opus, haiku, fable, ID complet, ou inherit
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan
maxTurns	Tours avant arrêt ; la sortie est marquée partielle
skills / mcpServers / hooks	Ressources scopées à ce sous-agent
memory	user, project, ou local (mémoire persistante)
background	true pour rester en fond
isolation	worktree pour un checkout git séparé
color / initialPrompt	Affichage, premier message auto-envoyé avec --agent

Trois invocations. Langage naturel : « utilise le sous-agent revieweur ». @-mention : @"revieweur (agent)" force l'appel. Session entière : claude --agent revieweur remplace le prompt système pour toute la session.

Un sous-agent qui a produit une sortie peut être relancé : Claude appelle SendMessage avec l'ID ou le nom. Les transcripts vivent dans ~/.claude/projects/{project}/{sessionId}/subagents/agent-{id}.jsonl et survivent à un /compact.

Sous-agents intégrés

Trois sous-agents intégrés existent sans déclaration : Explore (reconnaissance de code, lecture seule), Plan (préparation d'un plan avant édition), general-purpose (tâches sans définition précise). Explore et Plan sont one-shot : sans ID, non reprenables.

Limites de concurrence et de profondeur

Deux variables gouvernent la spéculation. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS fixe le nombre de sous-agents simultanés par session — 20 par défaut ; au-delà, l'outil Agent refuse avec Concurrent subagent limit reached. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH contrôle l'imbrication : 3 par défaut. À la profondeur maximale, l'outil Agent est retiré du sous-agent. Mettre 1 désactive l'imbrication.

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "8",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Forks : la conversation entière, en parallèle

Un fork est un sous-agent particulier : il hérite du prompt système, des outils, du modèle et de tout l'historique de la conversation principale. Aucun redécorage. On l'utilise pour tenter une variante sans polluer le fil : rédiger des tests pendant qu'on code, essayer deux approches à partir du même point.

La commande dédiée est /subtask (Claude Code v2.1.212+, /fork avant) :

/subtask rédiger les tests unitaires du parseur avec les changements récents

Le fork tourne en tâche de fond, son résultat revient comme un message. Il ne peut pas engendrer d'autre fork, et son cache de prompt est partagé avec la conversation principale — c'est ce qui le rend bon marché. Le mode fork est actif par défaut en interactif ; il se règle via CLAUDE_CODE_FORK_SUBAGENT.

Commandes essentielles

• /tasks — vue des travaux en fond : sous-agents actifs et terminés, commandes shell. Entrée ouvre le transcript, x arrête ou nettoie.
• /list-agents (ou /peers) — liste les sous-agents, coéquipiers d'équipe et sessions Claude Code joignables, avec le nom exact pour la messagerie inter-session.
• /agents — attention au piège. Depuis la v2.1.198, cette commande n'ouvre plus d'éditeur : elle rappelle simplement où éditer (.claude/agents/ ou ~/.claude/agents/).
• /batch <instruction> — skill fournie qui étudie le dépôt, découpe la tâche en 5 à 30 unités indépendantes, présente un plan, puis lance un sous-agent par unité, chacun dans son worktree, chacun ouvrant sa PR. Idéal pour une migration massive.
• /workflows — suivi des workflows dynamiques : pause, reprise, sauvegarde.

Worktrees : l'isolation au niveau fichier

Un worktree est un répertoire git séparé, branché du dépôt principal, avec ses propres fichiers. Deux sessions dans deux worktrees ne se marchent jamais dessus :

claude --worktree feature-paiement

Le worktree est créé sous .claude/worktrees/feature-paiement/ sur une branche worktree-feature-paiement. À la sortie, Claude Code demande quoi faire s'il reste des changements. Pour qu'un sous-agent ait son propre checkout, il suffit d'ajouter isolation: worktree à sa frontmatter : Claude Code crée un worktree temporaire et le nettoie si aucun changement n'y est resté.

Un fichier .worktreeinclude (syntaxe .gitignore) copie automatiquement des fichiers gitignorés (typiquement .env) dans chaque nouveau worktree.

Équipes d'agents (expérimental)

Les équipes d'agents orchestrent plusieurs sessions Claude Code coordonnées par un lead. Expérimental, désactivé par défaut : activer via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans env. Une fois actif, il suffit de décrire la tâche : « lance trois coéquipiers pour explorer ce problème sous trois angles ». Le lead ouvre une liste de tâches partagée, spawne les coéquipiers, leur assigne le travail.

Deux modes d'affichage : in-process (même terminal, navigation flèches+Entrée) et split panes (chaque coéquipier dans un pane tmux ou iTerm2). Réglage via teammateMode dans settings.json ou --teammate-mode. Attention : les coéquipiers ne sont pas isolés en worktrees, il faut partitionner les fichiers.

Workflows dynamiques

Un workflow dynamique est un script écrit par Claude qui lance de nombreux sous-agents et croise leurs résultats. Il convient quand une poignée de sous-agents ne suffit plus : audit d'un dépôt entier, migration de 500 fichiers, recherche à sources croisées. Des workflows fournis (/deep-research) sont accessibles directement ; on peut aussi demander à Claude d'en écrire un, l'approuver via plan mode, puis le sauvegarder pour rejeu. Suivi via /workflows.

Kiosque : deux sous-agents complets

Pour Kiosque, Nadia code deux sous-agents projet, versionnés dans .claude/agents/. Le premier revoit le code, le second exécute la suite de tests dans un contexte isolé.

Sous-agent 1 — revieweur

Objectif : passer une revue post-modification en lecture seule et remonter une synthèse hiérarchisée. Aucun droit d'édition, aucun accès Write.

---
name: revieweur
description: Passe une revue de code sur les changements Python récents. Utiliser proactivement après une session de code.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
color: blue
---

Tu es un revieweur senior Python pour la base de code Kiosque.

Quand tu es invoqué :
1. Lance `git diff main...HEAD` pour identifier les changements.
2. Concentre-toi sur les fichiers `.py` modifiés.
3. Applique la checklist suivante et remonte une synthèse.

Checklist :
- Lisibilité, nommage, absence de code dupliqué.
- Gestion d'erreurs explicite (pas d'`except:` nu).
- Aucun secret en clair, aucune clé d'API commitée.
- Validation des entrées côté FastAPI.
- Couverture de tests suffisante pour le comportement modifié.
- Migrations Alembic générées si le schéma change.

Rapporte en trois sections :
- « Bloquants » : corriger avant merge.
- « À revoir » : améliorations recommandées.
- « Nits » : détails de style ou de goût.

Ne modifie aucun fichier.

Sous-agent 2 — testeur

Objectif : exécuter make test dans un worktree isolé (pour ne pas polluer le checkout principal si un test crée un fichier temporaire), et remonter uniquement les échecs.

---
name: testeur
description: Exécute la suite de tests Kiosque dans un worktree isolé et remonte uniquement les échecs avec leurs traces.
tools: Read, Bash, Grep
model: haiku
isolation: worktree
maxTurns: 10
color: green
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/annotate-tests.sh"
---

Tu es un exécuteur de tests pour Kiosque.

Quand tu es invoqué :
1. Vérifie que tu es bien dans un worktree (`git rev-parse --show-toplevel`).
2. Lance `make test` avec sortie complète.
3. Si tout passe : retourne « Suite verte : N tests, T secondes ».
4. Si un test échoue : extrais pour chaque échec le nom du test, le fichier, la ligne, la première ligne d'assertion, et 5 lignes de contexte de la trace.
5. Ne relance jamais la suite sur un test individuel sans y avoir été invité.
6. Ne modifie aucun code source, aucune migration.

Format de sortie en échec :
- Nombre de tests exécutés, nombre en échec.
- Liste des échecs (nom, chemin, extrait de trace).
- Aucun commentaire de « probable cause » : juste les faits.

Utilisation quotidienne

Karim tape @"revieweur (agent)" revois services/paiement/`` avant d'ouvrir une PR : le revieweur lit, ne touche à rien, remonte trois listes hiérarchisées. Léa lance @"testeur (agent)" exécute la suite complète pendant qu'elle continue à coder : le testeur tourne dans un worktree temporaire, seuls les échecs remontent. Pour un chantier plus large — passer tous les endpoints à Pydantic v2 —, Nadia lance /batch migre les endpoints de services/ vers Pydantic v2 : découpe en 20 unités, un sous-agent par module dans son worktree, une PR par unité.

Quand privilégier une équipe d'agents

Un revieweur + un testeur = deux sous-agents. Une équipe devient utile quand plusieurs humains virtuels doivent tenir une conversation entre eux (architecte, backend, frontend, chacun réagissant aux messages des autres). Pour un travail one-shot déléguable en boîte noire, restez sur des sous-agents.

En résumé

• Sous-agents : contexte isolé, retour synthétique, YAML dans .claude/agents/. Champs clés : name, description, tools, model, permissionMode, isolation, maxTurns, skills, hooks.
• Forks (/subtask) : sous-agent qui hérite de tout le contexte ; parallèle bon marché.
• Limites : CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (20) et CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (3).
• Commandes : /tasks, /list-agents, /subtask, /fork, /batch, /workflows ; /agents n'ouvre plus d'éditeur.
• Worktrees : --worktree <nom> isole une session ; isolation: worktree sur un sous-agent lui offre son propre checkout.
• Équipes d'agents (expérimental) : CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Workflows dynamiques : scripts Claude à grande échelle, suivi via /workflows.

Module suivant : MCP : connecter Claude Code à vos outils et à vos données — comment ouvrir Claude Code sur GitHub, une base Postgres, un tracker de tickets, sans écrire soi-même le code de l'intégration.