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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для первого сценария достаточно плоской схемы: основной Claude вызывает одного read-only-проверяющего (подробнее о разделении задач между агентами - в разборе Claude Code против Codex). Не строй цепочку из исполнителей, пока не научился проверять одного.

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Создай каталог для помощников.

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

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

2. Создай Markdown-файл.

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

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

3. Добавь имя и описание.

   В YAML укажи name и description.

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

4. Оставь инструменты чтения.

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

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

5. Напиши системную инструкцию.

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

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

   markdown

   Скопировать

   ---
   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.

6. Сохрани и перезапусти сессию.

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

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

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

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

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

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

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

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

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

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

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

Use the code-reviewer subagent.

Task:
Review the authentication changes in this project.

Scope:
- src/auth/login.ts
- src/auth/session.ts
- src/middleware/auth.ts

Context:
The current task changes the authentication flow.

Return:
1. Critical issues.
2. File paths and line numbers.
3. Concrete safe fixes.
4. Open questions.

Do not edit, create, or delete files.

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

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-сервер - в пошаговой инструкции), но сам факт подключения не превращает помощника в готовый веб-поиск.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если субагент не видит то, что обсуждалось раньше, это ожидаемо: о природе контекстного окна и почему Claude Code «забывает» проект я рассказывал в отдельном разборе. Передай детали повторно:

Use the code-reviewer subagent.

Review only:
- src/auth/login.ts
- src/auth/session.ts

The change replaces cookie sessions with JWT sessions.

Return:
- critical issues;
- file paths;
- line numbers;
- safe fixes;
- open questions.

Do not edit files. If you cannot verify something, say "not found".

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

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

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

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

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

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