Sous-agents spécialisés et orchestrateur avec Claude Code : quand déléguer, limites et coûts
Une petite équipe d'agents (SQL, PowerShell, Azure, relecteur de documentation) et un orchestrateur : format des fichiers, briefs, parallélisme, limites et coûts.
Un sous-agent est un spécialiste auquel Claude Code peut déléguer une tâche. Il travaille dans sa propre fenêtre de contexte, avec ses propres instructions et ses propres outils, puis revient avec un résumé. Sur un dépôt de DBA, j'utilise une petite équipe : un expert SQL, un expert PowerShell, un expert Azure, un relecteur de documentation en lecture seule, et un orchestrateur qui répartit le travail entre eux.
À quoi ressemble un fichier d'agent
Un agent est un fichier Markdown dans .claude/agents/. L'en-tête dit qui il est et ce qu'il peut faire ; le corps est son prompt système.
---
name: sql-expert
description: Use for T-SQL work: queries, procedures, DDL, migration scripts, tuning, and placeholder templates read by PowerShell.
tools: Read, Edit, Write, Grep, Glob
model: inherit
---
You are a SQL Server and Azure SQL expert for this repository.
## Standards
Follow rule `sql-script.md`. Do not copy it here.
## Safety
Read-only queries are fine. Never run DDL or DML against production: write the script, stop.
## Output
What was done / files changed / how it was validated.
Trois champs comptent surtout :
descriptionest ce que la session principale lit pour décider de déléguer. Dites quand utiliser l'agent.toolsest la vraie frontière de permissions. Un relecteur n'a que des outils de lecture et de recherche : il ne peut physiquement pas modifier.modelpeut être hérité ou fixé sur un modèle moins coûteux pour les rôles simples.
Mon équipe
| Agent | Écrit ? | Rôle |
|---|---|---|
sql-expert |
oui | T-SQL, modèles, optimisation |
powershell-expert |
oui | fonctions, modules, tests Pester, lint |
azure-expert |
oui | YAML de pipelines, Azure SQL, Batch, identités |
docs-expert |
oui | README, changelogs, commentaires |
docs-reviewer |
non | vérifie la documentation contre le code, constats confirmés uniquement |
orchestrator |
non | découpe une demande multiple et l'aiguille |
Convention de nommage : <domaine>-expert écrit, <domaine>-reviewer ne fait que lire. Le mot indique le risque avant même l'appel.
Quand déléguer, et quand ne pas le faire
Déléguez quand :
- la tâche est autonome et son résultat tient en un court résumé (relire ce diff, trouver tous les appelants de cette fonction) ;
- elle exige beaucoup de lecture qui noierait le contexte principal ;
- vous voulez un regard indépendant, par exemple un relecteur qui n'a pas vu votre raisonnement ;
- plusieurs morceaux indépendants peuvent tourner en parallèle (fichiers ou composants différents).
Ne déléguez pas quand :
- le changement est petit. Pour corriger une fonction, rédiger le brief coûte plus cher que la modification ;
- deux agents toucheraient le même fichier ;
- la tâche dépend d'une longue conversation que l'agent n'a pas vue.
Comment briefer un agent
Un agent ne connaît que ce que contient le brief. Un bon brief a quatre parties, que j'utilise comme modèle :
Task: add a -WhatIf switch to function Remove-Foo in the shared module.
Context: the function is called by two applications; do not change its return contract.
Constraints: follow rule powershell-function; do not commit; do not run any entry script.
Expected outcome: changed files, lint clean, one Pester test.
Donnez des noms de règles, pas leur contenu. Dites ce qui est interdit. Ne mettez jamais de secret ni de donnée personnelle dans un brief.
L'orchestrateur
L'orchestrateur n'a aucun outil d'écriture. Il lit la demande, choisit les agents, séquence le travail dépendant (le SQL d'abord, puis le PowerShell qui le consomme), parallélise l'indépendant, valide ce qui revient et rédige la synthèse. Si un agent échoue deux fois, il me remonte le problème au lieu de boucler.
flowchart TD
U["Demande"] --> O["Orchestrateur"]
O --> Q["sql-expert"]
O --> P["powershell-expert"]
O --> Z["azure-expert"]
Q --> P
P --> D["docs-expert"]
D --> R["docs-reviewer : lecture seule"]
R --> O
Z --> O
O --> S["Synthèse pour le DBA"]
Limites et coûts
- Jetons. Chaque agent démarre avec un contexte neuf et relit les fichiers. Plusieurs agents en parallèle consomment vite. Utilisez-les là où l'isolation ou le parallélisme paie.
- Contexte perdu. L'agent ne voit que le brief, et vous ne voyez que son résumé. Du détail se perd des deux côtés.
- Erreurs assurées. Un résumé a l'air sûr de lui même quand il se trompe. J'ouvre les fichiers cités et je confirme chaque constat avant d'agir.
- Conflits. Des agents qui modifient le même fichier s'écrasent. Un seul rédacteur par fichier ; aucune opération Git depuis un agent.
- Biais d'hypothèse. Si vous donnez votre conclusion à un relecteur, il a tendance à l'approuver. Donnez-lui le code et les critères.
Retour d'expérience
- Commencez avec deux agents, pas neuf. Ajoutez-en un quand vous remarquez que vous redonnez toujours le même brief.
- Les relecteurs en lecture seule offrent le meilleur rapport : peu chers, sûrs, et ils trouvent ce que l'auteur a manqué.
- Gardez les standards dans les règles et faites-les citer par les agents.
- La session principale reste responsable : elle valide, lance les contrôles et décide.