AIDive

Pack vidéo

Trois fichiers de subagent Claude Code et l'eval du fold test qui en a coupé un quatrième

7 min de lecture

TL;DR et verdict

L'article d'Anthropic sur le repli des subagents dans la boucle principale vous dit d'en utiliser moins, et les vidéos qui s'en inspirent disent « supprimez vos subagents ». L'article garde pourtant trois cas et vous donne un test pour tout le reste s1. Ce pack contient les trois fichiers qui passent ce test (un scout de recherche, un reviewer en lecture seule, un builder isolé), le quatrième fichier que nous avons passé au test (un rédacteur de tests) et le script qui l'a fait tourner.

  • Le scout, le reviewer et le builder répondent chacun à un cas à garder, et chacun a sa raison écrite dans sa description.
  • Le quatrième agent, un rédacteur de tests, est passé par le fold test : six tâches, deux exécutions chacune, une fois en subagent et une fois replié dans un skill. Replié dans un skill, il a réussi 12/12. En subagent, il a réussi 11/12, à 0,410 dollar par exécution en moyenne contre 0,262, et 72 secondes contre 36.
  • Le rédacteur de tests a donc perdu son fichier. La version repliée n'a jamais fait moins bien.

Verdict : gardez les trois fichiers, et passez tout autre agent au fold test avant de lui donner un fichier. Évitez le scout pour les recherches rapides, n'envoyez jamais le builder sur du code que votre session principale modifie, et lisez la liste « unverified » du reviewer aussi attentivement que son verdict. Les limites sont réelles : douze exécutions par côté sur un seul dépôt, et l'unique échec du subagent venait d'une commande de test que les réglages de notre projet n'autorisaient pas. Lancez-le sur votre propre dépôt.

Synthèse sourcée

L'article garde les subagents pour trois cas. Utilisez-les quand une boucle d'agent unique subit une dégradation mesurable des performances à cause d'un contexte qui gonfle, quand plusieurs tâches tournent en parallèle dans des fenêtres de contexte neuves que l'on peut jeter, ou quand un agent unique peine à choisir le bon outil ou fait face à des instructions contradictoires dans le prompt système s1.

Le test de repli. Construisez un petit eval de bout en bout, repliez un subagent, et ne le gardez comme subagent que si la version repliée obtient un moins bon score, puis recommencez s1. L'article est écrit pour les agents de Claude Platform et ne parle pas des fichiers de Claude Code, nous appliquons donc son test par analogie s1.

Comment découper si vous en gardez un. Divisez par contexte : donnez à chaque subagent un morceau de travail qui a peu besoin du reste du système et faites-lui rendre un résultat compact s1. C'est pourquoi le scout porte un contrat de retour et le reviewer une forme de réponse.

Un fichier de subagent est un fichier Markdown avec un frontmatter YAML. Seuls name et description sont obligatoires, et tools hérite de tous les outils disponibles pour les subagents s'il est omis s2. Un agent en lecture seule doit donc lister ses outils explicitement. Pour empêcher un reviewer de lancer des assistants, omettez Agent de sa liste d'outils ou ajoutez-le à disallowedTools s2.

Vous écrivez les fichiers à la main. Claude Code 2.1.198 a supprimé l'assistant /agents : demandez à Claude de créer ou de gérer les subagents, ou modifiez directement .claude/agents/. Cette version a aussi fait tourner les subagents en arrière-plan par défaut s24 s3.

maxTurns et isolation: worktree font ce dont le builder a besoin. Quand le subagent atteint la limite maxTurns, Claude Code renvoie sa sortie marquée comme partielle s2. L'isolation par worktree donne au subagent une copie isolée du dépôt, créée par défaut à partir de votre branche par défaut plutôt que du HEAD de la session parente, et le worktree est nettoyé si le subagent ne fait aucune modification s2. La version 2.1.295 a corrigé l'affichage de la branche git de la session parente aux subagents placés dans leur propre worktree lié s3. Nous avons travaillé sur la 2.1.294.

