AIDive

Pakiet do filmu

Trzy pliki subagentów Claude Code i eval fold test, który wyciął czwarty

7 min czytania

TL;DR i werdykt

Artykuł Anthropic o składaniu subagentów z powrotem w główną pętlę mówi, żeby używać ich mniej, a filmy zbudowane na nim mówią "usuń swoje subagenty". Artykuł nadal zostawia trzy przypadki i daje test na całą resztę s1. Ten pakiet to trzy pliki, które ten test przechodzą (zwiadowca do badań, recenzent tylko do odczytu, izolowany builder), czwarty plik, który przepuściliśmy przez test (autor testów), oraz skrypt, który go uruchomił.

  • Zwiadowca, recenzent i builder odpowiadają każdy na jeden przypadek do zachowania, a jego powód jest zapisany w description.
  • Czwarty agent, autor testów, przeszedł fold test: sześć zadań, po dwa przebiegi, raz jako subagent i raz złożony w skill. Złożony w skill zaliczył 12/12. Jako subagent zaliczył 11/12, przy 0.410 dolara na przebieg średnio wobec 0.262 oraz 72 sekundach wobec 36.
  • Autor testów stracił więc swój plik. Złożona wersja nigdy nie wypadła gorzej.

Werdykt: zostaw trzy pliki, a każdego innego agenta przepuść przez fold test, zanim dostanie plik. Odpuść zwiadowcę przy szybkich sprawdzeniach, nigdy nie wysyłaj buildera do kodu, który edytuje twoja główna sesja, i czytaj listę "niezweryfikowanego" od recenzenta równie uważnie jak jego werdykt. Ograniczenia są prawdziwe: dwanaście przebiegów na stronę na jednym repozytorium, a jedyne pudło subagenta to polecenie testowe, którego ustawienia naszego projektu nie dopuszczały. Uruchom to na własnym repozytorium.

Synteza ze źródłami

Artykuł zostawia subagenty na trzy przypadki. Używaj ich, gdy pojedyncza pętla agenta trafia na wymierny spadek wydajności przez puchnący kontekst, gdy wiele zadań biegnie równolegle w świeżych oknach kontekstu, które można wyrzucić, albo gdy pojedynczy agent ma trudność z wyborem właściwego narzędzia lub zmaga się ze sprzecznymi instrukcjami w prompcie systemowym s1.

Test składania. Zbuduj mały eval od końca do końca, złóż jednego subagenta i zostaw go jako subagenta tylko wtedy, gdy złożona wersja wypada gorzej, a potem powtórz s1. Artykuł jest pisany dla agentów Claude Platform i nie mówi o plikach Claude Code, więc stosujemy jego test przez analogię s1.

Jak podzielić, jeśli zostawiasz jednego. Dziel według kontekstu: daj każdemu subagentowi kawałek pracy, który potrzebuje niewiele od reszty systemu, i niech oddaje zwarty wynik s1. Dlatego zwiadowca ma kontrakt zwrotu, a recenzent kształt odpowiedzi.

Plik subagenta to plik Markdown z frontmatterem YAML. Wymagane są tylko name i description, a tools dziedziczy wszystkie narzędzia dostępne dla subagentów, jeśli je pominiesz s2. Agent tylko do odczytu musi więc wymieniać swoje narzędzia jawnie. Żeby recenzent nie uruchamiał pomocników, pomiń Agent na jego liście narzędzi albo dodaj go do disallowedTools s2.

Pliki piszesz ręcznie. Claude Code 2.1.198 usunął kreator /agents: poproś Claude o utworzenie lub zarządzanie subagentami albo edytuj .claude/agents/ bezpośrednio. Sprawił też, że subagenty domyślnie działają w tle s24 s3.

maxTurns i isolation: worktree robią to, czego potrzebuje builder. Gdy subagent dojdzie do limitu maxTurns, Claude Code zwraca jego wynik oznaczony jako częściowy s2. Izolacja worktree daje subagentowi izolowaną kopię repozytorium, domyślnie odgałęzioną od twojej domyślnej gałęzi, a nie od HEAD sesji nadrzędnej, a worktree jest sprzątany, jeśli subagent nic nie zmienił s2. Wersja 2.1.295 naprawiła pokazywanie subagentom we własnym powiązanym worktree gałęzi git sesji nadrzędnej s3. My pracowaliśmy na 2.1.294.

Odczyty się rozpraszają, zapisy zostają pojedyncze. Rozpraszaj przy odczytach, zostań przy jednym agencie przy zapisach s8. Dlatego pakiet ma jednego buildera i nigdy ekipę.

Rozproszenie kosztuje tokeny, a przy zwykłych wyszukiwaniach nie znajduje niczego więcej. Układy wieloagentowe zwykle zużywają 3 do 10 razy więcej tokenów niż podejścia z jednym agentem przy równoważnych zadaniach s4. W benchmarku z 288 przebiegami recall wynosił 97 do 100% w każdym warunku, a koszt na przebieg rósł o 74% do 116% na Haiku 5.5 i o 143% do 221% na Opus 5.5 s5. Zwiadowca się opłaca, gdy odczyt jest duży, a twoja sesja ma po nim jeszcze pracę.

