Chief of Staff : orchestrer des sous-agents Claude Code

Le pattern Chief of Staff

Dans ce pattern, une équipe d’agents Claude Code a deux rôles. Le Chief of Staff ne fait pas le travail spécialisé : il reçoit la demande, la découpe, choisit le bon spécialiste pour chaque morceau et livre une réponse vérifiée. Les spécialistes sont des sous-agents qui traitent chacun un morceau précis.

• Le Chief clarifie l’objectif de la demande.
• Il découpe le travail en morceaux dont chacun a un critère de fin.
• Il confie chaque morceau à un spécialiste avec un brief autonome, puis rassemble les comptes-rendus.

Le pattern tient en une règle : la session principale coordonne, elle n’écrit pas tout. Une tâche triviale reste traitée directement par le Chief ; une tâche complexe se répartit entre plusieurs agents aux rôles distincts.

Pourquoi des sous-agents

Un sous-agent démarre avec son propre contexte : il ne voit pas la conversation principale, seulement le brief qu’on lui écrit. Les tâches lourdes (lire beaucoup de fichiers, lancer une suite de tests, relire un diff) remplissent ce contexte. Si tout se passe dans une seule session, la coordination se noie dans les détails. Avec des sous-agents, les détails restent dans leur contexte, et la session principale garde le sien pour décider.

Il y a aussi un coût : chaque agent ajoute de la latence et consomme des jetons. Lance un agent seulement quand la tâche le justifie, et ne multiplie pas les agents pour une demande simple.

Lancer le Chief dans Claude Code

Le fichier du Chief est un agent comme les autres, placé dans .claude/agents/. Pour qu’il dirige la session, lance Claude Code avec l’option --agent :

claude --agent chief-of-staff

Pour en faire la valeur par défaut du projet, ajoute la clé agent dans .claude/settings.json. L’option de ligne de commande l’emporte sur ce réglage. Ce fichier contient sans doute d’autres réglages : ajoute seulement la clé, sans remplacer le reste.

{
  "agent": "chief-of-staff"
}

Cette session principale prend les restrictions d’outils et le modèle du Chief. Le détail de l’invocation est dans la documentation officielle des sous-agents.

Les spécialistes dans .claude/agents/

Chaque spécialiste est un fichier Markdown dans .claude/agents/. Un agent placé dans ~/.claude/agents/ vaut pour tous tes projets. À nom égal, la version du projet l’emporte. Les emplacements sont décrits dans la documentation officielle.

---
name: tester
description: Writes and runs the vitest tests for a change. Use after the code is written.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
---

Write tests for the change, run them, and report the results in the format the brief asks for.

• name et description sont obligatoires. La description compte : la session principale la lit pour choisir le spécialiste.
• tools liste les outils permis. Si le champ est omis, l’agent hérite de tous les outils disponibles.
• model accepte sonnet, opus, haiku, un identifiant complet ou inherit.
• Les autres champs courants sont disallowedTools, maxTurns, effort et permissionMode.

Un spécialiste n’a pas besoin de lancer d’autres agents. Retire donc Agent de sa liste d’outils, ou ajoute-le à disallowedTools : la section suivante détaille la règle.

Règles d’un bon Chief

Ces règles viennent de la pratique de ce pattern. Ce ne sont pas des garanties de Claude Code : un prompt est une consigne, pas une contrainte. Le modèle peut ne pas la suivre, alors relis les comptes-rendus.

1. Écris un brief autonome pour chaque délégation : objectif, format de sortie, sources et outils, limites de la tâche.
2. Découpe chaque étape en sous-étapes, avec un critère de fin vérifiable.
3. Lance un agent neuf pour chaque sous-étape plutôt que de reprendre un agent dont l’historique a grossi.
4. Exige un compte-rendu compact : pas de journal, pas de sortie de commande recopiée.
5. Regroupe les vérifications : tests ciblés pendant le travail, puis suite complète, lint et build une fois par étape.
6. Ne lance jamais le Chief comme sous-agent : il dirige la session, ce n’est pas un spécialiste.
7. Retire Agent des outils des spécialistes, pour qu’ils ne lancent pas leurs propres sous-agents.