Les lectures se répartissent, les écritures restent uniques. Fan-out pour les lectures, un seul agent pour les écritures s8. C'est pourquoi le pack contient un seul builder et jamais une équipe.

Le fan-out coûte des tokens, et sur des recherches ordinaires il ne trouve rien de plus. Les montages multi-agents consomment typiquement 3 à 10 fois plus de tokens que les approches à agent unique pour des tâches équivalentes s4. Dans un benchmark de 288 exécutions, le rappel était de 97 à 100 % dans toutes les conditions, et le coût par exécution a augmenté de 74 % à 116 % sur Haiku 5.5 et de 143 % à 221 % sur Opus 5.5 s5. Le scout rapporte quand la lecture est grosse et que votre session a encore du travail ensuite.

Un reviewer a besoin de preuves, sinon il invente des constats. Dans un ticket, un reviewer a signalé du code correct faute d'information sur la version, et l'agent principal a relayé le constat sans le vérifier s12. Notre fichier de reviewer refuse donc tout constat sans ligne citée. Un reviewer qui finit par tout approuver a aussi cessé de travailler s11 : vérifiez de temps en temps que le vôtre trouve encore quelque chose.

Les dossiers d'agents pourrissent. Un développeur a rapporté que 16 agents importés n'ont jamais été lancés en deux semaines s10. Un subagent en arrière-plan peut aussi se bloquer sur une demande de permission, comme le montre le ticket ouvert sur les subagents isolés par worktree s13.

Le système de recherche d'Anthropic est un fan-out. Il montre où les lectures parallèles rapportent s14. La plupart des tâches de code ont moins de parties réellement parallélisables que la recherche.

Code

Note d'installation : placez les fichiers d'agent dans .claude/agents/ de votre projet. Ils sont pris en compte quelques secondes après leur enregistrement, sauf si le dossier agents n'existait pas au démarrage de la session, auquel cas redémarrez s2. La ligne de conventions du reviewer (argent en centimes entiers, fonctions du domaine qui ne mutent jamais, erreurs levées sous forme de ValidationError, NotFoundError ou ConflictError) décrit notre exemple d'API de facturation : remplacez-la par vos propres conventions.

Le scout répond au cas du contexte qui gonfle. Il n'a que Read, Grep et Glob, tourne sur le modèle bon marché haiku, et renvoie au plus 12 lignes : la réponse, la preuve sous forme de path:line, et ce qu'il n'a pas trouvé. Placez-le dans .claude/agents/scout.md et demandez un scout par question indépendante, en parallèle.

scout.md

---
name: scout
description: Read-only researcher for one question about this codebase that needs many files read but only a short answer back. Use proactively, one scout per independent question, in parallel.
tools: Read, Grep, Glob
model: haiku
---
You answer one question about this codebase. Read what you need. Never edit anything.

Return at most 12 lines:
1. The answer, in plain words, first.
2. The proof: the files and lines that show it, as path:line.
3. What you did not find or are not sure of.

No code block longer than 5 lines.

scout.md on GitHub

Le reviewer répond au cas de la vérification à regard neuf. Read, Grep et Glob seulement, pas d'Agent, donc il ne peut ni modifier ni lancer d'assistants. Donnez-lui la spec et le diff (git diff main...<branch>), et vérifiez vous-même chaque constat avant d'agir. Placez-le dans .claude/agents/reviewer.md.

reviewer.md

---
name: reviewer
description: Read-only code reviewer. Use after a change is built, with the spec and the diff in the prompt. Returns a verdict with file:line evidence. Never edits.
tools: Read, Grep, Glob
model: sonnet
---
You review one change against its spec. The spec and the diff are in your prompt; read the surrounding code you need to judge them.

Look for what breaks: wrong behaviour against the spec, an edge case the code or its tests miss, a broken convention of this repo (money in integer cents, domain functions never mutate, errors thrown as ValidationError, NotFoundError or ConflictError).

