Как работают субагенты в Claude Code

Инструкция сверена с документацией Claude Code в октябре 2026 года. Функция быстро меняется: летом 2026 года субагенты по умолчанию стали работать в фоне, а команда /agents перестала открывать мастер настройки.

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

Пять способов расширить Claude Code легко перепутать. CLAUDE.md хранит правила для каждого сеанса. Скил добавляет знания или готовый воркфлоу и подгружается в разговор, когда нужен. MCP подключает внешние системы вроде базы данных или трекера задач. Хук запускает ваш скрипт на событие, например после каждой правки файла, и срабатывает без решения модели. Субагент работает как отдельный исполнитель со своим контекстом, промптом, моделью и тулами.

Больше всего путаницы между субагентом и скилом. Документация советует отдавать субагенту побочную задачу, которая заваливает разговор ненужным выводом, а повторяемый промпт для основного разговора оформлять скилом. Скилы мы разобрали в отдельной статье.

Субагент стартует с чистого листа и не видит историю разговора, прочитанные файлы и вызванные скилы. Он получает свой системный промпт из файла вместо системного промпта Claude Code, задание, которое для него пишет Claude, ваши CLAUDE.md, снепшот git status и скилы из поля skills. Дальше он работает своими тулами, а основной разговор получает только финальный ответ.

Несколько субагентов встроены в Claude Code, и Claude зовёт их сам. Explore ищет и читает код без права на правки, а глубину поиска Claude задаёт уровнем quick, medium или very thorough. Plan собирает контекст в режиме планирования. Оба стартуют без CLAUDE.md и снепшота git, чтобы рисерч шёл быстрее и дешевле. General-purpose получает все доступные субагентам тулы и берётся за задачи, где код нужно и изучить, и изменить.

Субагент хранится в Markdown-файле. Сверху шапка frontmatter на YAML, ниже системный промпт. Файлы из .claude/agents/ работают в своём проекте, их стоит закоммитить для всей команды, а файлы из ~/.claude/agents/ доступны во всех ваших проектах. При совпадении имён проектный субагент важнее личного. Субагента Claude Code узнаёт по полю name, а правки в файлах подхватывает за несколько секунд без перезапуска. Перезапуск нужен, если папки agents на старте сеанса ещё не было.¹

Субагента проще всего заказать самому Claude Code:

Создай субагента code-reviewer в ~/.claude/agents/. Он смотрит последние
изменения через git diff и ищет ошибки, уязвимости и проблемы
с читаемостью. Сделай его только для чтения, модель Sonnet.

Файл можно написать и вручную, у нас получился такой ~/.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Ревьюер кода. Проверяет свежие изменения на ошибки, уязвимости и читаемость. Используй проактивно сразу после того, как код написан или изменён.
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
---

Ты старший ревьюер кода. Ты читаешь код и ничего в нём не меняешь.

Когда тебя вызвали:
1. Выполни git diff и посмотри последние изменения.
2. Сосредоточься на изменённых файлах.
3. Сразу начинай ревью.

Что проверять:
- логические ошибки и необработанные граничные случаи;
- обработку ошибок и проверку входных данных;
- секреты и ключи API в коде;
- понятность имён и повторы кода;
- есть ли тесты на новое поведение.

Сгруппируй замечания по приоритету:
- критично, исправить до коммита;
- желательно исправить;
- можно улучшить.

Для каждого замечания укажи файл и строку и покажи, как исправить.
Если замечаний нет, напиши это одной фразой.

Обязательных полей два. name задаёт имя до 256 символов без двоеточия. description решает, когда Claude отдаст субагенту задачу. Документация советует добавить в описание фразу вроде «use proactively», чтобы Claude делегировал охотнее. У нас это «Используй проактивно».