Recenzent potrzebuje dowodów, inaczej wymyśla znaleziska. W jednym zgłoszeniu recenzent oznaczył poprawny kod, bo brakowało mu informacji o wersji, a główny agent przekazał znalezisko dalej bez weryfikacji s12. Nasz plik recenzenta odrzuca więc każde znalezisko bez zacytowanej linii. Recenzent, który kończy na zatwierdzaniu wszystkiego, też przestał działać s11, więc co jakiś czas sprawdź, czy twój nadal coś znajduje.

Foldery agentów gniją. Jeden programista zgłosił, że 16 zaimportowanych agentów przez dwa tygodnie ani razu nie wystartowało s10. Subagent w tle może też utknąć na prośbie o uprawnienie, jak pokazuje otwarte zgłoszenie o subagentach izolowanych w worktree s13.

Własny system badawczy Anthropic to rozproszenie. Pokazuje, gdzie równoległe odczyty się opłacają s14. Większość zadań programistycznych ma mniej naprawdę równoległych części niż badania.

Kod

Uwaga o instalacji: umieść pliki agentów w .claude/agents/ swojego projektu. Są wczytywane w ciągu kilku sekund od zapisu, chyba że katalog agents nie istniał, gdy sesja startowała, wtedy zrestartuj s2. Linia konwencji recenzenta (pieniądze w całkowitych groszach, funkcje domenowe nigdy nie mutują, błędy rzucane jako ValidationError, NotFoundError lub ConflictError) opisuje nasze przykładowe API do faktur: zastąp ją własnymi konwencjami.

Zwiadowca odpowiada na przypadek puchnącego kontekstu. Ma tylko Read, Grep i Glob, działa na taniem modelu haiku i zwraca najwyżej 12 linii: odpowiedź, dowód jako path:line i to, czego nie znalazł. Wrzuć go jako .claude/agents/scout.md i poproś o jednego zwiadowcę na każde niezależne pytanie, równolegle.

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

Recenzent odpowiada na przypadek weryfikacji świeżym okiem. Tylko Read, Grep i Glob, bez Agent, więc nie może ani edytować, ani uruchamiać pomocników. Daj mu specyfikację i diff (git diff main...<branch>) i zweryfikuj każde znalezisko sam, zanim zadziałasz. Wrzuć go jako .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

Builder odpowiada na przypadek osobnego komponentu. isolation: worktree daje mu własną kopię repozytorium i gałąź, a maxTurns: 40 zatrzymuje buildera kręcącego się w kółko. Daj mu jeden samodzielny kawałek, gdy sam pracujesz dalej, i merguj po zaliczeniu przez recenzenta. Wrzuć go jako .claude/agents/builder.md i zmień polecenia instalacji i testów na swoje.

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

Autor testów to czwarty plik, ten, który fold test usunął. Jest tu, żebyś mógł uruchomić na nim ten sam test albo użyć go jako szablonu dla agenta, którego zaraz dodasz. Jeśli go zostawisz, trafia do .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

Ustawienia projektu użyte w przebiegach. Builder i autor testów uruchamiają tylko to, na co pozwalają ustawienia, więc lista dozwolonych poleceń, której brakuje jakiegoś polecenia, może kosztować przebieg: tak wyglądało nasze jedyne pudło subagenta. Scal potrzebne linie z .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

Uprząż fold testu w czterech plikach. run-one.sh uruchamia jedno zadanie jako subagent albo złożone w skill, z tym samym promptem użytkownika. score.py stosuje regułę zaliczenia ustaloną z góry: zestaw zielony, żaden plik źródłowy bez zmian i wyłapany podłożony błąd. mutations.py trzyma po jednym podłożonym błędzie na moduł. jobs.txt wymienia sześć zadań, po dwa przebiegi, z naprzemiennymi wariantami. Ścieżki wskazują na nasz folder roboczy i nasze przykładowe moduły, więc zmień ścieżkę główną i mutacje na pasujące do twojego repozytorium, zanim je uruchomisz.

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 sprawdza najpierw mutacje: każda musi sprawić, że obecny zestaw oblewa, albo przetrwać, gdy powinna, zanim zaufasz evalowi.

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

Zrób to w poniedziałek

  • Uruchom claude --version i pamiętaj, że /agents jest tylko wskazówką od 2.1.198: pliki agentów tworzysz, edytując .claude/agents/ albo prosząc Claude s24.
  • Wypisz pliki agentów, które masz dziś, i zapisz powód zachowania każdego jednym zdaniem. Jeśli nie potrafisz, to kandydat do złożenia w skill.
  • Skopiuj scout.md i reviewer.md do .claude/agents/ i dopasuj linię konwencji recenzenta do swojego repozytorium.
  • Skopiuj builder.md, sprawdź, czy twoja lista dozwolonych poleceń obejmuje jego polecenia testów i sprawdzania typów, i daj mu jeden samodzielny kawałek pracy na gałęzi.
  • Zrób złoty zestaw 6 promptów dla agenta, w którego wątpisz, każdy z regułą zaliczenia ustaloną przed uruchomieniem: zielony zestaw, żaden plik źródłowy bez zmian, wyłapany podłożony błąd.
  • Uruchom baseline-kill.sh (dopasowany), żeby udowodnić, że każdy podłożony błąd oblewa obecny zestaw.
  • Uruchom każde zadanie dwa razy jako subagent, odłóż plik agenta na bok, wstaw te same instrukcje do skilla, uruchom każde zadanie jeszcze dwa razy i przeczytaj, które zadania zmieniły wynik, a nie tylko sam wynik.
  • Zostaw plik agenta tylko wtedy, gdy skill wypada gorzej. W przeciwnym razie go usuń.