Answer in this shape, nothing else:
VERDICT: PASS or FAIL
FINDINGS (most serious first, at most 5):
- [high|medium|low] path:line - what breaks, and the line that proves it, quoted
UNVERIFIED:
- anything you suspect but could not prove from the code

No style remarks. No finding without a quoted line.

reviewer.md on GitHub

Le builder répond au cas du composant séparé. isolation: worktree lui donne sa propre copie du dépôt et sa branche, et maxTurns: 40 arrête un builder qui tourne en rond. Donnez-lui un morceau autonome pendant que vous continuez à travailler, puis fusionnez après la réussite du reviewer. Placez-le dans .claude/agents/builder.md et remplacez les commandes d'installation et de test par les vôtres.

builder.md

---
name: builder
description: Builds one self-contained component with a clean interface, tests included, in its own git worktree. Use when a separate piece can be built while the main session keeps working. Never for changes to code the main session is editing.
isolation: worktree
maxTurns: 40
model: inherit
---
You build exactly the component in your prompt, in this worktree, and nothing else.

1. Run `git branch --show-current` and `git rev-parse --show-toplevel` and report both.
2. If node_modules is missing, run `pnpm install --frozen-lockfile`.
3. Write the code and its tests. Follow the conventions in README.md.
4. Run `pnpm test` and `pnpm typecheck` until both are green.
5. Commit on your branch with a one-line message.

Report in at most 10 lines: branch, files changed, test count before and after, anything you did not do.

builder.md on GitHub

Le rédacteur de tests est le quatrième fichier, celui que le fold test a supprimé. Il est là pour que vous puissiez lui appliquer le même test, ou le prendre comme modèle pour l'agent que vous allez ajouter. Si vous le gardez, il va dans .claude/agents/test-writer.md.

test-writer.md

---
name: test-writer
description: Writes vitest tests for one module of this repo. Use proactively when the user asks to add or improve tests for a file or module.
tools: Read, Grep, Glob, Edit, Write, Bash
model: inherit
---
You write tests for exactly one module.

1. Read the module and the code that calls it. Read the existing test file for it, if any.
2. Add the missing cases to the test file under test/ (create it if none exists): boundaries, empty and invalid input, every branch, and anything the code promises in a comment.
3. Never edit files under src/. If a test reveals a bug, keep the test, mark it `it.fails`, and say so.
4. Run `pnpm test` until the suite is green.

Report in at most 6 lines: the test file, the cases added, the test count before and after.

test-writer.md on GitHub

Les réglages de projet utilisés pour les exécutions. Le builder et le rédacteur de tests ne lancent que ce que les réglages autorisent : une liste d'autorisations qui oublie une commande peut vous coûter une exécution, et c'est ainsi que s'est produit notre unique échec de subagent. Fusionnez les lignes dont vous avez besoin dans .claude/settings.json.

ledgerly-settings.json

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)", "Bash(pnpm test:*)", "Bash(pnpm typecheck)", "Bash(pnpm install:*)",
      "Bash(npx vitest:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
      "Bash(git add:*)", "Bash(git commit:*)", "Bash(git branch:*)", "Bash(git rev-parse:*)", "Bash(git worktree list)",
      "Edit", "Write"
    ]
  }
}

ledgerly-settings.json on GitHub

Le harnais du fold test, en quatre fichiers. run-one.sh lance une tâche en subagent ou repliée dans un skill, avec le même prompt utilisateur. score.py applique la règle de réussite fixée d'avance : suite verte, aucun fichier source modifié, et bug planté détecté. mutations.py contient un bug planté par module. jobs.txt liste les six tâches, deux exécutions chacune, avec des variantes en alternance. Les chemins pointent vers notre dossier de travail et nos modules d'exemple : changez le chemin racine et les mutations pour qu'ils correspondent à votre dépôt avant de les lancer.

run-one.sh