Par défaut, un sous-agent peut lancer ses propres sous-agents, jusqu’à trois niveaux sous la conversation principale. Le plus simple pour l’empêcher est de laisser Agent hors de la liste des outils :

tools: Read, Glob, Grep, Edit, Write, Bash

La variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 désactive aussi l’imbrication. Le Chief garde l’outil Agent, puisque c’est lui qui délègue.

Ce que Swarmbuilder génère

Swarmbuilder écrit le Chief dans son propre fichier, .claude/agents/chief-of-staff.md, avec son équipe, ses règles de délégation et le protocole de compte-rendu. Le contexte commun (objectif et conventions) va dans .claude/rules/swarmbuilder.md. Le ZIP n’écrit jamais de CLAUDE.md, ton fichier existant n’est donc jamais remplacé.

- **`architect`** — À utiliser avant un changement qui touche plusieurs zones (front, serveur, MCP, export) : rend un plan par étapes, en lecture seule. _(quand : avant un changement multi-zones)_
- **`ui-dev`** — À utiliser pour l’interface : écrans, canvas React Flow, panneaux, i18n, marketplace, page d’accueil, SEO et visite guidée. _(quand : interface, i18n, marketplace)_
- **`export-engineer`** — À utiliser pour les fichiers générés (.claude/, SDK, swarm.json, ZIP), l’import d’une config existante, le plan d’écriture et le serveur MCP. _(quand : export, import, MCP)_
- **`model-engineer`** — À utiliser pour le schéma zod du swarm, le store, la validation, le lint des prompts, le poids d’orchestration, les profils et les templates. _(quand : schéma, lint, templates)_
- **`server-engineer`** — À utiliser pour le serveur Fastify hors MCP : routes, comptes, sessions, crédits, base SQLite et migrations, e-mails, invitations. _(quand : serveur, comptes, crédits, base)_
- **`devops`** — À utiliser pour le Dockerfile, docker-compose, docker/deploy.sh et update.sh, les variables d’environnement, la sauvegarde et la mise en production. _(quand : Docker, déploiement)_
- **`tester`** — À utiliser pour écrire et lancer les tests vitest (front et serveur) et les parcours e2e, et diagnostiquer les échecs. _(quand : quand le code est prêt)_
- **`reviewer`** — À utiliser après une implémentation : relit le git diff pour la correction, les invariants et la sécurité du serveur, sans rien modifier. _(quand : quand les tests passent)_
- **`doc-writer`** — À utiliser quand le comportement visible change : met à jour le README, TODO.md, le changelog des nouveautés et les textes d’aide. _(quand : si le comportement visible change)_

Cet extrait est une vraie sortie de l’export, sans retouche. Chaque agent y figure avec sa description et sa condition de délégation.

Construire son équipe

Deux voies. Dans l’éditeur, tu dessines l’équipe sur le canvas, tu règles chaque agent, puis tu exportes un ZIP à décompresser à la racine du projet. Depuis Claude Code, le serveur MCP de Swarmbuilder propose une équipe à partir du projet en cours, et c’est Claude Code qui écrit les fichiers. Voici la voie MCP :

1. Connecte le serveur une fois, avec la commande ci-dessous.
2. Demande à Claude Code une équipe pour le projet en cours.
3. Relis l’aperçu et l’équipe proposée avant d’écrire quoi que ce soit.
4. Laisse Claude Code écrire les fichiers, puis lance le Chief avec claude --agent chief-of-staff.

claude mcp add --transport http --scope user swarmbuilder https://swarmbuilder.fr/mcp

L’adresse est celle de ce service ; si tu lis https://<domaine>, remplace-la par l’adresse de ton service. Son administrateur doit avoir ouvert l’accès MCP. La connexion passe par OAuth, dans le navigateur, avec ton compte : aucune clé à copier. Dans Claude Code, lance /mcp, choisis swarmbuilder puis « Authenticate ». Seule la génération des fichiers consomme des crédits ; l’aperçu et la validation n’en consomment pas.

Sources

• Sous-agents Claude Code : emplacements et portée
• Sous-agents Claude Code : écrire un fichier d’agent
• Sous-agents Claude Code : champs du frontmatter
• Sous-agents Claude Code : lancer un sous-agent
• Sous-agents Claude Code : sous-agents imbriqués