tools перечисляет разрешённые тулы. Без этого поля субагент наследует почти все тулы основного разговора, включая MCP. Write и Edit в списке нет, так что править файлы ревьюеру нечем. Bash нужен ради git diff. Команды git только для чтения выполняются без запроса разрешения, а на остальные действуют обычные правила доступа. Жёсткий запрет на отдельные команды ставят хуком PreToolUse прямо в шапке субагента.

Проверьте ревьюера в проекте с незакоммиченными правками: «Пусть code-reviewer посмотрит мои последние изменения». Отчёт придёт в разговор, когда ревьюер закончит.

Поле model принимает sonnet, opus, haiku, fable, полный ID вроде claude-opus-5-5 или inherit, то есть модель основного разговора. Без поля субагент тоже берёт её, если вы не задали другую переменной CLAUDE_CODE_SUBAGENT_MODEL. Модель, которую Claude передаст при вызове, важнее поля. Документация советует писать код на Sonnet, Opus оставлять для архитектуры и многошаговых рассуждений, а простые задачи субагентов отдавать Haiku. Если переключить /model на Opus, на него перейдут и субагенты, которые наследуют модель.

С необязательным полем disallowedTools субагент наследует всё, кроме перечисленного. maxTurns ограничивает число ходов. memory даёт постоянную папку памяти, со значением project это .claude/agent-memory/code-reviewer/. Полный список есть в таблице полей. Поле с опечаткой в имени Claude Code молча проигнорирует, так что сверяйте имена с документацией буква в букву.^{2 3}

С тест-раннера мы советуем начинать, потому что выгода от него видна на первом же прогоне. Лог тестов длинный, а нужен из него только список падений. Положите файл в .claude/agents/test-runner.md и закоммитьте:

---
name: test-runner
description: Запускает тесты проекта и возвращает только упавшие тесты с текстом ошибок. Используй проактивно после изменений кода и перед коммитом.
tools: Bash, Read
model: haiku
maxTurns: 10
---

Ты запускаешь тесты и докладываешь результат. Код ты не исправляешь.

1. Запусти весь набор тестов командой npm run test.
2. Если всё прошло, ответь одной строкой: сколько тестов прошло.
3. Если есть падения, для каждого упавшего теста укажи имя, файл
   и первые строки ошибки. Если из лога непонятно, где упало,
   открой файл теста.

Не пересказывай успешные тесты и не вставляй лог целиком.

Команду npm run test замените на свою, например pytest. Запустить команду и выписать падения под силу быстрой и недорогой модели, поэтому здесь стоит Haiku.

Фоновый субагент выносит каждый запрос разрешения в основной сеанс. Чтобы в ручном режиме тест-раннер не ждал вас, разрешите тесты заранее в .claude/settings.json, как в статье об установке и настройке Claude Code:

{
  "permissions": {
    "allow": [
      "Bash(npm run test *)"
    ]
  }
}

Теперь достаточно написать «Прогони тесты через test-runner».

Claude делегирует сам, сверяя вашу просьбу и контекст с полями description. Можно назвать субагента в просьбе, и Claude обычно послушается, но решение останется за ним. Гарантию даёт упоминание через @. Выберите субагента из подсказок, и получится строка вида @"code-reviewer (agent)" посмотри изменения в авторизации. Задание для субагента Claude всё равно напишет сам. Команда claude --agent code-reviewer отдаёт субагенту весь сеанс с его системным промптом, тулами и моделью.

По умолчанию субагент, которого Claude запускает из основного разговора, работает в фоне, а вы продолжаете писать. Работающие субагенты видны в панели под строкой ввода, /tasks показывает всю фоновую работу сеанса, Enter открывает транскрипт. Запрос разрешения от субагента появится в основном сеансе с его именем. Если вместо одобрения нажать Esc, отклонится только этот вызов, а субагент продолжит работу. Разрешение на весь сеанс действует и для основного разговора. Результат приходит уведомлением в одном из следующих ходов.

Чтобы Claude дождался отчёта, например ревью перед коммитом, в терминале, VS Code и десктопном приложении выключают режим форков:

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