#!/bin/bash
# One fold-test run: run-one.sh <variant agent|skill> <task> <n>
# Copies ledgerly, sets up the variant, sends the same user prompt, scores the result.
set -u
V=$1; T=$2; N=$3
ROOT=/private/tmp/subagents-bench
W=$ROOT/eval/runs/$V-$T-$N
rm -rf "$W"; mkdir -p "$W"; cp -R "$ROOT/ledgerly/." "$W/"
cd "$W"
if [ "$V" = skill ]; then
  # Fold: the subagent's prompt becomes a skill in the main loop; the agent file moves aside
  mkdir -p .claude/skills/test-writer
  BODY=$(awk 'f>=2{print} /^---$/{f++}' .claude/agents/test-writer.md)
  { printf -- '---\nname: test-writer\ndescription: Write vitest tests for one module of this repo. Use when the user asks to add or improve tests for a file or module.\n---\n'; printf '%s\n' "$BODY"; } > .claude/skills/test-writer/SKILL.md
  git mv .claude/agents/test-writer.md .claude/test-writer.agent.md.aside
  git add -A .claude && git commit -qm "eval: fold test-writer into a skill"
fi
FILE=$(python3 -c "import sys;sys.path.insert(0,'$ROOT/eval');from mutations import MUTATIONS;print(MUTATIONS['$T'][0])")
START=$(date +%s)
claude -p "Add tests for $FILE." --model opus --setting-sources project,local \
  --output-format stream-json --verbose --permission-mode acceptEdits > run.jsonl 2> run.err
END=$(date +%s)
# Score
SRC_CHANGED=$(git status --porcelain -- src | wc -l | tr -d ' ')
npx vitest run > after.txt 2>&1 && GREEN=1 || GREEN=0
TESTS=$(grep -Eo 'Tests +[0-9]+ passed' after.txt | grep -Eo '[0-9]+' | head -1)
python3 - "$W" "$T" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]; f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read(); open(p, "w").write(s.replace(old, new))
PY
npx vitest run > mutant.txt 2>&1 && KILLED=0 || KILLED=1
git checkout -q -- "$FILE"
python3 "$ROOT/eval/score.py" "$W" "$V" "$T" "$N" "$SRC_CHANGED" "$GREEN" "${TESTS:-0}" "$KILLED" "$((END-START))" >> "$ROOT/eval/results.jsonl"
tail -1 "$ROOT/eval/results.jsonl"

run-one.sh on GitHub

score.py

# Parse one run's stream-json and write a result row
import json, sys
w, v, t, n, src_changed, green, tests, killed, wall = sys.argv[1:]
delegated = skill = False
result = {}
for line in open(f"{w}/run.jsonl"):
    try: e = json.loads(line)
    except Exception: continue
    if e.get("type") == "assistant":
        for b in e["message"].get("content", []):
            if b.get("type") == "tool_use":
                i = b.get("input", {})
                if b["name"] in ("Agent", "Task") and i.get("subagent_type") == "test-writer": delegated = True
                if b["name"] == "Skill" and "test-writer" in json.dumps(i): skill = True
    if e.get("type") == "result": result = e
passed = int(src_changed) == 0 and green == "1" and killed == "1"
print(json.dumps({
    "variant": v, "task": t, "run": int(n),
    "invoked": delegated if v == "agent" else skill,
    "pass": passed, "green": green == "1", "srcChanged": int(src_changed), "killed": killed == "1",
    "tests": int(tests), "wallSec": int(wall),
    "costUsd": result.get("total_cost_usd"), "durationMs": result.get("duration_ms"), "turns": result.get("num_turns"),
    "usage": result.get("usage"), "modelUsage": result.get("modelUsage"), "isError": result.get("is_error"),
}))

score.py on GitHub

mutations.py

