1. Что такое субагент и зачем он
Субагент - это специализированный помощник, которому Claude Code передаёт задачу: он делает работу в своём собственном окне контекста и возвращает в вашу сессию короткую сводку. Чтения файлов, поиски и вызовы инструментов остаются в его контексте.
Зачем так: при работе в основной сессии сообщения, прочитанные файлы и результаты команд занимают место в одном окне, а объём у него не резиновый. По мере заполнения Claude Code сокращает историю, и часть подробностей может потеряться. Субагент позволяет вынести промежуточную работу в отдельное окно, а в основном разговоре оставить её результат.
Самый простой субагент
Для первого запуска достаточно обычного сообщения в Claude Code: явно попросите вызвать субагента и опишите его задачу. Создавать свой файл роли заранее не требуется, для такого поручения подойдёт встроенный помощник. Например:
Вызови субагента для чтения файла index.html.
Пусть он составит короткую карту файла: основные разделы
и что делает каждый из них. Затем напишет краткое резюме
содержимого в 3-5 предложениях.
Файл не изменять. Верни ответ субагента в эту сессию.Главный агент передаст задачу помощнику, а после выполнения покажет его ответ в вашем разговоре. При фоновом запуске внизу, под полем ввода, появится полоска с именем субагента и состоянием его работы. Нажмите на неё, чтобы открыть сессию субагента и посмотреть, что он читает и делает. Проверьте по ходу работы, что появился отдельный запуск субагента: просьба обычным текстом направляет выбор Claude, но сама по себе не гарантирует делегирование.
Что получает субагент
Если одно и то же поручение нужно повторять с постоянными правилами, можно описать собственную роль в файле. На старте у такого пользовательского субагента два главных входа:
- инструкцию роли из вашего файла конфигурации - специализацию и правила поведения;
- описание задачи, которое главный агент составляет по вашему запросу.
К ним Claude Code сам добавляет общий фон: файлы CLAUDE.md проекта, снимок git status и сведения об окружении. Вашего разговора с главным агентом среди этого нет.
На схеме важно одно: субагент выполняет поручение в своём окне, а в основной разговор возвращает сводку. Главному агенту не приходится загружать все промежуточные чтения и поиски. Сама сводка при этом тоже занимает место в основном контексте.
У такого разделения есть обратная сторона: сводка не показывает весь путь к выводу. По ней можно не заметить, каких данных помощнику не хватило или что он оставил непроверенным. Поэтому в ответе нужны основания и ограничения, а его выводы стоит проверять.
Почему Claude не помнит всё
Контекстное окно - сведения, которыми модель располагает при подготовке очередного ответа: инструкции, доступная история разговора, прочитанный код, результаты команд. Именно поэтому агент может опираться на решение, которое вы обсудили несколькими сообщениями раньше. Окно имеет предел; оно не хранит весь разговор во всех подробностях навсегда.
На скриншоте команда /context показывает 4k/200k tokens (2%): занято около 4 тысяч токенов из 200 тысяч доступных. Токен - небольшой фрагмент текста: слово, часть слова или знак. Поэтому 200 тысяч токенов не равны 200 тысячам слов. Это размер окна показанной сессии; у другой модели или конфигурации он может отличаться.
Ниже видно, что занимает место: System prompt - системные инструкции, Memory files - загруженные файлы памяти и правил, Skills - сведения о скиллах, Messages - сообщения. Переписки здесь почти нет, но часть окна уже занята инструкциями. Строка Free space: 196k (98.0%) показывает оставшееся свободное место. По мере разговора, чтения файлов и выполнения команд оно расходуется.
Сохранённая переписка и текущее контекстное окно - разные вещи. Разговор может оставаться в истории сессии, но при подготовке ответа модель получает ограниченный объём сведений. Когда окно приближается к пределу, Claude Code сокращает историю, в том числе заменяет подробности кратким изложением. Это не мгновенное забывание всего разговора: часть сведений сохраняется в сводке. Но отдельное условие, объяснение или отвергнутый вариант из начала беседы может в неё не попасть. Тогда агент уже не сможет опереться на эту подробность, пока вы не напомните её или он не прочитает источник заново.
С файлами похожая ситуация: наличие app.js в проекте ещё не означает, что его содержимое попало в окно. Агенту нужно его прочитать. Общие инструкции из CLAUDE.md могут загружаться снова, но они не восстанавливают все решения из чата.
Например, вы договорились, что покупки с одинаковым названием считаются разными записями. Если это условие осталось только в старой части разговора, после сжатия оно может оказаться недоступным. Перед важной проверкой полезно повторить само условие или поручить прочитать документ, где оно записано.
Дальше разберём этот механизм на пользовательском reviewer для чтения кода: какие сведения он получает и как создать файл его роли. Здесь речь о новом обычном запуске; способы продолжить прежнюю работу или передать копию истории в этом примере не нужны.
2. Что reviewer знает о проекте
Отдельный контекст не означает, что помощник ничего не знает. У него есть начальные инструкции и доступ к проекту. Вот откуда берутся сведения у пользовательского reviewer из нашего примера:
| Сведения | Как они попадают к reviewer |
|---|---|
| Постоянные правила проверки | Из файла роли: что делать, какие инструменты доступны, что вернуть |
| Конкретная задача | Главный агент формулирует поручение по вашему запросу |
| Код и документы проекта | Reviewer сам открывает доступные файлы, которые нужны для проверки |
| Общие правила проекта | Загружаются применимые файлы CLAUDE.md, если они есть |
CLAUDE.md - файл с общими инструкциями для Claude Code: например, где лежит исходный код и какие соглашения приняты в проекте. Создавать его специально ради этой проверки не требуется.
История вашего разговора не переносится автоматически. Если главный агент уже читал app.js, содержимое этого чтения само по себе не появится у reviewer. Но файл никуда не исчез: помощник может открыть его заново.
С решениями из чата та же история. Допустим, вы обсуждали, что два одинаковых названия в списке должны оставаться отдельными покупками. Для проверки удаления это существенное требование. Оно дойдёт до reviewer, если главный агент включит его в поручение или помощник прочитает документ, где оно записано.
У нашего reviewer нет инструмента, чтобы напрямую задать вам вопрос. Поэтому при нехватке данных он должен написать, чего не хватает, и вернуть доступную часть результата. Главный агент сможет уточнить условие у вас. Фразу "как мы раньше решили" лучше сразу заменить самим решением.
3. Создаём файл роли
Роль положим в .claude/agents/reviewer.md внутри проекта. В пользовательской папке ~/.claude/agents/ тоже можно хранить роли, доступные в разных проектах; знак ~ обозначает домашнюю папку пользователя. Сейчас хватит проектного варианта.
Создать файл можно просьбой к Claude Code:
Создай .claude/agents/reviewer.md для проверки кода страницы
без изменений. Разреши только Read, Grep, Glob.
Ревьюер возвращает обоснованные находки, проверенный объём
и ограничения; отсутствие находок допустимо.
Покажи созданный файл.В результате должен появиться обычный текстовый файл. Без магии. Ниже готовый вариант: можно сравнить с ним ответ агента или сохранить его самостоятельно. Если роль с таким именем у вас уже есть, сначала посмотрите её содержимое, чтобы не заменить нужную инструкцию.
---
name: reviewer
description: Проверяет код готовой страницы на ошибки поведения и возвращает обоснованный отчёт. Использовать, когда просят ревью страницы без исправлений.
tools: Read, Grep, Glob
---
Изучи код указанных файлов по заданным требованиям.
Не меняй файлы. Не обещай запуск страницы: у тебя только чтение и поиск.
Для каждой находки укажи место, ожидаемое поведение, основание вывода,
условия проверки и влияние. Если данных не хватает, обозначь это.
Отдельно перечисли, что проверил и чего не проверял.
Если проблем по заданным критериям не нашёл, так и напиши.Блок между двумя строками --- называется frontmatter: настройки в начале Markdown-файла. Здесь name задаёт имя роли, description объясняет главному агенту, когда её выбирать, а tools перечисляет доступные инструменты. Ниже идут обычные инструкции словами.
Три инструмента в примере делают ровно то, что нужно для просмотра кода: Read читает файл, Grep ищет по содержимому, Glob находит файлы по имени или пути. Поэтому reviewer сможет найти функцию удаления и прочитать её, но не запустит страницу в браузере и не выполнит команду в терминале.
Строка "не меняй файлы" описывает поручение. Поле tools ограничивает средства его выполнения. Если оставить только просьбу в тексте и не ограничить инструменты, у помощника могут остаться возможности записи. В готовом примере обе части уже на месте, добавлять ограничение потом не нужно.
Файл роли похож на скилл: настройки и текст инструкции. Перепутать легко. Но здесь мы настраиваем отдельный запуск для проверки. Скилл обычно добавляет повторяемую процедуру в текущий разговор, хотя скиллы тоже могут запускаться в отдельном контексте. Выбирайте по тому, как должна выполняться работа, а не по похожему виду двух файлов.
4. Проверяем и вызываем reviewer
Наличие файла на диске - первый результат. Теперь проверим, видит ли его сессия. Откройте файл и посмотрите на имя reviewer, описание, строку инструментов и текст: нет ли там обещания запустить браузер или сразу исправить ошибки.
В поле ввода Claude Code наберите @ и выберите reviewer с пометкой agent. Нужна именно роль, а не похожий пункт с путём к файлу. Выбор из списка позволяет явно указать помощника для этого поручения.
Если роли нет, сначала проверьте путь: файл должен лежать в .claude/agents/ открытого проекта. Потом frontmatter: обе строки-разделителя, имя и описание. Можно попросить Claude Code проверить сам файл определения.
По документации Claude Code, изменения в уже отслеживаемой папке подхватываются за несколько секунд. Если папка agents впервые появилась после старта сессии, нужен перезапуск. Завершите текущую сессию, а затем в обычном терминале, из той же папки проекта, выполните:
claude --continueЭто продолжит последний разговор из текущего каталога. После запуска снова проверьте список @. Саму команду запуска Claude набирают в терминале после выхода, не внутри уже работающего разговора.
Для первого поручения возьмём страницу списка покупок: разметка в index.html, логика в app.js, оба файла в корне проекта. В вашем проекте замените пути и ожидаемое поведение на свои. После выбора reviewer из списка добавьте к упоминанию такой текст:
Изучи index.html и app.js в корне проекта.
Проверь добавление и удаление пунктов: счётчик должен совпадать
с числом оставшихся пунктов, удаление одной записи не должно
удалять другую с тем же названием.
Файлы не меняй. Верни выводы по коду и что нужно проверить в браузере.Здесь уже есть всё для узкой проверки: где искать, что должно происходить и какой результат нужен. Брифа отдельным файлом тут не надо. Главный агент сформулирует задачу для выбранного reviewer; сам выбор через @ определяет исполнителя, а не дословную передачу вашего сообщения.
5. Как приходит результат
После отправки запроса посмотрите, появился ли запуск reviewer. В обычной интерактивной сессии такая работа может идти в фоне: вы видите её в панели и можете продолжать разговор. Команда /tasks помогает посмотреть задачи, в том числе недавно завершённые.
Когда проверка закончится, главный агент получит итог и сообщит его вам. Если пересказ слишком короткий, попросите: "Приведи итоговый отчёт reviewer целиком". Так проще сохранить точную формулировку находки и ограничения проверки.
Например, учебный отчёт о счётчике мог бы выглядеть так:
Проверил добавление и удаление в app.js.
В removeItem() список перерисовывается, но вызова updateCounter()
на этом пути не нашёл. Ожидается, что счётчик покажет число
оставшихся записей.
Проверка в браузере: добавить один пункт, удалить его,
сравнить счётчик с пустым списком.
Удаление записей с одинаковым названием отдельно не проверял.
В браузере не запускал.Это пример формы ответа, не обещание найти именно такой баг в вашей странице. У нашего reviewer только чтение кода, поэтому последняя строка честно описывает его возможности. Вывод по коду может быть обоснованным и без запуска, но его основание надо проверить: например, не обновляет ли счётчик другая функция на том же пути.
Откройте указанное место или повторите описанные действия в браузере. Если проблема подтверждается, можно поручить исправление главному агенту. Если нет, сообщите своё наблюдение и попросите проверить вывод. Красиво оформленный отчёт ещё не решает, что именно следует менять.
Ответ "по заданным критериям проблем не нашёл" тоже допустим, если понятно, что было проверено. А "не нашёл файл с логикой удаления" означает частичный результат: сначала нужно уточнить путь. Заполнять отчёт догадками ради количества незачем.
Кстати, в списке могут встречаться встроенные роли Explore и Plan. Они доступны без создания собственных файлов ролей.
6. Когда стоит делегировать
После первой удачной проверки легко захотеть отдельного помощника на каждое действие. Соблазн понятный. Но новый запуск должен что-то давать: независимый просмотр или самостоятельную работу, чей подробный ход не нужен в основном разговоре.
| Задача | Где удобнее выполнить |
|---|---|
| Проверить готовую функцию с явными критериями | Отдельный reviewer полезен даже для небольшого файла: здесь важен независимый взгляд |
| Найти по многим файлам, откуда берётся значение | Субагент может вернуть короткий ответ с нужными путями |
| Изменить подпись известной кнопки | В основном разговоре: отдельный запуск почти ничего не добавляет |
| Подбирать поведение вместе с вами, уточняя его на каждом шаге | В основном разговоре проще сохранять общий контекст обсуждения |
Несколько зависимых шагов тоже могут составлять одну задачу для субагента. Найти обработчик, проверить его вызовы и составить вывод - нормальное цельное поручение. Не стоит только раздавать каждый шаг отдельному помощнику, если потом придётся заново объяснять всем результаты соседнего шага.
Модель для субагента можно назначить отдельно полем model. сейчас оно не требуется: сначала полезнее получить понятную роль и проверяемый результат. Отдельный запуск сам по себе не означает ни более сильную, ни более слабую модель.
Вторая роль должна проверять другое
Допустим, кроме reviewer вам нужен playtester для проверки пользовательского сценария. Копия прежней инструкции с новым именем почти ничего не изменит. Сначала различите предмет работы и результат:
| Роль | Когда звать и что передать | Что получить |
|---|---|---|
| reviewer | Нужно проверить код удаления; передайте файлы и требования | Вывод по коду с местом, основанием и ограничениями |
| playtester | Нужно оценить сценарий пользователя; передайте шаги, ожидания и доступные наблюдения | Что произошло на каждом шаге, где результат расходится с ожиданием и что осталось непроверенным |
Например, роль может разбирать только удаление одной из двух покупок с одинаковым названием: после действия должна остаться одна запись, а счётчик должен показывать 1. Это измеримое поручение. "Оцени, хорошая ли страница" оставляет слишком много места для вкусовых советов.
Теперь сопоставьте поручение с инструментами. С одним чтением и поиском, как у нашего reviewer, помощник не выполнит действия в браузере. Он может составить сценарий проверки или разобрать ваши записанные наблюдения. Это подготовка или анализ проверки, а не самостоятельно выполненный playtest.
Подготовь сценарий проверки удаления одной из двух покупок
с одинаковым названием. Для каждого шага укажи действие
и ожидаемый результат. Код не меняй, выполнение не заявляй.
После моих наблюдений сравни ожидаемое с фактическим
и перечисли, каких данных не хватает.Для самостоятельного запуска нужен доступный инструмент работы с браузером и проверка того, что запуск действительно состоялся. Одного имени playtester для этого мало. Сначала выберите способ проверки, затем опишите в роли, когда её вызывать и какой результат она может честно вернуть.
7. Как это выглядит в вашей сессии
Теперь у вас есть файл роли, которую сессия видит, и короткая проверка, которую можно ей поручить. Этого достаточно для начала. Не нужно заранее собирать десяток похожих reviewer.
Дальше правьте тот слой, в котором обнаружилась проблема. Не передали важное условие - дополните поручение. Получили сомнительный вывод - проверьте основание. Reviewer регулярно возвращает слишком общие ответы - уточните инструкцию роли. Файл останется в проекте, и следующую проверку вы начнёте уже с этих правил.
Для повторяемых поручений пригодится бриф ревьюеру. Когда ответ уже получен, переходите к проверке находок и выбору исправлений.