# Субагенты в Claude Code: 6 шагов до первого read-only-помощника

> Субагент в Claude Code берёт одну отдельную задачу, работает в собственном контексте и возвращает основной сессии короткий результат. Ниже я показываю безопасный read-only-сценарий.

Источник: https://vibeceh.ru/guides/subagenty-odin-pomoshchnik-dlya-otdelnoy-zadachi-v-claude-code
Автор: Сергей Мазур · опубликовано 2026-08-04

📩 Разбираю по одной штуке в неделю и присылаю в телеграм: [@vibeceh](https://t.me/vibeceh). Без спама, отписка в один клик.

Если ты ищешь `claude субагенты`, начни с простой схемы: субагент в Claude Code - отдельный [ИИ-агент](https://vibeceh.ru/guides/concepts/agent), которому можно передать одну конкретную задачу, чтобы не выполнять её вручную в основном диалоге. Он читает нужные файлы в собственном контексте, делает проверку и возвращает короткий результат, а не весь поток промежуточной работы.

## Что значит субагент простыми словами?

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

Представь второго разработчика за соседним столом, который получил одно поручение. Основной Claude продолжает вести разговор. Субагент отдельно смотрит то, что ему передали, и возвращает вывод.

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

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

В официальном описании Anthropic смысл сформулирован так:

Субагенты - делегированные исполнители внутри одной сессии, которые берут побочную задачу в собственном контексте и возвращают краткое резюме.

Слово «побочная» здесь не означает бесполезную. Это задача, которая нужна для основного результата, но не требует всей переписки. Проверить файл. Найти причину ошибки. Сверить утверждение. Вернуть список рисков.

## Что такое субагенты ИИ?

субагенты ИИ нужны для короткой сфокусированной работы, которую неудобно выполнять в главном диалоге. Такой помощник может исследовать вопрос, проверить утверждение или просмотреть файл. Он возвращает сводку, поэтому основной Claude не тонет в поисковой выдаче, логах и прочитанном коде.

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

Субагент выносит такую работу наружу. Результатом становится полезная выжимка.

Хорошие задачи для первого запуска:

- исследовать, как часть проекта обрабатывает вход пользователя;
- проверить одно утверждение о коде;
- просмотреть файл и найти очевидные проблемы;
- найти связанные файлы по конкретной функции;
- объяснить путь данных от формы до сохранения.

Плохая формулировка звучит так: «Разберись со всем проектом и сделай его лучше». Здесь нет границы, результата и понятного способа проверки. Claude может начать читать слишком много, а потом вернуть общий пересказ.

Я бы держал простое правило: один субагент - одна проверяемая операция. Сформулируй конкретную задачу: «проверь файлы авторизации и верни пути файлов, найденные риски и номера строк».

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

роль субагента задаётся телом Markdown-файла, а поле `description` помогает Claude выбрать его автоматически. Новый исполнитель получает собственную системную инструкцию и базовые сведения о рабочей папке, но не видит историю основного разговора, уже прочитанные файлы и вызванные навыки. Всё необходимое передавай в самом запросе.

Я смотрю на устройство файла и вижу две части.

Первая - YAML-заголовок. Там лежат имя, описание и разрешённые инструменты.

Вторая - тело Markdown-файла. Оно становится системной инструкцией субагента. Здесь ты задаёшь роль, запреты, область проверки и формат ответа.

`description` работает не как подпись для красоты. По нему Claude понимает, когда такую роль стоит подключить. Поэтому я советую обозначать в описании конкретную задачу и момент запуска. Например: «проверяет текущие изменения на ошибки и риски, не редактирует файлы».

Контекст у субагента отдельный. Если ты пять сообщений назад объяснил главному Claude, что авторизация переезжает с cookies на JWT, новый исполнитель этого не знает. Если основной Claude уже читал `src/auth/login.ts`, субагент не получает прочитанное автоматически.

Передавай ему:

- область проверки;
- нужные файлы;
- краткий фон;
- формат результата;
- запрет на лишние действия.

Документация Anthropic отдельно фиксирует это ограничение:

Каждый субагент начинает работу в новом изолированном контексте. Он не видит историю разговора, уже вызванные навыки и файлы, которые Claude уже прочитал.

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

На практикуме я показываю руками, как передавать контекст субагенту и не терять детали: vibeceh.ru/#buy

## Как устроена система субагентов?

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

![Кот у схемы основного Claude, субагента, инструментов и результата.](https://s3.regru.cloud/crossmark/statejnik/images/guides/subagenty-odin-pomoshchnik-dlya-otdelnoy-zadachi-v-claude-code/kadr-1.webp)

Схема выглядит так:

1. **Основной Claude.** Принимает твою задачу и ведёт главный диалог.
2. **Субагент.** Получает отдельное поручение и собственную инструкцию.
3. **Инструменты.** Определяют, что субагент способен сделать: читать, искать, запускать команды или редактировать.
4. **Результат.** Возвращается основному Claude в сжатом виде.

Для первого сценария достаточно плоской схемы: основной Claude вызывает одного read-only-проверяющего (подробнее о разделении задач между агентами - в [разборе Claude Code против Codex](https://vibeceh.ru/guides/claude-code-protiv-codex-kak-razdelit-zadachi-mezhdu-agentami)). Не строй цепочку из исполнителей, пока не научился проверять одного.

За одну сессию Claude Code по умолчанию может создать максимум 200 субагентов. Одновременно работают не больше 20. Эти лимиты не означают, что надо стремиться к большим запускам. Для личной задачи новичка они, скорее всего, останутся далеко за пределами реальной потребности.

Инструменты задают фактические границы роли. Если оставить `Read`, `Glob` и `Grep`, субагент сможет читать и искать. `Edit`, `Write` и `Bash` расширят доступ. Для безопасной проверки я бы их не добавлял.

Для первого сценария субагент не должен запускать других субагентов: глубина вложенности зависит от версии и настроек Claude Code. Не пытайся строить схему «помощник вызвал специалиста, специалист вызвал ещё одного». Последовательность держит основной Claude.

## Какую одну задачу дать первому помощнику?

первой роли дай read-only-проверку кода или объяснение части проекта. Такая задача ограничена, её результат можно сверить по путям файлов и строкам, а ошибка не меняет рабочие файлы. Широкая роль разработчика опаснее: она охватывает слишком много действий, а проверить, где именно Claude свернул не туда, трудно.

Я бы начал с одной из двух ролей:

| Роль | Что делает | Кому подходит |
|------|-----------|---------------|
| `code-explainer` | Объясняет, как устроена выбранная часть проекта | Когда нужно понять структуру кода |
| `code-reviewer` | Ищет ошибки, риски и пропущенные проверки | Перед коммитом, для проверки изменений |

Для начинающего вайб-кодера особенно полезен `code-reviewer`. Он не собирает новую функцию и не пытается «улучшить» архитектуру. Он смотрит на уже существующие изменения и сообщает, что может сломаться.

Минимальная инструкция проверяющего должна содержать четыре вещи:

- читать только файлы, связанные с текущей задачей;
- ничего не менять;
- указывать путь и номер строки;
- явно писать, если проблема не найдена.

Такой результат легче показать основному Claude или проверить самому.

Широкая роль backend-разработчика выглядит мощнее, но для первого запуска это плохой обмен. В неё придётся включить API, базу данных, авторизацию, тесты и производительность. Claude получит слишком много направлений. Ты получишь длинный план вместо ответа на один вопрос.

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

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

## Как создать read-only-субагента в проекте?

создай в проекте каталог `.claude/agents/`, положи туда Markdown-файл с YAML-полями `name`, `description` и `tools`, а ниже напиши системную инструкцию. Оставь только `Read`, `Glob` и `Grep`, запрети изменение файлов, сохрани файл и перезапусти сессию Claude Code.

![Кот держит карточку с инструментами Read, Glob и Grep для read-only-проверки.](https://s3.regru.cloud/crossmark/statejnik/images/guides/subagenty-odin-pomoshchnik-dlya-otdelnoy-zadachi-v-claude-code/kadr-2.webp)

Открой корень проекта и создай папку `.claude/agents/`.

Этот путь относится к текущему проекту. Пользовательский каталог `~/.claude/agents/` хранит роли, доступные во всех проектах. Для первого эксперимента бери локальный вариант, чтобы не подключить роль случайно в другом месте.

Внутри каталога создай файл `code-reviewer.md`.

Имя файла должно заканчиваться на `.md`. Внутри будет YAML-заголовок и обычный текст инструкции. Готовый вариант ниже можно использовать без дополнительных сервисов.

В YAML укажи `name` и `description`.

`name` - короткое имя роли. `description` - условие, по которому Claude понимает назначение помощника. Пиши конкретную задачу и момент запуска.

Укажи `Read`, `Glob` и `Grep` в поле `tools`.

`Read` читает файлы. `Glob` ищет файлы по шаблону. `Grep` ищет текст внутри файлов. Не добавляй `Edit`, `Write` и `Bash`, если роль должна только проверять код.

После закрывающей строки YAML задай роль, запреты и формат результата.

Субагент не видит историю главного разговора. Поэтому я пишу инструкцию так, чтобы она сама объясняла, что проверять и как отчитываться - похоже на [Skills](https://vibeceh.ru/guides/skills-navyki-pervyy-navyk-dlya-claude-code-bez-kashi), где инструкция живёт отдельно и подгружается только при вызове. Не прячь главное правило в другом файле.

   ```markdown Заготовка read-only-проверяющего
   ---
   name: code-reviewer
   description: >
     Reviews current code changes for bugs, security problems, and missing tests.
     Use proactively before committing changes. Never edit files.
   tools: Read, Glob, Grep
   ---

   Review the current code changes.

   Rules:
   - Read only files relevant to the current task.
   - Do not edit, create, or delete files.
   - Do not run shell commands.
   - Check for obvious bugs, security issues, broken user flows, and missing tests.
   - Include file paths and line numbers.
   - If you find nothing, say so explicitly.

   Return:
   1. Critical issues.
   2. Warnings.
   3. Suggested fixes.
   4. Open questions.
   ```

Запиши `.claude/agents/code-reviewer.md`, закрой текущую сессию и запусти Claude Code заново.

Факт наличия файла ещё не доказывает, что Claude Code его загрузил. После перезапуска вызови роль явно. Если она не отображается или не отвечает как проверяющий, проверь имя, путь и YAML.

В документации Anthropic формат описан так:

Тело файла становится системным промптом субагента, а frontmatter задаёт его метаданные и конфигурацию.

Не добавляй `tools` «на всякий случай». Если поле не указать, субагент может унаследовать все доступные инструменты. Для read-only-сценария явный список безопаснее.

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

## Как запустить субагента и передать ему задачу?

назвать роль в обычном запросе можно для мягкого вызова, `@` используют для обязательного запуска конкретного субагента, а `claude --agent <name>` запускает всю сессию с настройками выбранной роли. Сам запрос всё равно должен содержать область проверки, файлы и формат ответа, потому что история основного диалога не передаётся автоматически.

![Безымянный мужчина прикрывает лицо рядом с тремя способами запуска субагента.](https://s3.regru.cloud/crossmark/statejnik/images/guides/subagenty-odin-pomoshchnik-dlya-otdelnoy-zadachi-v-claude-code/kadr-3.webp)

Есть три способа.

1. Назвать роль в обычной фразе. Claude сам решит, делегировать ли задачу.
2. Упомянуть роль через `@`. Такой вызов гарантирует запуск выбранного субагента для одной задачи.
3. Запустить сессию через `claude --agent code-reviewer`. Тогда вся сессия получает системную инструкцию, ограничения инструментов и модель этой роли.

Для первого теста используй обязательный вызов через `@`. Он убирает неопределённость автоматического выбора.

```text Использование роли
@"code-reviewer (agent)" проверь изменения в авторизации
```

Самый полезный запрос выглядит так:

Если используешь обычный вызов, формулировка может быть короче:

```text
Use the code-reviewer subagent to inspect the authentication files. Do not edit anything. Return only critical issues, file paths, line numbers, and open questions.
```

Я бы не писал «проверь всё». Узкая область нужна не для красоты. Она уменьшает объём чтения и помогает понять, действительно ли роль делает то, что задумано.

В официальной документации есть три режима: естественный вызов, `@`-упоминание и запуск через флаг `--agent`.

## Что такое web-субагент и нужен ли он тебе?

внешний доступ для отдельного субагента можно задать через поле `mcpServers`. Это подключает к нему MCP-серверы, которых нет в основном разговоре. Для первого read-only-сценария web-доступ не нужен: начни с локальных файлов и добавляй внешний сервис только под конкретную задачу.

`mcpServers` задаётся отдельно в конфигурации субагента. Через него можно дать роли доступ к внешним сервисам (как подключить первый MCP-сервер - в [пошаговой инструкции](https://vibeceh.ru/guides/mcp-podklyuchit-pervyj-instrument)), но сам факт подключения не превращает помощника в готовый веб-поиск.

В первом запуске внешний доступ скорее мешает:

- добавляет ещё один источник ошибок;
- расширяет область действий;
- усложняет проверку результата;
- требует отдельной настройки MCP-сервера.

Если задача звучит как «проверь, как устроена эта часть моего проекта», локального read-only-помощника достаточно. Если понадобится внешний сервис, сначала сформулируй отдельную роль и выдай ей только нужный MCP-доступ.

Не добавляй `mcpServers` в файл только потому, что встретил запрос `web субагент`. Подключённая возможность должна закрывать конкретную задачу, а не украшать конфигурацию.

На этом месте я останавливаюсь: в доступной фактуре есть подтверждённый способ подключать MCP-серверы, но нет готового официального сценария веб-поиска для новичка. Поэтому не буду выдавать догадку за инструкцию.

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

Субагенты полезны как способ разделить повторяемую работу на понятные операции. Чем точнее ограничена роль, тем безопаснее результат.

## Сколько это стоит и когда субагент только мешает?

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

У субагента есть накладные расходы. Ему надо заново получить инструкцию, понять область работы, открыть нужные файлы и сформировать ответ для основного Claude.

Если ты просишь проверить один маленький файл, отдельный запуск может добавить лишний путь:

1. основной Claude формулирует поручение;
2. субагент открывает собственный контекст;
3. субагент читает файл;
4. субагент пишет отчёт;
5. основной Claude читает отчёт и продолжает работу.

В таком случае быстрее бывает попросить основной Claude прочитать файл напрямую.

Субагент оправдан, когда побочная задача регулярно раздувает главный диалог. Например, проверка нескольких файлов, исследование структуры проекта или повторяемый аудит изменений. Тогда короткий итог ценнее длинного потока чтения.

Anthropic предупреждает об этом прямо:

Субагенты несут накладные расходы. Каждый запускает собственный контекст, потребляет токены и добавляет слой косвенности.

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

Я провожу практическую границу так. Один файл и один очевидный вопрос - основной диалог. Повторяемая проверка нескольких файлов с коротким отчётом - read-only-субагент.

## Что делать, если субагент не видит контекст или не запускается?

сначала проверь, загрузился ли файл, затем вызови роль явно и передай самодостаточный запрос. У субагента нет истории основного диалога, уже прочитанных файлов и автоматически вызванных навыков. Если read-only-роли поручить редактирование, она не выполнит задачу. Проверь имя, путь, инструменты и ожидаемый формат ответа.

Проверь пять пунктов:

1. **Сверь имя роли.** Значение `name`, имя файла и имя в вызове должны указывать на одну роль.
2. **Проверь путь.** Для роли проекта нужен `.claude/agents/<имя>.md`.
3. **Проверь инструменты.** `Read`, `Glob`, `Grep` подходят для чтения. `Edit` и `Write` в read-only-файле не появятся сами.
4. **Вызови роль явно.** Не жди автоматического запуска. Используй имя в запросе или `@`.
5. **Сделай запрос самодостаточным.** Передай область, нужные файлы, фон и формат результата.

Автоматический запуск не гарантирован. Claude выбирает субагента по описанию роли, твоей задаче и текущему контексту. Описание «помощник по коду» слишком широкое. Напиши, какую проверку делать и когда.

Если субагент не видит то, что обсуждалось раньше, это ожидаемо: о природе контекстного окна и почему Claude Code «забывает» проект я рассказывал в [отдельном разборе](https://vibeceh.ru/guides/kontekst-v-claude-code-zabyvaet-proekt). Передай детали повторно:

Если роль не запускается, не начинай с переписывания инструкции. Сначала перезапусти сессию, затем проверь путь и YAML. Пользовательские файлы в `~/.claude/agents/` иногда игнорируются даже при размещении по документации. Надёжного универсального восстановления из этой ситуации в официальных источниках нет.

Если роль запустилась, но не меняет файл, проверь инструменты. Это нормальное поведение при `tools: Read, Glob, Grep`. Read-only-проверяющий не должен редактировать код.

Не пытайся лечить это добавлением `Agent` или старого `Task`. По умолчанию субагент не запускает других субагентов (глубина вложенности зависит от версии Claude Code). Последовательность должен запускать основной Claude.

Перед повторной попыткой сверь чек-лист:

- файл называется `.claude/agents/code-reviewer.md`;
- внутри есть `name`;
- `description` описывает конкретное условие запуска;
- `tools` не содержит лишних разрешений;
- сессия перезапущена;
- вызов сделан явно;
- запрос не зависит от невидимой переписки;
- задача соответствует доступным инструментам.

## Вопросы и ответы

Субагент Claude Code - отдельный исполнитель внутри текущей сессии. Он берёт одну задачу, работает в собственном контексте и возвращает основному Claude итог. Для первого запуска подходит проверка файлов или объяснение части проекта без изменения кода.

В этой инструкции используется плоская схема: основной Claude передаёт конкретную задачу отдельному субагенту. Субагент не получает всю историю разговора и не запускает других субагентов. Его роль задаётся отдельным Markdown-файлом с инструкцией и ограничениями инструментов.

Claude Code может выбрать субагента по описанию роли и текущей задаче. Автоматический выбор не гарантирован. Для обязательного вызова используй `@`, а для запуска всей сессии с одной ролью - `claude --agent <name>`.

Для первого проекта подойдёт `code-reviewer`, который читает изменения и возвращает найденные проблемы. Другой безопасный вариант - `code-explainer`, объясняющий выбранную часть проекта. Роль разработчика с доступом к редактированию лучше не брать первым запуском.

Субагенты могут выполнять доступные им действия в рамках заданной роли. При инструментах `Read`, `Glob` и `Grep` они читают и ищут файлы, но не редактируют их. Результат возвращается основному Claude в виде отчёта.

Доступ к внешним сервисам для отдельного субагента задаётся через `mcpServers`. В фактуре подтверждён сам способ подключения MCP-серверов, но нет готового официального сценария веб-поиска. Для первого запуска безопаснее оставить только локальное чтение проекта.

Связь субагентов с Codex в фактуре не описана. Эта инструкция посвящена механике Claude Code и не переносит её на другой инструмент без отдельного подтверждения.

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

Потому что инструменты `Read`, `Glob` и `Grep` дают доступ к чтению и поиску, но не к изменению файлов. Для редактирования нужны другие инструменты, однако первый сценарий безопаснее начинать с роли, которая только возвращает отчёт.

- [Claude Code Docs: Run agents in parallel](https://code.claude.com/docs/en/agents)
- [Claude Code Docs: Extend Claude Code](https://code.claude.com/docs/en/features-overview)
- [Claude Code Docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Claude Code Docs: Subagents in the SDK](https://code.claude.com/docs/en/agent-sdk/subagents)
- [Claude Code Docs: Tools reference](https://code.claude.com/docs/en/tools-reference)
- [Claude Code Docs: Common workflows](https://code.claude.com/docs/en/common-workflows)
- [Anthropic: How and when to use subagents in Claude Code](https://claude.com/blog/subagents-in-claude-code)
- [Claude Code FAQ](https://support.claude.com/en/articles/12386420-claude-code-faq)