Субагенты Claude Code: настройка и примеры

Q: Работают ли субагенты Claude Code в Cursor?

Нет, формат .claude/agents/.md — специфика Claude Code; Cursor его не читает, там свои механизмы. Если нужна одна командная конфигурация под оба инструмента, смотрите разбор переносимости движка между Claude Code, Cursor и VS Code.

Коротко

Субагенты Claude Code — это отдельные ИИ-исполнители со своим системным промптом, своим набором инструментов и собственным контекстным окном, которых главный агент вызывает под конкретные подзадачи: ревью, тесты, аудит безопасности. Настраиваются они обычными markdown-файлами с YAML-шапкой в .claude/agents/ (проект) или ~/.claude/agents/ (глобально); обязательных поля два — name и description, правки подхватываются без перезапуска. Ниже — точный формат, пять готовых конфигов под типовые роли и честный список ситуаций, когда субагенты не нужны.

Что такое субагенты и какую проблему они решают?

Субагент — это специализированная копия Claude, которую основная сессия запускает как подрядчика: выдаёт задание, ждёт, получает краткий отчёт. Из этого следуют три практических выгоды.

Чистый контекст. Субагент работает в собственном контекстном окне. Если тестировщик перелопатил 30 файлов логов, эти токены не съедают контекст основной сессии — в неё возвращается только вывод.
Специализация. Узкий системный промпт («ты ревьюер, ищи баги, ничего не редактируй») стабильно работает лучше универсального «сделай всё сразу» — почему так, мы разбирали в статье про команду агентов-специалистов.
Ограничение прав. Ревьюеру можно выдать только чтение — он физически не сможет «починить» код в обход вас.

Если с Claude Code вы пока на «вы», начните с гайда для начинающих: субагенты дают эффект, когда базовый цикл работы уже освоен.

Как создать субагента: /agents или файл руками?

Исторически команда /agents открывала интерактивный мастер создания и управления агентами. В свежих сборках CLI (лето 2026) мастер убрали: команда лишь подсказывает попросить самого Claude сгенерировать агента или отредактировать .claude/agents/ вручную. Поведение зависит от версии, поэтому рабочих способа два:

Попросить Claude. «Создай субагента, который прогоняет тесты и разбирает падения» — Claude сам напишет файл с разумной шапкой. Быстро, но результат стоит вычитать: автогенерированные description часто расплывчаты, а это главное поле.
Написать файл самому. Дольше, но для боевых конфигов надёжнее: вы явно контролируете инструменты, модель и права.

Куда класть файлы: .claude/agents/ в корне репозитория — агент едет с проектом через git и виден всей команде; ~/.claude/agents/ — личные агенты, доступные во всех проектах. При совпадении имён побеждает проектный. Изменения Claude Code подхватывает на лету за несколько секунд.