# One planted mutation per golden task: (task id, file, old, new)
MUTATIONS = {
  "money":      ("src/domain/money.ts", "if (value < min) {", "if (value <= min) {"),
  "customer":   ("src/domain/customer.ts", "name.trim() === \"\"", "name === \"\""),
  "invoice":    ("src/domain/invoice.ts", 'invoice.dueDate < now.toISOString()', 'invoice.dueDate <= now.toISOString()'),
  "validation": ("src/domain/validation.ts", "quantity < 1", "quantity < 0"),
  "migrations": ("src/store/migrations.ts", "{ customer: 0, invoice: 0, invoiceNumber: 0 }", "{ customer: 0, invoice: 0, invoiceNumber: 1 }"),
  "router":     ("src/http/router.ts", "decodeURIComponent(m[i + 1])", "m[i + 1]"),
}

mutations.py on GitHub

jobs.txt

skill money 1
agent customer 1
skill customer 1
agent invoice 1
skill invoice 1
agent validation 1
skill validation 1
agent migrations 1
skill migrations 1
agent router 1
skill router 1
agent money 2
skill money 2
agent customer 2
skill customer 2
agent invoice 2
skill invoice 2
agent validation 2
skill validation 2
agent migrations 2
skill migrations 2
agent router 2
skill router 2

jobs.txt on GitHub

baseline-kill.sh vérifie d'abord les mutations : chacune doit faire échouer la suite existante, ou survivre quand elle le doit, avant que vous fassiez confiance à l'eval.

baseline-kill.sh

#!/bin/bash
# For each mutation: apply on a scratch copy of ledgerly, run the suite, report killed/survived
set -u
SRC=/private/tmp/subagents-bench/ledgerly
for t in money customer invoice validation migrations router; do
  W=$(mktemp -d /private/tmp/subagents-bench/eval/mut-XXXX); cp -R "$SRC/." "$W/"
  python3 - "$W" "$t" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]
f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read()
assert s.count(old) == 1, (t, s.count(old)); open(p, "w").write(s.replace(old, new))
PY
  (cd "$W" && npx vitest run >/dev/null 2>&1) && echo "$t survived" || echo "$t killed"
  rm -rf "$W"
done

baseline-kill.sh on GitHub

À faire lundi

  • Lancez claude --version, et notez que /agents n'est qu'un renvoi depuis la 2.1.198 : vous créez les fichiers d'agent en modifiant .claude/agents/ ou en le demandant à Claude s24.
  • Listez les fichiers d'agent que vous avez aujourd'hui, et écrivez la raison de garder chacun en une phrase. Si vous n'y arrivez pas, c'est un candidat au repli dans un skill.
  • Copiez scout.md et reviewer.md dans .claude/agents/, et adaptez la ligne de conventions du reviewer à votre dépôt.
  • Copiez builder.md, vérifiez que votre liste d'autorisations couvre ses commandes de test et de vérification de types, et donnez-lui un morceau de travail autonome sur une branche.
  • Constituez un golden set de 6 prompts pour l'agent dont vous doutez, chacun avec une règle de réussite fixée avant de lancer : suite verte, aucun fichier source modifié, un bug planté détecté.
  • Lancez baseline-kill.sh (adapté) pour prouver que chaque bug planté fait échouer la suite actuelle.
  • Lancez chaque tâche deux fois en subagent, mettez le fichier d'agent de côté, placez les mêmes instructions dans un skill, relancez chaque tâche deux fois, et lisez quelles tâches ont basculé, pas seulement le score.
  • Ne gardez le fichier d'agent que si le skill obtient un moins bon score. Sinon, supprimez-le.

Mesures

Les exécutions ont eu lieu sur Claude Code 2.1.294 avec Opus 5.5 le 2026-11-08. Elles sont petites : douze exécutions par côté sur un seul dépôt pour le fold test, deux exécutions par côté pour le scout.

Fold test : rédacteur de tests, 6 tâches x 2 exécutions x 2 variantes

Variante Invoqué Réussite Coût moyen $ Durée moyenne s
agent 12/12 11/12 0.410 72
skill 12/12 12/12 0.262 36

Le seul échec : agent/router/2 a laissé un test rouge dans test/router.test.ts ("matches the root path": expected null not to be null). Chaque exécution a tué la mutation plantée de son module, et aucune n'a modifié src/.

