Subagents Claude Code : ce que 18 en production nous ont appris

Subagents Claude Code : ce que 18 en production nous ont appris

Dix-huit subagents Claude Code font tourner chaque article de ce site, y compris celui-ci. Six sur Opus, onze sur Sonnet, un sur Haiku. Le subagent researcher, à lui seul, a accumulé 74 fichiers de mémoire depuis nos débuts. Aucun d'eux ne se parle. C'est ce qui nous a le plus surpris : un subagent ne voit jamais votre conversation, et il ne voit jamais non plus la conversation d'un autre subagent. Tout le pipeline repose donc sur des fichiers sur disque. Voici la flotte, la répartition des modèles, le dispositif de mémoire, et ce qui a cassé en cours de route.

En bref :

• Un subagent tourne dans sa propre fenêtre de contexte, avec son propre system prompt, ses propres outils et ses propres permissions.
• Nous en faisons tourner 18 : 6 sur Opus, 11 sur Sonnet, 1 sur Haiku.
• Les agents se passent le relais via des fichiers sur disque, jamais via un contexte partagé.
• Depuis la v2.1.198, l'assistant de création /agents a disparu. Écrivez le fichier vous-même.

Qu'est-ce qu'un subagent Claude Code ?

Un subagent Claude Code est un assistant spécialisé qui tourne dans sa propre fenêtre de contexte, avec un system prompt personnalisé, un accès spécifique aux outils, et des permissions indépendantes. Il exécute une tâche annexe sans noyer votre conversation principale, puis ne renvoie que son résumé. Les définitions vivent sous forme de fichiers Markdown avec un frontmatter YAML dans .claude/agents/, documentées dans la référence d'Anthropic sur les subagents.

Claude délègue à l'un d'eux automatiquement. Il lit le champ description de chaque subagent qu'il peut voir, et quand une tâche correspond, il lui confie le travail sans vous demander votre avis au préalable. Depuis v2.1.198, ces subagents tournent en arrière-plan par défaut, si bien que la délégation se produit souvent pendant que vous continuez à taper. Vous pouvez aussi en appeler un par son nom quand vous voulez un agent précis pour une tâche précise.

Claude Code embarque trois subagents natifs : Explore pour la recherche en lecture seule dans le code, Plan pour la planification, et general-purpose pour tout le reste.

Un détail de nommage qui piège les anciens guides et les anciens fichiers de config : l'outil qui lance un subagent s'appelle Agent, pas Task. Il a été renommé en v2.1.63, et la documentation confirme que les références Task(...) existantes fonctionnent toujours comme alias. Nous utilisons Agent tout au long de cet article.

La suite de cet article n'est pas une documentation de référence. Celle d'Anthropic fait déjà ce travail mieux que nous ne pourrions le faire, avec environ 8 000 mots d'annotations de version qui descendent jusqu'à v2.1.212. Ce qui suit, c'est à quoi ressemblent dix-huit subagents quand ils tournent tous les jours.

Notre flotte de 18 agents : à quoi ressemble un vrai setup sur disque

Notre répertoire .claude/agents/ contient 18 fichiers de définition de subagents, chacun un fichier Markdown avec un frontmatter YAML. Ensemble, ils font tourner tout le pipeline de contenu de ce site : recherche, brief, rédaction, validation, traduction en neuf langues, génération d'images et publication. Six tournent sur Opus, onze sur Sonnet, un sur Haiku.

Tous les guides sur les subagents en première page de Google démontrent avec le même exemple code-reviewer recopié depuis la documentation. Voici à quoi ressemblent dix-huit d'entre eux quand ils livrent réellement du travail.

.claude/agents/
├── abc-link-checker.md
├── brief-creator.md
├── content-gap-finder.md
├── content-refresher.md
├── content-writer.md
├── image-handler.md
├── language-translator.md
├── payload-publisher.md
├── pipeline-manager.md
├── rank-checker.md
├── rescue-diagnoser.md
├── rescue-prioritizer.md
├── researcher.md
├── sanity-publisher.md
├── seo-auditor.md
├── sitemap-checker.md
├── translation-coordinator.md
└── validator.md

