Routage des sous-agents

Problème : Ton session Claude Code principale lance des sous-agents toute la journée. Elle n'a pas de sens intégré pour savoir quand les faire tourner côte à côte, quand les enchaîner, ou quand les pousser en arrière-plan. Sans règles de routage dans CLAUDE.md, elle en choisit une. Elle choisit souvent mal.

Gain rapide : Ajoute ce bloc de routage dans ton CLAUDE.md :

## Sub-Agent Routing Rules
 
**Parallel dispatch** (ALL conditions must be met):
 
- 3+ unrelated tasks or independent domains
- No shared state between tasks
- Clear file boundaries with no overlap
 
**Sequential dispatch** (ANY condition triggers):
 
- Tasks have dependencies (B needs output from A)
- Shared files or state (merge conflict risk)
- Unclear scope (need to understand before proceeding)
 
**Background dispatch**:
 
- Research or analysis tasks (not file modifications)
- Results aren't blocking your current work

Ton thread principal lit le bloc et commence à faire des handoffs plus intelligents tout seul.

Ton thread principal est le routeur

Voilà ce que la plupart des gens ratent. Claude Code n'est pas un seul modèle. C'est une petite équipe, et ton chat principal est le chef. Ce chef distribue le travail à des sous-agents spécialistes. Tout ce qui suit ne fonctionne qu'aussi bien que tu as appris au chef à distribuer les tâches.

Trois modes d'exécution existent sur le Task tool. Chacun correspond à une forme de travail différente :

Ignore les règles et ton chef revient à une exécution lente, prudente, une chose à la fois. Sûre. Aussi lente.

Parallèle : diviser par domaine

Le dispatch parallèle convient au travail qui s'étend sur des coins séparés de la codebase. Mets la carte des domaines dans CLAUDE.md pour que le chef sache où sont les lignes :

## Domain Parallel Patterns
 
When implementing features across domains, spawn parallel agents:
 
- **Frontend agent**: React components, UI state, forms
- **Backend agent**: API routes, server actions, business logic
- **Database agent**: Schema, migrations, queries
 
Each agent owns their domain. No file overlap.

La règle stricte : le parallèle tient seulement quand les agents touchent des fichiers différents. Ton chef doit voir ces limites de domaine pour diviser le travail proprement.

Séquentiel : chaînes qui dépendent les unes des autres

Certains travaux n'ont de sens que dans l'ordre. L'étape deux a besoin de ce que l'étape un a produit. Le chef doit tenir cette ligne.

Liste tes chaînes courantes dans CLAUDE.md. Comme ça le chef les repère et arrête d'essayer de faire tourner une chaîne en parallèle.

Arrière-plan : recherche qui ne te bloque pas

Les tâches de forme recherche devraient tomber en arrière-plan d'elles-mêmes, pour que tu puisses continuer à travailler. Appuie sur Ctrl+B pendant n'importe quelle exécution de sous-agent, ou pose la règle dès le départ :

## Background Execution Rules
 
Run in background automatically:
 
- Web research and documentation lookups
- Codebase exploration and analysis
- Security audits and performance profiling
- Any task where results aren't immediately needed

Lance /tasks quand tu veux jeter un oeil à ce qui tourne. Les résultats remontent quand l'agent a terminé. Le guide des workflows asynchrones a la version longue.

Configurer le comportement des sous-agents

Le routage est une couche. Claude Code te donne aussi des contrôles directs sur le comportement des sous-agents.

Choisir le modèle de sous-agent

CLAUDE_CODE_SUBAGENT_MODEL dit à Claude Code quel modèle lancer pour les sous-agents. Cette seule variable déplace le curseur coût/vitesse plus que presque n'importe quoi d'autre :

# Use a lighter model for sub-agents to save tokens
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"

Une division propre : Opus sur le thread principal pour la réflexion difficile, Sonnet sur les sous-agents pour le travail de suivi ciblé. La dépense en tokens baisse et le travail passe quand même, parce que chaque tâche de sous-agent est déjà bien délimitée.

Épingler des spécialistes dans .claude/agents/

Au lieu de lancer de nouveaux appels Task à chaque fois, garde des spécialistes nommés comme fichiers Markdown avec frontmatter YAML dans .claude/agents/. L'orchestrateur de Claude les trouve tout seul.

.claude/agents/ contient les agents de projet qui vivent avec le dépôt et s'envoient à ton équipe. ~/.claude/agents/ contient les agents utilisateur qui te suivent sur chaque projet.

Les agents ici héritent de ton CLAUDE.md, donc ils apparaissent en connaissant déjà tes conventions, règles de code, et particularités du projet.

Verrouiller les agents avec des règles de permission

Les règles Task(AgentName) dans ton fichier de permissions décident quels sous-agents sont autorisés à tourner :

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

Le flag --disallowedTools fait la même chose au lancement :

claude --disallowedTools "Task(Explore)"

Pratique pour garder les dépenses en tokens serrées, ou pour empêcher l'exploration autonome d'un dépôt de production.

Les mauvaises invocations sont le vrai bug

La plupart des problèmes de sous-agents ne viennent pas de l'exécution. C'est l'invocation qui l'a déclenchée. Le chef envoie un sous-agent avec des instructions floues, du contexte manquant, et pas de ligne d'arrivée claire. Le sous-agent fait ce qu'il peut avec ce qu'il a.

Mauvaise invocation : "Fix authentication"

Bonne invocation : "Fix OAuth redirect loop where successful login redirects to /login instead of /dashboard. Reference the auth middleware in src/lib/auth.ts."

L'écart, c'est le contexte. Les sous-agents tournent dans leur propre fenêtre de courte durée. Ils ne peuvent pas revenir en cours d'exécution pour demander ce que tu voulais dire. Ton chef a besoin de règles strictes pour écrire des invocations complètes du premier coup.

C'est là où beaucoup de fichiers CLAUDE.md s'arrêtent. Le routage est géré. La qualité des invocations ne l'est pas. Une bonne configuration couvre les deux : chaque dispatch porte le contexte complet, des instructions claires, des fichiers liés, et une définition concrète de terminé.

Erreurs d'orchestration courantes

Sur-parallélisation : dix agents parallèles pour une petite fonctionnalité brûle des tokens et ajoute du travail de coordination. Regroupe les petites tâches liées dans un agent.

Sous-parallélisation : quatre passes indépendantes qui tournent dos à dos alors qu'elles auraient pu tourner en même temps. Cherche l'indépendance de domaine.

Invocations vagues : "Implement the feature" sans portée, sans fichiers, sans sortie attendue.

Où aller ensuite

Ces règles de routage seules vont affûter comment ton chef distribue le travail. Il y a plus d'orchestration pro-level au-dessus de ça :

• Exigences d'invocation constitutionnelles qui forcent chaque dispatch à porter les quatre pièces essentielles
• Tables de routage d'agents qui mappent les types de tâches aux agents spécialistes
• Protocoles de handoff de contexte qui transportent l'état à travers une chaîne séquentielle
• Coordination basée sur les sessions pour suivre le travail en plusieurs étapes

Commence avec les règles de routage. Colle-les dans CLAUDE.md aujourd'hui. Le chef choisira de meilleures voies demain. Pour des schémas plus approfondis, lis la distribution de tâches et les fondamentaux des agents.