Как устроен файл .claude/agents/*.md?

Файл состоит из двух частей: YAML-шапка (конфигурация) и markdown-тело (системный промпт агента). Основные поля шапки:

Поле	Обязательное	Что делает
`name`	да	Идентификатор агента: латиница и дефисы
`description`	да	По нему главный агент решает, кому делегировать задачу
`tools`	нет	Список разрешённых инструментов через запятую; если опустить — агент наследует все, включая MCP
`model`	нет	`haiku` / `sonnet` / `opus` / `inherit`; по умолчанию наследует модель сессии
`permissionMode`	нет	Режим разрешений: `default`, `acceptEdits`, `plan`
`maxTurns`	нет	Лимит шагов — страховка от зацикливания

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

Готовые конфиги: 5 типовых ролей

Каждый конфиг — отдельный файл в .claude/agents/, можно копировать как есть и править под свой стек. Больше вариантов ролей и промптов к ним — в разделе арсенала «Роли».

Ревьюер (code-reviewer.md) — разберём подробно:

---
name: code-reviewer
description: Ревью изменений кода. Вызывай проактивно после каждой правки src. Ищет баги и упрощения, файлы не редактирует.
tools: Read, Grep, Glob, Bash
model: inherit
---
Ты — строгий код-ревьюер. Работай только с диффом текущей задачи.
Порядок: прочитай изменённые файлы целиком, а не только дифф;
ищи логические ошибки, гонки, необработанные исключения.
Для каждой находки укажи файл, строку и сценарий отказа.
Отвечай списком по убыванию серьёзности. Нет находок — так и скажи.

Обратите внимание: в tools нет Write и Edit — ревьюер не может «тихо поправить» код, только доложить.

Тестировщик (test-runner.md):

---
name: test-runner
description: Запускает тесты и разбирает падения. Вызывай после правок кода и перед коммитом.
tools: Bash, Read, Grep
model: haiku
---
Определи тест-раннер по проекту (npm test, pytest и т.п.) и запусти релевантные тесты.
Каждое падение разбери отдельно: причина, файл, минимальный фикс. Код не правь — верни отчёт.

Аналитик (analyst.md):

---
name: analyst
description: Исследует кодовую базу до начала работы: где что лежит, какие модули затронет задача, какие есть риски.
tools: Read, Grep, Glob
model: sonnet
---
Твой результат — карта, а не правки. Верни: затронутые файлы,
зависимости между ними, риски и открытые вопросы к постановке задачи.

Документатор (docs-writer.md):

---
name: docs-writer
description: Обновляет README, CHANGELOG и docstring после изменений публичного API.
tools: Read, Write, Grep
model: haiku
---
Пиши коротко и только по фактам из кода. Если поведение неочевидно —
ставь TODO с вопросом, а не догадку.

Секьюрити (security-auditor.md):

---
name: security-auditor
description: Аудит безопасности изменений. Вызывай проактивно при работе с auth, пользовательским вводом, SQL и секретами.
tools: Read, Grep, Glob
model: opus
---
Ищи: инъекции, утечки секретов, широкие CORS, отсутствие валидации ввода.
Каждую находку подтверждай конкретной строкой кода. Ничего не редактируй.

Какие ошибки убивают пользу субагентов?

Расплывчатый description. «Помогает с кодом» — с таким описанием агент либо не вызывается никогда, либо вызывается невпопад. Лечится формулой «когда + что + чего не делает».
Инструменты по умолчанию. Опущенное поле tools наследует всё, включая подключённые MCP-серверы. Аудитору безопасности доступ к записи файлов и внешним API не нужен — режьте права осознанно.
Ожидание общей памяти. Субагент не видит переписку основной сессии: он получает только текст задания. Ветку, пути к файлам, критерии приёмки передавайте явно — по тем же правилам, что и постановку задачи агенту.
Зоопарк из двадцати агентов. Пересекающиеся описания превращают выбор исполнителя в лотерею. Начните с 3–5 ролей и добавляйте по необходимости.
opus везде. Тяжёлая модель для механических задач — это медленно и дорого. Тестам и документации обычно хватает haiku.

Когда субагенты не нужны?

Честный список, чтобы не городить архитектуру ради архитектуры:

Маленький проект или одноразовый скрипт. Накладные расходы на делегирование съедят выгоду: каждый субагент заново читает нужные файлы и тратит токены.
Линейная задача. Если шаги строго последовательны и каждому нужен полный контекст беседы, изоляция субагента будет мешать, а не помогать.
Нужны знания, а не исполнитель. Стайл-гайд, регламент, чек-лист — это про CLAUDE.md или skill, а не про отдельного агента.
Нужен повторяемый шаблон запроса. Это слэш-команда: она дешевле и предсказуемее.

Рабочее правило: субагент оправдан, когда у роли есть отдельная зона ответственности, свой набор прав и результат, который можно вернуть коротким отчётом.

Где взять готовую команду, а не собирать по одному агенту?

Пять конфигов из этой статьи — нормальный старт, собирается за вечер. Сложности начинаются на следующем шаге: чтобы роли не дублировали друг друга, результаты проверялись независимой ревизией, а постановка задач была единообразной, конфиги приходится долго калибровать друг под друга. Именно эту работу закрывает движок Quest: готовая команда из 8 согласованных агентов с откалиброванными ролями и контурами проверки из коробки. На момент июля 2026 движок стоит 4900 ₽ разово, дополнительные модули — по 1900 ₽; примерить состав под свой стек можно в конфигураторе.

Частые вопросы

Чем субагент отличается от скилла (skill)?

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

Видит ли субагент переписку основной сессии?

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

Можно ли запускать субагентов параллельно?

Да, главный агент может раздать несколько подзадач одновременно — например, тесты и ревью в параллель. Учтите, что параллелизм умножает расход токенов, поэтому механическим ролям ставьте model: haiku.

Работают ли субагенты Claude Code в Cursor?

Нет, формат .claude/agents/*.md — специфика Claude Code; Cursor его не читает, там свои механизмы. Если нужна одна командная конфигурация под оба инструмента, смотрите разбор переносимости движка между Claude Code, Cursor и VS Code.