Ils se répartissent en quatre familles. La production de contenu enchaîne researcher, brief-creator, content-writer puis validator. La distribution couvre translation-coordinator, language-translator, image-handler, payload-publisher et sanity-publisher. La maintenance regroupe content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker et abc-link-checker. La coordination revient à pipeline-manager et content-gap-finder.

Deux de ces fichiers, recopiés tels quels depuis le disque, portent à eux seuls tout l'argument sur le coût :

# .claude/agents/researcher.md
name: researcher
tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash
model: opus
memory: project
skills:
  - seo
  - competitor-analysis

# .claude/agents/sitemap-checker.md
name: sitemap-checker
tools: Read, Write, Edit, Glob, Grep, WebFetch
model: haiku

Même mécanisme, environ dix fois le coût par token. L'un est un agent Opus avec accès au web et mémoire persistante, qui décide de ce qu'un article doit défendre. L'autre est un agent Haiku qui récupère un sitemap et écrit un fichier JSON. Rien dans le format des subagents ne vous oblige à payer le tarif Opus pour la seconde tâche, et la plupart des flottes que nous avons vues font pourtant exactement ça par défaut.

Le champ skills: de researcher précharge deux définitions de skills dans le system prompt de ce subagent au moment du lancement, ce qui lui permet de connaître nos conventions SEO sans qu'on ait à les répéter à chaque exécution. Si vous n'en avez pas encore écrit, nous avons traité comment écrire une Claude skill séparément, et cet article ne va pas s'y attarder.

Si vous voulez un catalogue de définitions à parcourir et à copier, la collection communautaire awesome-claude-code-subagents est celle que les gens recherchent réellement. Lisez-la pour les structures, pas pour l'actualité : certaines entrées datent d'avant le renommage en Agent.