Pomiary

Przebiegi odbyły się w Claude Code 2.1.294 z Opus 5.5 w dniu 2026-11-08. Są małe: dwanaście przebiegów na stronę na jednym repozytorium dla fold testu, dwa przebiegi na stronę dla zwiadowcy.

Fold test: autor testów, 6 zadań x 2 przebiegi x 2 warianty

Wariant Wywołany Zaliczone Średni koszt $ Średni czas s
agent 12/12 11/12 0.410 72
skill 12/12 12/12 0.262 36

Jedyne pudło: agent/router/2 zostawił czerwony test w test/router.test.ts ("matches the root path": expected null not to be null). Każdy przebieg wyłapał podłożoną mutację swojego modułu i żaden nie edytował src/.

Zwiadowca, mierzony na głównej sesji (mainCtx to rozmiar kontekstu głównej sesji, spawns liczba uruchomionych zwiadowców, durS czas trwania w sekundach)

Przebieg mainCtx spawns koszt $ durS tury
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

Wiersze "audit" to duży odczyt (jak każde wbudowane middleware dużego frameworka open source odrzuca żądanie). Pozostałe wiersze to trzy małe pytania. Przy małych pytaniach zwiadowca zaoszczędził prawie nic. Zwiadowcy działali na haiku.

Idź dalej

Agent Teams to inny mechanizm. Zespoły to sesje wysyłające do siebie wiadomości, za flagą eksperymentalną, i nic w tym pakiecie ich nie wymaga s3.

Rozproszenie kosztuje więcej niż czat. Własny system badawczy Anthropic mierzy koszt wieloagentowy względem czatu, a nie względem pojedynczego agenta, więc nie czytaj tej liczby jako subagentów wobec jednej pętli s14. Nasze porównanie z pojedynczym agentem to tabela zwiadowcy powyżej.

Subagent a skill, w jednej linii. Subagent startuje ze świeżym, izolowanym kontekstem; skill działa w twojej głównej rozmowie, gdzie sesja już zna repozytorium. Dlatego złożony autor testów był szybszy.

Forki i wznawianie. Fork dziedziczy całą rozmowę zamiast zaczynać od zera, a zatrzymanego subagenta można wznowić z pełną historią. Nie testowaliśmy żadnego z nich; przeczytaj dokumentację subagentów, zanim na nich polegasz s2.

Kilku builderów. Równoległe buildery piszące naraz wykraczały poza zakres. Zasada na start to "odczyty się rozpraszają, zapisy zostają pojedyncze" s8.

Agenci-persony. Architekt, product manager i inni agenci z schematu organizacyjnego to właśnie to, co test usuwa. Artykuł Anthropic ostrzega, że architektura agentów staje się kopią schematu organizacyjnego s1.

FAQ

Czy zwiadowca zawsze oszczędza kontekst? Nie. Przy naszych trzech małych pytaniach zaoszczędził prawie nic, a rozproszenie przy zwykłych wyszukiwaniach nie znalazło niczego więcej przy wyższym koszcie s5. Opłacił się przy dużym odczycie, gdzie główna sesja została mniejsza.

Dlaczego recenzent nie ma Edit ani Write? Żeby nie mógł naprawiać tego, co znajdzie, a pominięcie Agent powstrzymuje go od uruchamiania pomocników s2. Pominięcie tools dałoby mu wszystkie narzędzia, bo pominięte tools dziedziczy je wszystkie s2.

Worktree mojego buildera nie zawierał mojej niezacommitowanej pracy. Czy to błąd? Nie. Worktree jest domyślnie odgałęziony od twojej domyślnej gałęzi, a nie od miejsca, w którym jesteś s2. Zacommituj lub zmerguj wcześniej to, czego builder potrzebuje.

Autor testów przegrał na waszym repozytorium. Czy przegra na moim? Niekoniecznie. Uruchomiliśmy dwanaście przebiegów na stronę na jednym małym repozytorium, a jedyne pudło subagenta to polecenie testowe, którego nasze ustawienia nie dopuszczały. Uruchom uprząż na swoim i przeczytaj każdy przebieg, który zmienił wynik, tak jak zaleca artykuł s1.

Czy mogę sprawić, żeby recenzent czekał, zamiast działać w tle? Od 2.1.198 subagenty domyślnie działają w tle s24. Dokumentacja opisuje prośbę do Claude, żeby poczekał na raport, i ustawienie, które każe mu czekać; sprawdź dokumentację subagentów dla swojej wersji s2.

Pliki