Субагенты

В уроке про контекст мы несколько раз говорили: «отдайте это субагенту». Пора разобраться, что это такое. Субагенты — способ разделить работу на изолированные контексты: основной разговор остаётся чистым, а шумные или специализированные задачи выполняются отдельно. В этом уроке — как они устроены, какие есть из коробки и как написать свой.

Что такое субагент

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

Отсюда три свойства, ради которых субагентов используют:

• Изоляция контекста. Исследование на пятьдесят файлов не попадает в основной разговор.
• Специализация. У субагента своя инструкция: «ты ревьюер безопасности», «ты запускаешь тесты и разбираешь падения».
• Ограничение инструментов. Ревьюеру можно дать только чтение и поиск — он физически не сможет ничего изменить.

Субагент не видит историю основного разговора. Он получает системную инструкцию, текст задачи, файлы CLAUDE.md и снимок состояния git. Это надо учитывать при постановке задачи: всё, что он должен знать, нужно передать явно. Исключение — субагент-«форк», который стартует с копией текущего разговора.

Встроенные субагенты

Claude Code поставляется с несколькими субагентами, которых не нужно настраивать.

Explore — только чтение, без правок. Для поиска файлов и исследования кода. Чтобы работать быстро и дёшево, он пропускает загрузку CLAUDE.md и git-статуса. Именно его Claude выбирает, когда вы пишете «используй субагента, чтобы разобраться…».

Plan — тоже только чтение, используется в режиме планирования для исследования перед составлением плана.

general-purpose — со всеми инструментами, для сложных многошаговых задач, включая правки кода.

Есть и служебные: claude-code-guide отвечает на вопросы о самом Claude Code, statusline-setup настраивает строку состояния.

Вызвать субагента можно обычным языком:

используй субагента, чтобы выяснить, как в проекте обновляется токен
и есть ли готовые утилиты для OAuth

Claude сам выберет подходящего по описанию. Если нужен конкретный — упомяните его через @: @agent-security-reviewer проверь изменения в auth. Упоминание гарантирует вызов именно этого субагента.

По умолчанию субагенты работают в фоне: основной агент продолжает работу, а запросы на разрешения от субагента всплывают в основной сессии. Список запущенных показывает /list-agents, остановить все фоновые — Ctrl+X Ctrl+K.

Свой субагент: формат файла

Субагент — это markdown-файл с YAML-заголовком. Место хранения определяет область:

Обе папки сканируются рекурсивно, так что субагентов можно раскладывать по подпапкам. Минимальный файл:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Обязательны два поля. name — идентификатор латиницей в нижнем регистре с дефисами. description — когда Claude должен делегировать этому субагенту; по нему модель решает, кого вызвать, поэтому пишите конкретно и коротко. Текст после заголовка — системная инструкция субагента.

Необязательные поля, которые пригодятся чаще других:

• tools — список разрешённых инструментов через запятую. Без поля субагент наследует все. disallowedTools — наоборот, список запрещённых.
• model — sonnet, opus, haiku или inherit. Для простых задач haiku заметно дешевле.
• permissionMode — режим прав субагента: default, acceptEdits, plan и другие.
• maxTurns — предел шагов, после которого субагент остановится с частичным результатом.
• memory — постоянная память субагента (user, project или local), чтобы он накапливал знания между сессиями.
• skills — навыки, которые загружаются в контекст субагента при старте.

Полный список полей — в документации. Не обязательно писать файл руками: попросите Claude — «создай субагента test-runner в .claude/agents/, который запускает тесты, разбирает падения и предлагает исправления; только чтение и Bash».

Пример: раннер тестов для Flutter

Прогон тестов Flutter-приложения даёт длинный вывод, а разбор падений требует чтения нескольких файлов. Хороший кандидат для субагента:

---
name: flutter-test-runner
description: Runs Flutter tests and diagnoses failures. Use after changes to lib/ or test/ when the user asks to verify or fix tests.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
---

You run `flutter test` (or `flutter test <path>` when a path is given),
read the output, and for each failure find the cause in lib/ or test/.

Report back:
1. Total passed/failed.
2. For each failure: test name, file:line, one-sentence cause,
   proposed fix (do not apply it).
Keep the report under 40 lines. Do not paste raw test output.

Вызов: «используй flutter-test-runner для test/features/orders». В основной разговор вернётся отчёт на сорок строк вместо нескольких тысяч строк вывода. Заметьте последнюю инструкцию — без неё субагент склонен вставлять сырой вывод, и весь выигрыш по контексту пропадает.

Аналогичные субагенты уместны для Python (pytest с разбором трейсбеков), для Node (vitest, линтер) и для сборки: «собери проект, если упало — найди причину и опиши».

Когда субагент — правильный выбор

Документация выделяет типичные случаи.

• Исследование большой кодовой базы. Вопрос требует прочитать много файлов, а вам нужен только вывод.
• Многословные операции. Тесты, логи, загрузка документации.
• Проверка чужой работы. Ревьюер в свежем контексте не предвзят к коду, который написал основной агент. Об этом был урок про ревью.
• Параллельная работа. Несколько субагентов могут работать над независимыми частями одновременно, а основной агент собирает результаты.

Когда субагент не нужен: короткая задача с понятным ответом. Запуск субагента сам по себе стоит контекста и времени — для «прочитай этот файл и ответь» это лишнее.

Один нюанс: описания всех субагентов загружаются в основной контекст, чтобы модель могла выбирать. Держите description коротким и не плодите десятки субагентов «на всякий случай».

Субагент как основной агент

Файл субагента можно использовать и как конфигурацию основной сессии: claude --agent code-reviewer запустит Claude Code с инструкцией и ограничениями этого субагента. Это удобно для ролевых сессий — например, сессия только для ревью, в которой физически отключены инструменты записи. Для скриптов субагентов можно передать флагом --agents в виде JSON, не создавая файлов.