Scout, mesuré sur la session principale (mainCtx est la taille du contexte de la session principale, spawns le nombre de scouts lancés, durS la durée en secondes)

Exécution mainCtx spawns coût $ durS tours
audit-inline-1 45868 0 0.457 55 15
audit-inline-2 47476 0 0.433 47 12
audit-scout-1 30505 3 0.267 17 1
audit-scout-2 33937 3 0.344 25 3
inline-1 32294 0 0.273 29 7
inline-2 33345 0 0.272 36 10
scout-1 28966 3 0.223 18 1
scout-2 30390 3 0.257 20 2

Les lignes « audit » correspondent à la grosse lecture (comment chaque middleware intégré d'un grand framework open source rejette une requête). Les autres lignes sont trois petites questions. Sur les petites questions, le scout n'a presque rien fait gagner. Les scouts tournaient sur haiku.

Pour aller plus loin

Les Agent Teams sont un mécanisme différent. Les teams sont des sessions qui s'envoient des messages, derrière un flag expérimental, et rien dans ce pack n'en a besoin s3.

Le fan-out coûte plus cher qu'un chat. Le système de recherche d'Anthropic mesure son coût multi-agent par rapport à un chat, pas par rapport à un agent unique : ne lisez donc pas ce chiffre comme subagents contre une boucle unique s14. Notre comparaison avec un agent unique est le tableau du scout ci-dessus.

Subagent contre skill, en une ligne. Un subagent démarre avec un contexte neuf et isolé ; un skill tourne dans votre conversation principale, où la session connaît déjà le dépôt. C'est pourquoi le rédacteur de tests replié était plus rapide.

Forks et reprise. Un fork hérite de toute la conversation au lieu de repartir de zéro, et un subagent arrêté peut être repris avec tout son historique. Nous n'avons testé ni l'un ni l'autre ; lisez la documentation des subagents avant de vous y fier s2.

Plusieurs builders. Des builders parallèles qui écrivent en même temps étaient hors périmètre. La règle de départ est « les lectures se répartissent, les écritures restent uniques » s8.

Agents persona. Architecte, product manager et autres agents calqués sur l'organigramme sont ce que le test supprime. L'article d'Anthropic prévient que l'architecture d'agents devient une copie de l'organigramme s1.

FAQ

Le scout fait-il toujours gagner du contexte ? Non. Sur nos trois petites questions, il n'a presque rien fait gagner, et le fan-out sur des recherches ordinaires n'a rien trouvé de plus pour un coût plus élevé s5. Il a rapporté sur la grosse lecture, où la session principale est restée plus légère.

Pourquoi le reviewer n'a-t-il ni Edit ni Write ? Pour qu'il ne puisse pas corriger ce qu'il trouve, et omettre Agent l'empêche de lancer des assistants s2. Laisser tools de côté lui donnerait tous les outils, car un tools omis les hérite tous s2.

Le worktree de mon builder ne contenait pas mon travail non commité. Est-ce un bug ? Non. Le worktree part par défaut de votre branche par défaut, pas de l'endroit où vous êtes s2. Commitez ou fusionnez d'abord ce dont le builder a besoin.

Le rédacteur de tests a perdu sur votre dépôt. Perdra-t-il sur le mien ? Pas forcément. Nous avons fait douze exécutions par côté sur un seul petit dépôt, et l'unique échec du subagent venait d'une commande de test que nos réglages n'autorisaient pas. Lancez le harnais sur le vôtre et lisez toute exécution qui bascule, comme le recommande l'article s1.

Puis-je faire attendre le reviewer au lieu de le laisser tourner en arrière-plan ? Les subagents tournent en arrière-plan par défaut depuis la 2.1.198 s24. La documentation décrit comment demander à Claude d'attendre son rapport, et un réglage qui le fait attendre ; consultez la documentation des subagents pour votre version s2.

Fichiers