TL;DR and verdict
Статья Anthropic о возвращении субагентов в основной цикл советует использовать их меньше, а видео по её мотивам говорят «удалите своих субагентов». При этом статья оставляет три случая и даёт тест для всего остального s1. В этом паке три файла, которые проходят тест (исследовательский скаут, ревьюер только для чтения, изолированный билдер), четвёртый файл, который мы прогнали через тест (автор тестов), и скрипт, которым мы это делали.
- Скаут, ревьюер и билдер отвечают каждый на один случай «оставить», и причина каждого записана в его
description. - Четвёртый агент, автор тестов, прошёл fold-тест: шесть задач, по два прогона, один раз как субагент и один раз влитым в скилл. Влитый в скилл он прошёл 12/12. Как субагент он прошёл 11/12, при 0.410 доллара за прогон в среднем против 0.262 и 72 секундах против 36.
- Так что автор тестов лишился своего файла. Влитая версия ни разу не оказалась хуже.
Вердикт: оставьте три файла и пропускайте каждого другого агента через fold-тест, прежде чем он получит файл. Не используйте скаута для быстрых справок, никогда не отправляйте билдера в код, который правит ваша основная сессия, и читайте список «непроверено» у ревьюера так же внимательно, как его вердикт. Ограничения настоящие: по двенадцать прогонов на сторону на одном репозитории, а единственный промах субагента был вызван тестовой командой, которую настройки нашего проекта не разрешали. Запустите это на своём репозитории.
Sourced synthesis
Статья оставляет субагентов для трёх случаев. Используйте их, когда один агентный цикл упирается в измеримое ухудшение из-за раздувания контекста, когда несколько задач идут параллельно в свежих контекстных окнах, которые можно выбросить, или когда одному агенту трудно выбрать правильный инструмент либо он сталкивается с противоречивыми инструкциями в системном промпте s1.
Тест на возврат в основной цикл. Соберите небольшой сквозной eval, влейте одного субагента и оставьте его как субагента, только если влитая версия набирает меньше, затем повторите s1. Статья написана для агентов Claude Platform и не говорит о файлах Claude Code, поэтому мы применяем её тест по аналогии s1.
Как делить, если вы оставляете одного. Делите по контексту: дайте каждому субагенту часть работы, которой мало нужно от остальной системы, и пусть он возвращает компактный результат s1. Поэтому у скаута есть контракт ответа, а у ревьюера форма ответа.
Файл субагента это Markdown-файл с YAML frontmatter. Обязательны только name и description, а tools, если его опустить, наследует все инструменты, доступные субагентам s2. Поэтому агент только для чтения должен перечислять свои инструменты явно. Чтобы ревьюер не запускал помощников, не включайте Agent в его список tools или добавьте его в disallowedTools s2.
Файлы вы пишете вручную. Claude Code 2.1.198 удалил мастер /agents: просите Claude создать субагентов или управлять ими, либо правьте .claude/agents/ напрямую. Он же сделал так, что субагенты по умолчанию работают в фоне s24 s3.
maxTurns и isolation: worktree делают то, что нужно билдеру. Когда субагент достигает лимита maxTurns, Claude Code возвращает его вывод с пометкой «частично» s2. Изоляция через worktree даёт субагенту изолированную копию репозитория, ответвлённую по умолчанию от вашей ветки по умолчанию, а не от HEAD родительской сессии, и worktree убирается, если субагент ничего не изменил s2. Версия 2.1.295 исправила ошибку, при которой субагентам в собственном связанном worktree показывалась git-ветка родительской сессии s3. Мы работали на 2.1.294.
Чтение идёт веером, запись остаётся одной. Параллельно для чтения, по одному для записи s8. Поэтому в паке один билдер и никогда бригада.
Параллельный запуск стоит токенов, а на обычном поиске не находит ничего нового. Мультиагентные схемы обычно используют в 3-10 раз больше токенов, чем подходы с одним агентом на равных задачах s4. В бенчмарке из 288 прогонов полнота была 97-100% во всех условиях, а стоимость прогона выросла на 74-116% на Haiku 5.5 и на 143-221% на Opus 5.5 s5. Скаут окупается, когда чтение большое и у вашей сессии есть ещё работа после него.
Ревьюеру нужны доказательства, иначе он выдумывает находки. В одном issue ревьюер пометил верный код, потому что ему не хватало сведений о версии, а основной агент передал находку дальше непроверенной s12. Поэтому наш файл ревьюера отказывается от любой находки без процитированной строки. Ревьюер, который в итоге одобряет всё, тоже перестал работать s11, так что время от времени проверяйте, что ваш всё ещё что-то находит.
Папки с агентами гниют. Один разработчик сообщил, что 16 импортированных агентов не запустились ни разу за две недели s10. Фоновый субагент также может зависнуть на запросе разрешения, как показывает открытый issue о субагентах с изоляцией через worktree s13.
Собственная исследовательская система Anthropic это параллельный запуск. Она показывает, где окупается параллельное чтение s14. В большинстве задач по коду по-настоящему параллелизуемых частей меньше, чем в исследовании.
Code
Заметка об установке: положите файлы агентов в .claude/agents/ вашего проекта. Они подхватываются через несколько секунд после сохранения, если только каталога agents не было при старте сессии, тогда перезапустите s2. Строка соглашений ревьюера (деньги в целых центах, доменные функции ничего не мутируют, ошибки бросаются как ValidationError, NotFoundError или ConflictError) описывает наш пример API для счетов: замените её своими соглашениями.
Скаут отвечает на случай раздувания контекста. У него только Read, Grep и Glob, он работает на дешёвой модели haiku и возвращает не больше 12 строк: ответ, доказательство в виде path:line и то, чего он не нашёл. Положите его как .claude/agents/scout.md и просите по одному скауту на независимый вопрос, параллельно.
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.
Ревьюер отвечает на случай проверки свежим взглядом. Только Read, Grep и Glob, без Agent, так что он не может ни править, ни запускать помощников. Дайте ему спецификацию и diff (git diff main...<branch>) и проверяйте каждую находку сами, прежде чем действовать. Положите его как .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.
Билдер отвечает на случай отдельного компонента. isolation: worktree даёт ему собственную копию репозитория и ветку, а maxTurns: 40 останавливает билдера, ходящего по кругу. Дайте ему один самостоятельный кусок, пока вы продолжаете работать, и сливайте после того, как ревьюер его пропустит. Положите его как .claude/agents/builder.md и замените команды установки и тестов своими.
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.
Автор тестов это четвёртый файл, тот, который убрал fold-тест. Он здесь, чтобы вы могли запустить на нём тот же тест или взять его как шаблон для агента, которого собираетесь добавить. Если оставите его, он лежит в .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.
Настройки проекта, использованные в прогонах. Билдер и автор тестов запускают только то, что разрешено настройками, так что список разрешений без нужной команды может стоить вам прогона: именно так случился наш единственный промах субагента. Перенесите нужные строки в .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
Обвязка fold-теста, четыре файла. run-one.sh запускает одну задачу как субагента или влитой в скилл, с тем же пользовательским промптом. score.py применяет критерий, решённый заранее: набор зелёный, ни один исходный файл не изменён и подложенный баг пойман. mutations.py содержит по одному подложенному багу на модуль. jobs.txt перечисляет шесть задач, по два прогона, с чередованием вариантов. Пути указывают на нашу рабочую папку и наши примерные модули, так что перед запуском поменяйте корневой путь и мутации под свой репозиторий.
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"
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"),
}))
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]"),
}
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
baseline-kill.sh сначала проверяет мутации: каждая должна ломать существующий набор тестов, либо выживать там, где должна, прежде чем вы начнёте доверять 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
Do this Monday
- Выполните
claude --versionи учтите, что/agentsсо времён 2.1.198 лишь указатель: файлы агентов вы создаёте, правя.claude/agents/или прося об этом Claude s24. - Перечислите файлы агентов, которые есть у вас сегодня, и запишите причину «оставить» для каждого одним предложением. Если не получается, он кандидат на влитие в скилл.
- Скопируйте
scout.mdиreviewer.mdв.claude/agents/и адаптируйте строку соглашений ревьюера под свой репозиторий. - Скопируйте
builder.md, проверьте, что ваш список разрешений покрывает его тестовые команды и проверку типов, и дайте ему один самостоятельный кусок работы на ветке. - Составьте золотой набор из 6 промптов для агента, в котором сомневаетесь, каждый с критерием прохождения, который вы фиксируете до запуска: набор зелёный, ни один исходный файл не изменён, подложенный баг пойман.
- Запустите
baseline-kill.sh(адаптированный), чтобы доказать, что каждый подложенный баг ломает текущий набор тестов. - Прогоните каждую задачу дважды как субагента, уберите файл агента в сторону, положите те же инструкции в скилл, прогоните каждую задачу дважды снова и посмотрите, какие задачи перевернулись, а не только итоговый счёт.
- Оставьте файл агента, только если скилл набирает меньше. Иначе удалите его.
Measurements
Прогоны шли на Claude Code 2.1.294 с Opus 5.5 2026-11-08. Они небольшие: по двенадцать прогонов на сторону на одном репозитории для fold-теста и по два прогона на сторону для скаута.
Fold-тест: автор тестов, 6 задач x 2 прогона x 2 варианта
| Вариант | Вызван | Прошёл | Средняя стоимость $ | Среднее время с |
|---|---|---|---|---|
| agent | 12/12 | 11/12 | 0.410 | 72 |
| skill | 12/12 | 12/12 | 0.262 | 36 |
Единственный провал: agent/router/2 оставил красный тест в test/router.test.ts ("matches the root path": expected null not to be null). Каждый прогон убил подложенную мутацию своего модуля, и ни один прогон не правил src/.
Скаут, измерено на основной сессии (mainCtx это размер контекста основной сессии, spawns число запущенных скаутов, durS длительность в секундах)
| Run | mainCtx | spawns | cost $ | durS | turns |
|---|---|---|---|---|---|
| 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 |
Строки «audit» это большое чтение (как каждый встроенный middleware большого open source фреймворка отклоняет запрос). Остальные строки это три небольших вопроса. На небольших вопросах скаут почти ничего не сэкономил. Скауты работали на haiku.
Go further
Agent Teams это другой механизм. Teams это сессии, которые пишут друг другу сообщения, за экспериментальным флагом, и ничто в этом паке в них не нуждается s3.
Параллельный запуск стоит дороже обычного чата. Собственная исследовательская система Anthropic сравнивает свою мультиагентную стоимость с чатом, а не с одним агентом, поэтому не читайте эту цифру как «субагенты против одного цикла» s14. Наше сравнение с одним агентом это таблица скаута выше.
Субагент против скилла, в одну строку. Субагент стартует со свежим изолированным контекстом, а скилл работает в вашем основном разговоре, где сессия уже знает репозиторий. Поэтому влитый автор тестов был быстрее.
Форки и возобновление. Форк наследует весь разговор вместо старта с чистого листа, а остановленного субагента можно возобновить с полной историей. Мы не тестировали ни то ни другое: прочитайте документацию по субагентам, прежде чем на это полагаться s2.
Несколько билдеров. Параллельные билдеры, пишущие одновременно, были вне рамок. Правило, с которого стоит начать, это «чтение идёт веером, запись остаётся одной» s8.
Агенты-персоны. Архитектор, продакт-менеджер и другие агенты по оргструктуре это то, что тест убирает. Статья Anthropic предупреждает, что архитектура агентов становится копией оргструктуры s1.
FAQ
Всегда ли скаут экономит контекст? Нет. На наших трёх небольших вопросах он почти ничего не сэкономил, а параллельный запуск на обычном поиске не нашёл ничего нового при более высокой цене s5. Он окупился на большом чтении, где основная сессия осталась меньше.
Почему у ревьюера нет Edit и Write?
Чтобы он не мог исправлять найденное, а отсутствие Agent не даёт ему запускать помощников s2. Если опустить tools, он получит все инструменты, потому что пропущенный tools наследует их все s2.
В worktree моего билдера не оказалось моей незакоммиченной работы. Это баг? Нет. Worktree по умолчанию ответвляется от вашей ветки по умолчанию, а не оттуда, где вы находитесь s2. Сначала закоммитьте или слейте то, что нужно билдеру.
Автор тестов проиграл на вашем репозитории. Проиграет ли он на моём? Возможно, нет. Мы сделали по двенадцать прогонов на сторону на одном небольшом репозитории, а единственный промах субагента был вызван тестовой командой, которую наши настройки не разрешали. Запустите обвязку на своём и прочитайте каждый прогон, где результат перевернулся, как рекомендует статья s1.
Можно ли сделать так, чтобы ревьюер ждал, а не работал в фоне? С версии 2.1.198 субагенты по умолчанию работают в фоне s24. Документация описывает просьбу к Claude дождаться отчёта и настройку, которая заставляет его ждать; проверьте документацию по субагентам для вашей версии s2.
AIDive