Comment créer un subagent ? (L'assistant /agents a disparu)

Vous créez un subagent Claude Code en écrivant vous-même un fichier Markdown dans .claude/agents/, ou en demandant à Claude de l'écrire pour vous. Depuis v2.1.198, la commande /agents n'ouvre plus l'assistant de création interactif. L'exécuter affiche désormais un simple rappel qui vous renvoie vers le répertoire.

1. Créez le fichier. .claude/agents/{name}.md pour un subagent de projet versionné avec le code, ou ~/.claude/agents/{name}.md pour un subagent qui vous suit d'un projet à l'autre.
2. Renseignez name et description. Le champ description compte plus que tout le reste du fichier, car c'est ce que Claude compare pour décider s'il délègue. Écrivez-le comme une règle de routage, pas comme un intitulé de poste.
3. Réglez tools et model. tools est une liste blanche ; si vous l'omettez, le subagent hérite des outils de la conversation principale. model remplace le modèle de votre session.
4. Écrivez le system prompt comme le corps Markdown situé sous le frontmatter. Les subagents ne reçoivent que ce prompt plus quelques détails d'environnement de base, jamais le system prompt complet de Claude Code.
5. Invoquez-le. Automatiquement, en laissant la description correspondre, ou explicitement en le demandant par son nom.

---
name: changelog-writer
description: Writes release notes from merged pull requests. Use when the user asks for a changelog, release notes, or a summary of what shipped.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You write release notes. Read the merged PRs since the last tag with `git log`,
group them into Added / Changed / Fixed, and write one line per change in past
tense. Never invent a change that is not in the log. Return only the markdown.

Plusieurs guides actuellement bien classés disent encore aux lecteurs de lancer /agents pour ouvrir l'interface de gestion. Cette instruction est morte. Un autre piège que la documentation mentionne explicitement : le watcher de fichiers ne couvre que les répertoires qui existaient au démarrage de la session, donc le tout premier fichier d'agent dans un répertoire agents/ flambant neuf a besoin d'un redémarrage de Claude Code avant de se charger.

Subagent vs Skill vs Agent Team vs Fork : lequel vous faut-il vraiment ?

Choisissez un subagent quand une tâche annexe noierait votre conversation principale et que vous n'avez besoin que du résumé. Choisissez une skill quand vous voulez apprendre à Claude une procédure qu'il exécute dans votre contexte existant. Choisissez une agent team quand des membres doivent coordonner entre eux. Choisissez un fork quand la tâche annexe a besoin de l'historique de votre conversation.

Les subagents vous rendent compte à vous, jamais entre eux. Les agent teams se parlent directement entre elles. Cette seule différence détermine de quelle primitive vous avez besoin.

Notre choix par défaut est le subagent, et nous n'avons jamais eu besoin d'une agent team. La coordination dans notre pipeline est séquentielle plutôt que conversationnelle, donc une liste de tâches partagée ne nous apporterait rien tout en coûtant des tokens. Les agent teams sont aussi encore expérimentales et désactivées par défaut, ce qui est rédhibitoire pour tout ce que nous faisons tourner sans supervision. Les skills se situent à un tout autre niveau : ce sont des instructions chargées dans le contexte déjà en cours, y compris celui d'un subagent, ce qui explique pourquoi researcher en déclare deux au lieu de leur déléguer le travail.

Choix du modèle : quels agents vont sur Haiku, Sonnet et Opus

Réglez model dans le frontmatter d'un subagent sur haiku, sonnet, opus, ou un ID de modèle précis, et ce subagent remplace le modèle de votre session. Notre répartition réelle sur 18 agents est six sur Opus, onze sur Sonnet, un sur Haiku, assignée selon le niveau de jugement que la sortie de l'agent exige réellement.

Trois règles qu'on donnerait à quiconque hiérarchise une flotte. Placez un agent sur Haiku quand sa sortie est déterministe et son entrée petite : récupération, parsing, comptage, reformatage. Placez un agent sur Sonnet quand la tâche est longue et bien spécifiée, mais que quelqu'un a déjà décidé à quoi ressemble une réponse « correcte », ce qui couvre l'essentiel du travail d'exécution, y compris les neuf workers de traduction. Réservez Opus aux agents dont rien en aval ne remettra la sortie en question.

Cette dernière règle explique pourquoi validator tourne sur Opus, même s'il produit un rapport court. Rien ne vérifie le vérificateur.

Une précision de version qui change le calcul : depuis v2.1.198, le subagent natif Explore ne tourne plus systématiquement sur Haiku, il hérite désormais du modèle de la session. Un subagent défini au niveau utilisateur ou projet et nommé Explore remplace le natif et conserve son propre champ model, donc définissez-en un avec model: haiku si vous voulez garder l'exploration sur un modèle bon marché.

Contrats de fichiers : comment nos agents se passent le relais sans partager de contexte

Un subagent ne voit pas l'historique de votre conversation, et il ne voit pas non plus celui d'un autre subagent. Les passations en mémoire entre agents sont donc structurellement impossibles. La solution consiste à transformer chaque passation en un artefact sur disque, pour que l'agent suivant lise un fichier au lieu d'hériter d'un contexte qu'il ne pourra jamais avoir.

techsy.community/posts/claude-code-subagents/
├── research.md      # researcher       → SERP analysis, keyword data, gaps
├── brief.md         # brief-creator    → section-by-section spec
├── en.md            # content-writer   → the post you are reading
├── de.md            # language-translator (one subagent per language)
├── hero.webp        # image-handler
├── validation.md    # validator
└── meta.json        # pipeline stage, updated by a PostToolUse hook

Cinq artefacts, chacun écrit par un agent différent, chacun lu par le suivant, tous lisibles par un humain et suivis dans git. Le pipeline survit aux limites de contexte parce qu'aucun agent n'a jamais besoin du contexte d'un autre agent. Il n'a besoin que du fichier de l'agent précédent.

L'exemple le plus parlant, c'est la traduction. translation-coordinator lit en.md, puis lance un subagent language-translator par langue, neuf ou dix d'un coup. Dans notre repo, la concurrence dépend du fait d'émettre tous les appels de lancement dans un seul message : c'est un comportement observé sur notre installation plutôt qu'une garantie documentée, mais il s'est montré assez constant pour que le coordinateur soit écrit de façon à le faire délibérément. Chaque traducteur écrit son propre {lang}.md et aucun ne peut voir le travail des autres, ce qui ne pose aucun problème, car le contrat, c'est le fichier, et le fichier est déjà complet.

C'est aussi là que s'arrêtent les subagents et que quelque chose d'autre commence. Les subagents travaillent à l'intérieur d'une seule session. Si vous voulez des espaces de travail réellement indépendants, avec leur propre historique, vous faites plutôt tourner plusieurs sessions Claude Code en parallèle, ou vous utilisez isolation: worktree pour donner à un subagent sa propre copie du dépôt.

Comment les subagents se souviennent-ils d'une session à l'autre ?

Seulement si vous définissez le champ memory, qui accepte trois portées : user écrit dans ~/.claude/agent-memory/<name>/, project écrit dans .claude/agent-memory/<name>/, et local écrit dans .claude/agent-memory-local/<name>/. Sans ça, chaque invocation démarre à vide. Douze de nos dix-huit agents déclarent memory: project.

Après une quarantaine d'articles, ces répertoires sont devenus conséquents. researcher détient 74 fichiers de mémoire, validator 66, brief-creator 65. Ce ne sont pas des journaux. Ce sont des décisions accumulées : quels schémas de H1 ont sous-performé, quelles affirmations client on ne peut pas faire, quelles formes de SERP récompensent un tableau plutôt qu'un texte.

Voici la contrainte qui façonne tout ça. Un subagent avec mémoire activée ne reçoit que les 200 premières lignes ou les 25 Ko de MEMORY.md injectés dans son system prompt, selon ce qui arrive en premier. C'est cette limite unique qui explique pourquoi chacun de nos agents tient un index plutôt qu'un journal.

# Researcher Memory

## Reusable post patterns
- [Challenger H1 pattern](feedback_challenger_h1_pattern.md): when a question-shaped H1 earns the click
- [Sponsored post research](feedback_sponsored_post_research.md): H1 must be category-shaped, never a review
- [Claude Skills tutorial](project_claude_skills_tutorial.md): docs own the top two slots, target the long tail

Une ligne par entrée, le détail renvoyé vers le fichier thématique lié, que l'agent lit à la demande avec son outil Read. MEMORY.md reste un index qui tient dans le budget d'injection, pendant que le corpus derrière lui grossit sans limite.

Nous utilisons project plutôt que user pour presque tout, parce que la mémoire de projet vit dans le repo et voyage avec le contrôle de version. Quand un coéquipier fait un pull, il récupère le jugement accumulé de l'agent en même temps que le code. local existe pour les cas où vous voulez les notes, mais pas le commit.

Ce qui a cassé : modes de défaillance, noms en double, et un alias hérité dans notre propre repo

Quatre modes de défaillance expliquent presque tout ce qu'on a rencontré. Un subagent qui refuse de se lancer, un subagent qui, en silence, n'est pas celui que vous avez modifié, un subagent que Claude ne trouve pas du tout, et un plafond de session strict sur le nombre que vous pouvez lancer. Les quatre ont des correctifs courts et sans ambiguïté.

Celui du nom en double est plus vicieux qu'il n'y paraît. Vous modifiez un fichier, le comportement ne change pas, et il n'y a d'erreur nulle part, parce qu'un autre fichier portant le même name a gagné l'ordre de lecture.

Les hooks nous ont plus aidés que prévu pour les échecs qui ne sont même pas des erreurs, juste des étapes qu'un humain oublie. Le nôtre est volontairement basique :

"SubagentStop": [
  {
    "matcher": "content-writer",
    "hooks": [
      {
        "type": "command",
        "command": "echo 'Content writer finished. Run /validate to check quality and SEO compliance.'"
      }
    ]
  }
]

Maintenant, la partie honnête. En écrivant cet article, on a grepé notre propre flotte et trouvé ceci encore présent dans translation-coordinator.md :

# .claude/agents/translation-coordinator.md
name: translation-coordinator
tools: Read, Write, Glob, Grep, Task
model: sonnet

Task, pas Agent. Ce champ est obsolète depuis la v2.1.63 et il n'a jamais échoué une seule fois, parce qu'Anthropic a conservé l'alias. On ne l'a pas encore nettoyé. Si vos propres fichiers d'agent disent encore Task, ils ne sont pas cassés, juste anciens, et l'alias fait discrètement le travail pour un grand nombre de repos en ce moment.

Une correction dans l'autre sens : les guides écrits avant v2.1.172 disent aux lecteurs qu'un subagent ne peut pas en lancer d'autres. Il le peut, et ce depuis cette version. La profondeur est fixée à cinq niveaux sous la conversation principale et n'est pas configurable, donc un subagent au niveau cinq ne reçoit tout simplement pas l'outil Agent.

Ce que coûtent les subagents, et quand ne pas en utiliser un

Chaque lancement de subagent crée une fenêtre de contexte neuve, donc la délégation n'est jamais gratuite. L'équipe d'ingénierie d'Anthropic rapporte que les agents utilisent environ 4x plus de tokens que les interactions par chat, et les systèmes multi-agents environ 15x plus, et que la seule consommation de tokens explique 80 % de la variance de performance qu'ils ont mesurée.

Nous n'avons pas nos propres mesures de tokens à ajouter, donc traitez tout multiplicateur précis que vous lisez sur ce sujet, y compris les chiffres de 4x à 7x qui circulent sur d'autres blogs, comme le chiffre de son auteur plutôt que comme un benchmark. L'article d'Anthropic sur son système de recherche multi-agents est ici la seule source avec de vraies données derrière elle, et cette même étude a constaté qu'un agent principal Opus avec des subagents Sonnet battait un agent Opus seul de 90,2 % sur leur évaluation interne. C'est ce résultat, pas le nombre de tokens, qui plaide pour la hiérarchisation.

Évitez le subagent quand le résultat a de toute façon sa place dans votre conversation principale, parce que vous ne ferez que le recopier et payer deux fois. Évitez-le pour les petites modifications où l'aller-retour de délégation coûte plus cher que de faire le travail vous-même. Et évitez-le quand la tâche a réellement besoin de l'historique de votre conversation : utilisez plutôt un fork, qui hérite de toute la conversation et réutilise le cache de prompt du parent, ce qui le rend moins cher qu'un subagent neuf pour une tâche annexe chargée en contexte. Le guide sur les coûts d'Anthropic et leur cadrage sur quand les utiliser arrivent tous deux à la même conclusion.

Le plafond de 200 par session vaut la peine d'être connu avant de concevoir un fan-out. C'est un vrai plafond contre la délégation incontrôlée, et le relever est un acte délibéré, pas un réglage par défaut.

À propos de l'auteur

Mert Batur construit chez Techsy, où l'équipe livre des agents IA, des systèmes d'automatisation et des pipelines voix/SDR pour des clients B2B. Il écrit sur la pile d'outils LLM et les Claude Skills que l'équipe Techsy utilise réellement en production.

Techsy — University of Birmingham · LinkedIn

Questions fréquentes

Que sont les subagents Claude Code ?

Les subagents Claude Code sont des assistants spécialisés qui tournent chacun dans sa propre fenêtre de contexte, avec un system prompt personnalisé, un accès restreint aux outils, et des permissions indépendantes. Vous en définissez un sous forme de fichier Markdown avec un frontmatter YAML dans .claude/agents/. Le subagent exécute une tâche annexe et ne renvoie que son résumé à votre conversation principale.

Claude Code utilise-t-il les subagents automatiquement ?

Oui. Claude lit le champ description de chaque subagent qui lui est disponible et délègue quand une tâche correspond, sans vous demander votre avis au préalable. Depuis v2.1.198, les subagents tournent en arrière-plan par défaut, si bien que le travail délégué se déroule souvent pendant que vous continuez à taper dans la conversation principale.

Où se trouvent les fichiers de subagent ?

Les subagents de projet vivent dans .claude/agents/ et les subagents utilisateur dans ~/.claude/agents/. Les deux emplacements sont scannés de façon récursive, donc les sous-dossiers ne posent pas de problème. L'identité vient uniquement du champ name du frontmatter, jamais du chemin. Les subagents managés, déployés par un administrateur, priment sur les définitions de projet ou d'utilisateur partageant le même nom.

Comment invoquer un subagent explicitement ?

Demandez-le par son nom dans votre prompt, par exemple « utilise le subagent validator sur ce brouillon ». L'invocation explicite contourne la correspondance de description qui pilote la délégation automatique, ce qui aide quand deux de vos subagents ont des descriptions qui se chevauchent et que Claude se trompe systématiquement.

Un subagent peut-il en lancer d'autres lui-même ?

Oui, depuis Claude Code v2.1.172. Les guides écrits avant cette version affirment que l'imbrication est impossible, et ils sont dépassés. La profondeur compte les niveaux sous la conversation principale et est fixée à cinq : un subagent au niveau cinq ne reçoit pas l'outil Agent. La limite n'est pas configurable.

Les subagents se souviennent-ils de quelque chose d'une session à l'autre ?

Seulement si vous définissez le champ memory. Il accepte user pour ~/.claude/agent-memory/<name>/, project pour .claude/agent-memory/<name>/, ou local pour .claude/agent-memory-local/<name>/. Sans ça, chaque invocation démarre à vide. Douze de nos dix-huit agents utilisent memory: project pour que leurs notes voyagent avec le contrôle de version.

Un subagent peut-il utiliser un modèle différent de celui de ma session ?

Oui. Réglez model dans le frontmatter sur haiku, sonnet, opus, ou un ID de modèle précis, et il remplace le modèle de votre session pour ce subagent. Notre flotte se répartit en six sur Opus, onze sur Sonnet et un sur Haiku, selon le niveau de jugement qu'exige la sortie de chaque agent.

Pourquoi mon nouveau subagent n'apparaît-il pas ?

Trois causes habituelles. Le répertoire agents n'existait pas au démarrage de la session, donc le watcher ne l'a jamais repéré : redémarrez Claude Code. Ou deux fichiers partagent le même name et un seul se charge. Ou rien dans votre liste tools ne se résout, ce qui, depuis v2.1.208, refuse le lancement avec une erreur de nommage.

Task est-il toujours un nom d'outil valide ?

Oui, comme alias. L'outil Task a été renommé Agent en v2.1.63, et les références Task(...) existantes fonctionnent toujours dans les settings et les définitions d'agent. Écrivez Agent dans les nouveaux fichiers. Notre propre translation-coordinator.md déclare encore Task, ce qu'on a découvert en écrivant cet article et qu'on n'a pas encore nettoyé.

Trois choses à retenir

Si vous montez votre première flotte, commencez ici. Le champ description décide de tout, car c'est ce que Claude lit pour choisir un agent, donc écrivez-le comme une règle de routage plutôt que comme un intitulé de poste. Concevez la passation sous forme de fichier avant de concevoir l'agent, puisqu'aucun subagent ne verra jamais le contexte d'un autre. Et placez chaque agent sur le modèle le moins cher capable de produire une réponse correcte, pour ne le monter en gamme que lorsque vous le surprenez en train de se tromper.

Explorez toute la bibliothèque pour voir les specs derrière ce pipeline.