La plupart des équipes traitent Claude Code comme un seul agent. C’est passer à côté de la moitié de la valeur.

Le vrai déclic, ce sont les sub-agents — des personas spécialisés avec leurs propres system prompts, leurs propres outils autorisés et leurs propres règles. Vous ne parlez pas à « Claude ». Vous parlez à code-reviewer, puis à test-writer, puis à migration-runner. Chacun reste dans sa voie et fait une seule chose, bien.

Voici les 11 sub-agents que je fais tourner sur chaque base de code sérieuse, leur périmètre, et les définitions .claude/agents/<nom>.md qui les rendent opérationnels.

Pourquoi des sub-agents ?

Un agent monolithique est un généraliste. Les généralistes sont parfaits quand le problème est petit. Sur une vraie base de code, vous voulez :

• Un reviewer qui ne fait que reviewer et n’écrit jamais de code.
• Un test-writer qui ne touche jamais au code applicatif.
• Un migration-runner qui ne lance que des migrations et s’arrête.

La contrainte est la fonctionnalité. Chaque sub-agent est borné par un system prompt et une allowlist d’outils. Cette contrainte, c’est ce qui les rend fiables.

Les 11 que je garde sur chaque projet

1. code-reviewer

Périmètre : revue post-implémentation. Lit les diffs, n’en écrit jamais.

# system
Tu reviews des diffs. Tu ne modifies pas de fichiers. Tu sors :
1. Bugs (avec fichier:ligne)
2. Zones à risque (sécurité, perf, breaking changes)
3. Violations de style/convention vs CLAUDE.md
4. Verdict en 1 ligne : SHIP, FIX-FIRST, ou REWRITE.

# tools
allow: ["git diff *", "rg *", "cat *"]
deny:  ["edit", "shell-write"]

2. test-writer

Écrit de nouveaux tests. N’édite jamais le code de production. Si le test échoue, il rapporte l’échec — il ne « répare » rien.

3. test-fixer

L’image miroir. Lit les tests qui échouent, modifie le code de production pour les faire passer, et n’édite jamais le test sauf s’il est manifestement faux.

4. migration-runner

Lance des migrations DB. Autorisé : pnpm db:migrate, psql -c "...". Refusé : toutes les autres commandes shell.

5. dependency-auditor

pnpm outdated, pnpm audit, npm-check-updates. Sort un tableau markdown des upgrades + risque. N’exécute pas d’upgrades sans surveillance.

6. release-bot

Génère changelogs, bumps de version, tags. Ne pousse jamais — le push est humain.

7. docs-writer

Touche à README.md, docs/, commentaires JSDoc. Interdit dans src/ et app/.

8. refactor-surgeon

Refactors purs. Contrainte : zéro changement de comportement, tous les tests doivent passer avant et après. Si un test casse, le refactor n’était pas pur — annulez.

9. incident-responder

Celui qu’on ne convoque qu’en cas de panne. Lit les logs, écrit un squelette de postmortem, suggère des commandes de rollback. Ne lance jamais de commandes en prod.

10. architect

Read-only. Regarde la base de code, produit un brouillon d’ADR (architecture decision record) quand vous demandez « doit-on ajouter X ? »

11. ci-fixer

Lit .github/workflows/, les logs de CI qui échouent, et propose des changements minimaux. Autorisé à pousser des branches, jamais sur main.

Ce qui va dans .claude/agents/<nom>.md

Chaque agent est un fichier. Voici la forme canonique :

---
name: code-reviewer
model: claude-sonnet-4
---

# system
<persona + périmètre + format de sortie>

# tools
allow: [...]
deny: [...]

# Respect de CLAUDE.md
Lire le CLAUDE.md du projet avant d'agir.

C’est tout. Commitez ce dossier ; toute l’équipe a la même équipe d’agents.

Comment ils collaborent (sans qu’on parle de « multi-agents »)

Ce n’est pas encore les pipelines multi-agents (c’est l’article 7). C’est la chorégraphie plus simple :

Vous → /agents → pick test-writer → "écris des tests pour lib/cache.ts"
  → /agents → pick test-fixer    → "fais-les passer"
  → /agents → pick code-reviewer → "review le diff"
  → /release-notes

Chaque étape est bornée. Chaque étape est relisable. Vous n’avez jamais un seul agent qui « a écrit les tests, corrigé le code, fait sa propre review et poussé sur main ». Ce genre d’auto-review est exactement le mode d’échec qu’il faut concevoir pour éviter.

La règle du nommage

Les sub-agents portent le nom de rôles, pas d’outils. code-reviewer, pas claude-with-rg. migration-runner, pas psql-runner. Les rôles se composent ; les outils non.

Quand un nouveau coéquipier arrive, il lit .claude/agents/ une fois et comprend immédiatement le modèle opérationnel. C’est de la documentation par configuration.

Exemple en direct : livrer une feature avec l’équipe

Vous : /agents test-writer
> Écris des cas vitest pour lib/cache.ts couvrant l'expiration TTL et l'éviction LRU.
test-writer : <écrit 2 tests, les deux échouent, rapporte>

Vous : /agents test-fixer
> Fais passer ces tests sans modifier lib/cache.test.ts.
test-fixer : <implémente TTL + LRU dans lib/cache.ts, tests verts>

Vous : /agents code-reviewer
> Review le diff.
code-reviewer : SHIP.

Vous : /release-notes
release-bot : <écrit le changelog>

Vous : git checkout -b feat/cache-lru && git commit && gh pr create

Vous avez écrit ~20 lignes en langage naturel. Trois spécialistes différents ont écrit / vérifié / signé le vrai code. Voilà le workflow.

Construire les vôtres

Commencez par deux : code-reviewer et test-writer. Utilisez-les sur chaque PR pendant une semaine. Vous découvrirez où est le frottement et ajouterez le troisième organiquement — généralement ci-fixer ou migration-runner.

Au bout de deux mois, chaque équipe que j’ai onboardée a 6 à 8 sub-agents commités dans .claude/agents/, et ils sont traités comme de l’infrastructure.

---

Article suivant : Sécurité en production — permissions, garde-fous, et ce qu’aucun sub-agent ne devrait jamais toucher sans surveillance.