Субагенты Claude Code: файлы, frontmatter, инструменты и полные примеры

Введение

Субагент — отдельный воркер со своим контекстным окном, своим системным промптом, своим списком инструментов и своей моделью. Claude запускает его, когда побочная задача завалила бы основной разговор результатами поиска, логами или содержимым файлов, а субагент возвращает только сводку. Вы получаете три выигрыша сразу: основной контекст остаётся чистым, ограничения держатся списками инструментов, а не вежливыми просьбами, и дешёвые модели могут делать дешёвую работу.

Типичное разделение повторяет модель ролей: дешёвый triage и исследование на небольших моделях, стандартная реализация в основной сессии и строгий ревьюер на Opus, который никогда не правит. Написать файлы — простая часть; эта страница описывает поля, ограничения и режимы отказа, от которых зависит, будут ли роли вообще работать.

Где живут субагенты

Субагент — это файл Markdown с frontmatter YAML. Расположение решает, кому он достаётся и кто побеждает при совпадении имён:

РасположениеОбластьПриоритет
.claude/agents/Этот проект, коммитится для команды3
~/.claude/agents/Все ваши проекты4
флаг CLI --agentsТолько текущая сессия, JSON в командной строке2
Управляемые настройкиНа всю организацию, разворачивают администраторы1
agents/ плагинаВезде, где включён плагин5

Каталоги проекта и пользователя сканируются рекурсивно, поэтому раскладывайте файлы по папкам вроде agents/review/; подкаталог не меняет id, потому что идентичность задаёт name во frontmatter. Держите имена уникальными внутри одного каталога: из двух файлов с одним именем загрузится только один, в порядке файловой системы. Во вложенных каталогах проекта побеждает определение, ближайшее к рабочему каталогу. Каталоги, добавленные через --add-dir или /add-dir, тоже отдают свои файлы .claude/agents/ для этой сессии.

Устройство файла

Frontmatter настраивает воркера; тело Markdown становится его системным промптом. Обязательны только name и description. Пример файла .claude/agents/code-reviewer.md:

mkdir -p .claude/agents

vi .claude/agents/code-reviewer.md

--- name: code-reviewer description: Reviews changes for correctness, security and missing tests. Use after every code change. tools: Read, Grep, Glob model: opus color: red --- You are a strict reviewer. Report findings in severity order, each with file and line, then a verdict: ship, fix first, or block. Never edit files.

Поля, которые важны на практике:

Поле с опечаткой игнорируется без ошибки — это самый частый молчаливый отказ. Запустите claude --debug и поищите в журнале отладки does not recognize or apply, когда поле вроде бы ничего не делает.

Как их вызывают

Claude читает описания субагентов и делегирует автоматически, когда задача совпадает. Можно попросить и явно: Use the code-reviewer subagent on my staged changes. Внутри основная сессия вызывает инструмент Agent (до v2.1.63 он назывался Task); в транскрипте появляется строка субагента и его задачи.

Субагенты работают внутри текущей сессии. Они могут запускать своих субагентов, пока позволяет предел глубины; на пределе инструмент Agent убирается у этого воркера. Запущенные субагенты и модель каждого из них показывает /tasks. Завершённого субагента можно продолжить для доработки, вместо того чтобы прогонять задачу заново.

Инструменты и ограничения

Список инструментов — это настоящий контракт. Ревьюер только для чтения, который не может править, писать или запускать shell, не повредит репозиторий, что бы ни говорил промпт. Вот этот умеет только читать и искать, файл .claude/agents/safe-researcher.md:

vi .claude/agents/safe-researcher.md

--- name: safe-researcher description: Research agent with restricted capabilities tools: Read, Grep, Glob ---

Форма с denylist наследует всё, кроме перечисленных инструментов: это удобно, но шире, файл .claude/agents/no-writes.md:

vi .claude/agents/no-writes.md

--- name: no-writes description: Inherits the available tools except file writes disallowedTools: Write, Edit ---

Фильтры применяются до вашего списка: часть инструментов до субагента не доходит (AskUserQuestion, EnterPlanMode, ScheduleWakeup, WaitForMcpServers, Workflow, EndConversation), а фоновые субагенты сохраняют только рабочий набор встроенных инструментов — Read, Grep, Glob, LSP, Bash, Edit, Write, WebFetch, WebSearch, TodoWrite, Skill и ещё несколько. Поэтому одно и то же определение может дать разные инструменты на переднем плане и в фоне. Если не разрешается ничего, субагент отказывается запускаться с ошибкой, где перечислены эти записи.

Доступ к MCP следует той же идее. Перечислите целые серверы в disallowedTools (mcp__github), чтобы их отнять, или определите серверы прямо в mcpServers, чтобы их инструменты существовали только внутри субагента и не стоили контекста родителю. Встроенный сервер из файла проектного агента загружается только после того, как вы доверитесь папке.

Модели и стоимость