Затем перезапустите claude и попросите прямо: «Запусти ревьюера и дождись отчёта». Ctrl+B в терминале вернёт ждущего субагента в фон.

Параллельный запуск просят словами: «Изучи модули авторизации, базы данных и API параллельно, отдельными субагентами». Каждый разберёт свою независимую часть, а Claude сведёт выводы. В сеансе одновременно работают до 20 субагентов, а вложенность ограничена тремя уровнями. Если параллельные субагенты правят код, дайте каждому isolation: worktree.

Форк наследует весь разговор, а с ним системный промпт, тулы и модель. Режим форков включён по умолчанию, поэтому Claude может запускать их сам, а вы запускаете форк командой /subtask, например /subtask набросай юнит-тесты для сегодняшних правок в парсере. Форк нужен, когда обычному субагенту пришлось бы долго объяснять контекст. Команда /fork с похожим названием обычно копирует весь сеанс в новый фоновый сеанс.

Изоляция бережёт контекст основного разговора, но работа субагента не бесплатна. Он шлёт модели свои запросы, и они идут в те же лимиты использования. Отчёты субагентов возвращаются в разговор, так что десять параллельных исследований с подробными выводами съедят заметную часть контекста.

У обычного субагента свой системный промпт, поэтому его первый запрос не читает кэш промптов основного разговора и прогревает собственный. Даже на подписке кэш субагента по умолчанию живёт пять минут, а не час, как у основного разговора. Форк повторяет промпт и тулы родителя, читает готовый кэш и для задачи с тем же контекстом обходится дешевле свежего субагента.

Простым задачам ставьте model: haiku. Explore раньше работал на Haiku, а с лета 2026 года берёт модель основного разговора, но свой субагент с именем Explore и model: haiku заменит встроенного. Описания субагентов держите короткими, они постоянно занимают контекст. Если их сумма превысит 15 000 токенов, Claude Code предупредит об этом на старте. Долю субагентов в недавнем расходе на тарифах Pro, Max, Team и Enterprise показывает /usage.

Чаще всего субагент не срабатывает из-за расплывчатого описания. По фразе «помогает с кодом» Claude не поймёт, когда его звать, поэтому описание должно отвечать на вопрос, когда нужен именно этот субагент.

Субагент не помнит разговор и не может задать вам уточняющий вопрос по ходу работы, потому что тул AskUserQuestion у субагентов отключён. Всё важное, например «не трогай vendor/», пишите в просьбе или запускайте форк.

Если в файле нет name или строка --- стоит не первой, Claude Code молча считает файл документацией. Файл без description или с битым YAML он пропускает и пишет причину в отладочный лог, который видно при запуске claude --debug. С версии 2.1.233 папку можно проверить заранее командой claude plugin validate .claude/agents, но файл без name она не отметит.

Несколько полей ведут себя неочевидно. Claude Code игнорирует permissionMode, если основной разговор идёт в режиме auto, acceptEdits или bypassPermissions. Поле memory само включает тулы Read, Write и Edit, так что у ревьюера с памятью появятся тулы для правки файлов. Строка disallowedTools: Bash(git push *) убирает весь Bash, не только push. Копия для isolation: worktree по умолчанию ответвляется от основной ветки, а не от вашего текущего HEAD.

Наконец, частые уточнения, этапы с общим контекстом, мелкие правки и задачи, где важна скорость ответа, лучше оставить основному разговору, ведь свежему субагенту нужно время, чтобы собрать контекст.

Начните с двух субагентов из статьи и через пару дней посмотрите в /usage, сколько они тратят. Новых субагентов впрок не заводите, каждое лишнее описание занимает контекст и мешает Claude выбрать нужного. Потом подключите к рабочим субагентам скилы команды через поле skills или упакуйте их в плагин, чтобы переносить между репозиториями. Для задач, которые не помещаются в один сеанс, есть другие способы параллельной работы: agent view, экспериментальные команды агентов и динамические воркфлоу.