Маршрутизируйте по весу задачи. Запросы субагентов идут в те же лимиты использования, что и основной разговор, поэтому исследователь на дешёвой модели окупает себя, а дорогая модель остаётся на финальный вердикт.

РаботаПоле modelПочему
Поиск, triage, сводкиhaikuБыстро и дёшево; инструменты только для чтения.
Реализация, тестыsonnet или модель сессии по наследствуСбалансированное качество для рутинных правок.
Ревью, архитектура, сложные багиopus или claude-opus-5-5Лучшее рассуждение для последних десяти процентов.
Как в основной сессииinheritРешение о маршрутизации не нужно, когда модель сессии уже подходит.

Порядок разрешения: параметр модели при вызове, затем model во frontmatter, затем переменная окружения CLAUDE_CODE_SUBAGENT_MODEL, затем модель основного разговора. Задайте переменную вместе с CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, чтобы посадить всех субагентов на одну модель. Модель, исключённая allowlist организации, подменяется, и Claude Code показывает предупреждение с запрошенной и фактической моделью; /tasks показывает модель работающего субагента. Необязательное поле effort настраивает глубину рассуждений для каждого субагента.

Пять полных субагентов

Файлы, которые можно положить в .claude/agents/ уже сегодня. Они повторяют модель ролей из статьи Создание ИИ-агентов: ревью только для чтения, запуск тестов, отладка, дешёвое исследование и координатор с явным allowlist на запуск.

Пример 1 — ревьюер на Opus, только чтение. Финальный шлюз на staged diff; инструмента правки нет по замыслу:

vi .claude/agents/code-reviewer.md

--- name: code-reviewer description: Reviews staged changes for correctness, security and missing tests. Use after every code change. tools: Read, Grep, Glob model: opus maxTurns: 12 --- Review the staged diff. Report findings in severity order with file and line. Check for missing validation, secrets and missing tests. Verdict: ship, fix first, or block. Do not edit files.

Пример 2 — тест-раннер на Sonnet. Владеет циклом тестов, так что падения и логи никогда не заваливают основной контекст:

vi .claude/agents/test-runner.md

--- name: test-runner description: Runs the test suite and fixes failing tests. Use after implementation changes. tools: Read, Edit, Bash model: sonnet --- Run the narrowest test command for the change, then the full suite. On failure, quote the failing assertion, fix only the test or the code under test, and rerun. Stop after three attempts and report.

Пример 3 — отладчик по наследству. Сложные баги получают модель сессии, больше шагов и все инструменты:

vi .claude/agents/debugger.md

--- name: debugger description: Root-cause analysis for crashes and test failures. Use when an error resists a quick fix. model: inherit maxTurns: 20 color: orange --- Trace the error to the first wrong assumption before proposing a fix. Show the evidence chain, then apply the smallest fix and verify it.

Пример 4 — исследователь на Haiku. Дешёвое исследование только для чтения для вопросов, которым нужно много файлов:

vi .claude/agents/safe-researcher.md

--- name: safe-researcher description: Read-only research over the codebase. Use for "where is" and "how does" questions. tools: Read, Grep, Glob model: haiku --- Answer with file paths and short quotes. Do not edit anything. State clearly when the codebase does not contain the answer.

Пример 5 — координатор с allowlist на запуск. Как агент основной сессии он может запускать только названных детей; список типов внутри определения субагента игнорируется:

vi .claude/agents/coordinator.md

--- name: coordinator description: Coordinates work across specialized agents tools: Agent(worker, researcher), Read, Bash --- Plan the work in three bullets, delegate each step to worker or researcher, then merge the results into one report.

Это половина цикла, отвечающая за субагентов. Промпты, навыки и команды описаны в руководстве по навыкам; инструментальная сторона серверов MCP — в статье MCP.

Контекст, память и изоляция

Сначала замеры, потом мнения

Восемь фиксированных задач с проверяемым результатом лучше любого демо. Стартовый набор для пяти примеров выше:

Прогоняйте набор при каждом изменении промпта, инструмента или модели и храните историю. Падение на два пункта после улучшения — норма. Когда роль падает, трассировка обычно показывает причину: размытое описание, слишком узкий список инструментов или модель, маловатая для задачи.

Вместе с OpenCode в одном репозитории

Claude Code и OpenCode могут делить один checkout, не мешая друг другу, потому что читают разные каталоги агентов, но пересекаются на навыках: OpenCode тоже читает .claude/skills/, так что этот каталог — общий дом для совместных процедур. Файлы агентов остаются раздельными: .claude/agents/ здесь, .opencode/agents/ там.

repo/ ├── AGENTS.md shared instructions ├── .claude/skills/ read by both tools ├── .claude/agents/ Claude Code subagents ├── .opencode/agents/ OpenCode agents └── .opencode/skills/ extra OpenCode skills

Разобранный сценарий — triage в одном инструменте, сборка в другом, ревью обратно в первом — есть в статье Создание ИИ-агентов, а детали файлов OpenCode — в статье Агенты OpenCode.

Решение проблем

Автор статьи: Клавдия Кондакова