Subagents в Claude Code: создание, 7 готовых ролей и сравнение со Skills, Slash-commands и Agent Teams в 2026

Главная боль работы с Claude Code на больших задачах одна: основной диалог быстро забивается логами тестов, выдачами grep, кусками файлов и трассировками ошибок. Через час сессия похожа на свалку, модель путается в контексте и начинает повторяться.

Субагенты решают именно эту боль. Это способ запустить отдельную мини-сессию Claude с собственным окном контекста, отдать ей узкую задачу и получить обратно только итог, без всего мусора, который накопился по дороге.

В статье разберём, что такое субагенты в Claude Code, как создать своего за пять минут, дадим семь готовых production-ролей (ревьюер, исследователь, тестировщик, security-чекер, рефакторщик, doc-writer, проверка миграций) и сравним субагентов со скиллами, слеш-командами и Agent Teams в одной таблице.

Если вы ещё не знакомы с самим инструментом, начните с обзорной статьи «Что такое Claude Code: обзор, цены и как начать пользоваться». Там разобрали интерфейс, тарифы и первый запуск.

В тему субагентов хорошо лечь после того, как вы освоились со слеш-командами Claude Code. Это следующая ступень: команды дают быстрый шорткат к действиям, а субагенты — целую новую сессию с другой ролью.

Статья пригодится не только инженерам. Субагентов используют аналитики для разбора больших датасетов, дата-сайентисты для исследования моделей, технические писатели, продакты и SEO-специалисты везде, где нужно изолировать узкую задачу от основного диалога. А если хочется освоить AI-инструменты системно, загляните в нашу подборку курсов по нейросетям и искусственному интеллекту: там 316 программ от коротких интенсивов до годовых.

Что такое субагент простыми словамиСкопировано

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

Аналогия из жизни. Представьте, что вы менеджер проекта. К вам приходит задача «проверить, нет ли в коде утечек памяти в модуле X». Вы можете попытаться разобраться сами, заваливая стол отчётами анализаторов. А можете позвать профильного инженера, дать ему узкое ТЗ, и через час получить обратно одну страницу с выводами. Стол остаётся чистым, у вас есть нужный ответ, контекст не размыт сотней мелочей.

Технически субагент — это .md-файл с YAML-метаданными в начале, который лежит в одной из двух директорий:

• ~/.claude/agents/ — пользовательские субагенты, доступны во всех ваших проектах
• .claude/agents/ в корне проекта — проектные субагенты, лежат в репозитории и приезжают к каждому, кто склонировал репо

Минимальный файл выглядит так:

---
name: reviewer
description: Проверяет код на качество, безопасность и стилистику. Возвращает список замечаний.
tools: Read, Glob, Grep, Bash
model: sonnet
---

Ты — ревьюер кода. Анализируешь diff или указанные файлы и находишь:
- ошибки логики и null-проверок
- проблемы безопасности (SQL-инъекции, XSS, утечки)
- нарушения стиля проекта
- сложные места, которые трудно поддерживать

Возвращай ответ списком: файл, строка, тип проблемы, краткое описание, рекомендация.
Не предлагай рефакторинги, которых никто не просил.

Всё. Перезапускаете Claude Code или вызываете /agents, и субагент становится доступен.

Зачем вообще нужны субагентыСкопировано

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

Сценарий первый: экономия контекста

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

С субагентом-исследователем основная сессия отдаёт команду «изучи модуль auth и верни схему: какие классы, какие методы, где точки расширения». Субагент уходит в свою сессию, читает двадцать файлов, возвращает страницу выводов. Основное окно остаётся чистым.

Сценарий второй: параллельная работа

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

Запустить пять субагентов параллельно — это отдельная фишка. Каждый работает в своём окне, через десять минут вы получаете пять независимых отчётов. Время прохождения упало в 3–5 раз.

Сценарий третий: контролируемые права

Иногда нужен ассистент, который только читает. Например, аудитор архитектуры, который ничего не должен менять, только смотреть. В YAML-конфиге субагента вы указываете tools: Read, Glob, Grep и всё, у него физически нет инструментов для записи. Даже если модель решит что-то «по-хорошему» отредактировать, харнесс ей этого не даст. Это полезный страховочный механизм для агентов, которые работают по правам в проде или на сервере.

Архитектура родитель-дочернийСкопировано

Когда основная сессия вызывает субагента, происходит следующее:

1. Родительская сессия передаёт субагенту короткий промпт-задачу. Никакого предыдущего диалога он не видит.
2. Субагент стартует в новом контекстном окне. Его системный промпт берётся из YAML-конфига и тела .md-файла.
3. Субагент делает свою работу: читает файлы, гоняет команды, ищет по коду. Все эти действия не попадают в окно родителя.
4. По завершении субагент возвращает короткое summary: обычно несколько абзацев или структурированный список.
5. Родитель видит только это summary и продолжает работу с этим коротким ответом в контексте.

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

Ещё один нюанс: субагенты не делят между собой состояние. Если два запущенных параллельно агента работают над одной кодовой базой, каждый видит её свежий снимок, но обмениваться выводами в реальном времени они не могут. Если нужно, чтобы агенты общались между собой, это уже другая абстракция, Agent Teams. Разберём её ниже в сравнительной таблице.

Встроенные субагенты — Explore, Plan и general-purposeСкопировано

Claude Code из коробки приходит с тремя встроенными субагентами. Они работают без всяких настроек, их можно вызвать командой /agents или просто попросить основную сессию делегировать задачу.

Встроенные субагенты — это хороший способ попробовать механизм без настройки. Откройте Claude Code в любом проекте и попросите: «используй Explore, чтобы найти все обработчики POST-запросов в репо». Получите аккуратный список, без сотни строк grep-вывода в основном окне.

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

Как создать своего субагента за пять минутСкопировано

Самый быстрый способ — интерактивная команда /agents. Она проведёт по шагам: имя, описание, инструменты, модель, системный промпт. На выходе создаст файл в нужной директории.

Если хочется руками, порядок такой.

Шаг 1: выбрать директорию

Решите, нужен субагент только в этом проекте или вообще везде:

• Только в проекте → .claude/agents/ в корне репозитория. Коммитите файл в git, и команда получит того же агента после git pull
• Везде → ~/.claude/agents/. Лежит в домашней директории, виден из любой папки

Шаг 2 — создать md-файл

Имя файла равно имени субагента плюс .md. Используйте kebab-case: code-reviewer.md, db-migration-checker.md, security-auditor.md. Имя должно быть осмысленным, потому что родительская сессия выбирает агента по описанию и косвенно по имени.

Шаг 3: заполнить YAML-frontmatter

В начале файла идёт блок между --- со следующими полями:

• name — короткое имя, совпадающее с именем файла
• description — главное поле. По нему родительская сессия решает, когда звать этого агента. Пишите конкретно: «когда нужно проверить SQL-миграцию на безопасность отката и блокировки больших таблиц», а не «помогает с миграциями»
• tools — список разрешённых инструментов через запятую. Если поле пропустить, агент получит все инструменты родителя. Для read-only роли указывайте только Read, Glob, Grep
• model — какую модель использовать: sonnet, opus, haiku. Для рутинных проверок берите haiku (дешевле и быстрее), для сложного анализа подойдёт opus

Шаг 4: написать системный промпт

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

• В первом предложении явно объявляет роль («Ты — ревьюер безопасности», «Ты — технический писатель»)
• Описывает, что субагент делает, а что нет («Ты не пишешь код. Ты только проверяешь и возвращаешь замечания»)
• Задаёт формат ответа («Возвращай ответ в виде маркированного списка: файл, строка, проблема, рекомендация»)
• Содержит примеры, если задача нетривиальная

Шаг 5: проверить

Запустите /agents и убедитесь, что ваш субагент появился в списке. Попросите основную сессию что-то ему делегировать. Если родитель не догадывается позвать вашего агента, значит описание слишком общее. Стоит переписать поле description конкретнее.

7 готовых ролей субагентов для типовых задачСкопировано

Это production-конфиги, которые мы используем в Checkroi и которые можно скопировать к себе. Сохраняйте файлы в ~/.claude/agents/ и пользуйтесь во всех проектах.

Роль 1: code-reviewer

Главный ассистент по ревью. Берёт diff или указанные файлы и возвращает структурированный список замечаний.

---
name: code-reviewer
description: Проверяет код на ошибки логики, безопасность и стилистику. Используй после правок или перед PR. Возвращает список конкретных замечаний с указанием файла и строки.
tools: Read, Glob, Grep, Bash
model: sonnet
---

Ты — старший инженер на ревью. Не пишешь код, только находишь проблемы.

Проверяй в таком порядке:
1. Логические ошибки и неверные условия
2. Null/undefined проверки
3. Безопасность: SQL-инъекции, XSS, секреты в коде, небезопасный десериализатор
4. Утечки ресурсов (файлы, соединения, таймеры)
5. Нарушения стиля проекта

Формат ответа:
- ⛔ КРИТИЧНО — баги и дыры безопасности
- ⚠️ ВАЖНО — потенциальные ошибки
- 💡 СОВЕТ — стилистика и улучшения

Каждый пункт: путь к файлу с номером строки, тип проблемы, что сломается, рекомендация.

Роль 2: researcher

Изучает кодовую базу и возвращает карту: какие модули, как они связаны, где точки расширения. Незаменим в незнакомых проектах.

---
name: researcher
description: Исследует кодовую базу и возвращает структурированную карту. Используй когда нужно разобраться в новом репо или модуле. Read-only.
tools: Read, Glob, Grep, WebFetch
model: sonnet
---

Ты — исследователь кода. Только читаешь, ничего не меняешь.

Получив задачу «разберись в X», возвращай:
1. Список ключевых файлов и их назначение
2. Главные классы/функции с короткими описаниями
3. Граф зависимостей: какие модули с какими общаются
4. Точки расширения: где удобно добавлять новую функциональность
5. Подводные камни: нестандартные паттерны, легаси, опасные места

Не предлагай изменений. Только описывай то, что есть.

Роль 3: test-runner

Запускает тесты, разбирает падения, возвращает короткий отчёт. Экономит контекст за счёт того, что выдача pytest или jest не попадает в основное окно.

---
name: test-runner
description: Запускает тесты, анализирует падения и возвращает структурированный отчёт. Используй после правок кода для быстрой проверки.
tools: Read, Bash, Glob
model: haiku
---

Ты — раннер тестов. Запускаешь тесты, парсишь вывод, возвращаешь отчёт.

Алгоритм:
1. Определи, какой фреймворк используется (pytest, jest, vitest, go test)
2. Запусти полный прогон или указанный поднабор
3. Собери падения: тест, файл, строка, тип ошибки, короткая выдержка из traceback
4. Не вставляй полные traceback и логи в ответ — только то, что нужно для диагностики

Формат: общий счёт passed/failed, потом список упавших с минимальной диагностикой.

Роль 4: security-auditor

Узкая роль на безопасность. Берёт указанный файл или модуль, проверяет по чек-листу OWASP-подобных проблем.

---
name: security-auditor
description: Проверяет код на типовые уязвимости безопасности (OWASP). Используй для аудита аутентификации, обработки ввода, работы с БД и файловой системой. Read-only.
tools: Read, Glob, Grep
model: opus
---

Ты — security-аудитор. Только читаешь, не правишь.

Чек-лист по каждому файлу:
- Инъекции (SQL, NoSQL, command, LDAP, OS)
- XSS в шаблонах и API-ответах
- Небезопасная сериализация/десериализация
- CSRF в state-changing endpoints
- Чувствительные данные в логах и ответах
- Жёстко зашитые секреты и токены
- IDOR (доступ к чужим объектам по ID)
- Path traversal
- Race conditions в критичных операциях

Формат ответа: для каждой находки — критичность (Critical/High/Medium/Low), файл и строка, что эксплуатируется, как починить.

Роль 5: refactorer

Берёт указанный кусок и предлагает рефакторинг с обоснованием. Не пишет код сразу, сначала план.

---
name: refactorer
description: Анализирует функцию или модуль и предлагает план рефакторинга с обоснованием. Сначала возвращает план, код пишет только по запросу.
tools: Read, Glob, Grep, Edit, Write
model: sonnet
---

Ты — рефакторщик. Работаешь в два шага.

Шаг 1 — план. Для указанного кода возвращай:
- Что не так сейчас (дублирование, сложность, нарушения SRP, плохая тестируемость)
- Какой паттерн применить
- Какие файлы тронуть и что в них изменится
- Чем это лучше текущего

Шаг 2 — реализация. Делаешь только после подтверждения. Минимальный возможный diff, без побочных изменений.

Роль 6: doc-writer

Пишет и обновляет техдокументацию по коду. Полезно при разрастании проекта, когда README и docs/ отстают от реальности.

---
name: doc-writer
description: Пишет и обновляет техническую документацию по существующему коду. Используй для README, docstrings, описаний API. Не выдумывает поведение — только описывает то, что в коде.
tools: Read, Glob, Grep, Edit, Write
model: sonnet
---

Ты — технический писатель. Пишешь сжато и по делу.

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

Если что-то в коде непонятно — пиши «требует уточнения» вместо догадки.

Роль 7: migration-checker

Проверяет SQL-миграции на безопасность раскатки в проде. Особенно нужна, если у вас большие таблицы и нужно не положить базу.

---
name: migration-checker
description: Проверяет SQL-миграции на безопасность раскатки. Ищет блокирующие операции на больших таблицах, проблемы с откатом, риски downtime. Read-only.
tools: Read, Glob, Grep, Bash
model: opus
---

Ты — DBA-ревьюер миграций.

Для каждого файла миграции проверяй:
1. Блокирующие DDL на больших таблицах (ALTER без CONCURRENTLY/ONLINE)
2. NOT NULL колонки без DEFAULT (требуют полного переписывания таблицы)
3. Создание индексов без CONCURRENTLY
4. Удаление столбцов без двухшаговой схемы
5. Изменение типов колонок, требующее ребилда
6. FOREIGN KEY без NOT VALID + VALIDATE
7. Транзакции, которые блокируют DDL
8. Откатываемость: можно ли применить down-миграцию без потери данных

Формат: для каждой миграции — оценка риска (Safe/Caution/Dangerous), список конкретных проблем, рекомендации.

Большие коллекции готовых субагентов на разные роли можно посмотреть в open-source репозитории awesome-claude-code-subagents: там 100+ готовых конфигов для разных стеков.

Subagent vs Skill vs Slash-command vs Agent TeamСкопировано

Эти четыре сущности в Claude Code часто путают. Они решают разные задачи и устроены по-разному. Чтобы было нагляднее:

Простое правило выбора:

• Если задача короткая и часто повторяется — slash-команда
• Если задача — это многошаговый workflow с известным алгоритмом — скилл
• Если задача засоряет контекст логами/файлами и не нужна в основном диалоге — субагент
• Если задача требует нескольких ролей, которые должны обмениваться промежуточными выводами — Agent Team

Подробный разбор слеш-команд и встроенных шорткатов есть в нашем материале «37 команд Claude Code в 2026»: там 37 команд с примерами вызова и сценариями.

Как делегировать: что писать в parent-промптеСкопировано

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

Ошибка 1: слишком общий запрос

Плохо: «посмотри код и скажи, что не так».

Хорошо: «используй code-reviewer, проверь файлы src/auth/*.py на проблемы безопасности и null-проверки, верни замечания списком».

Конкретное указание роли + конкретные файлы + конкретные критерии = чистый и полезный ответ.

Ошибка 2: попытка вести диалог с субагентом

Субагент не сохраняет состояние между вызовами. Каждый вызов — новая сессия с нуля. Если хотите «развить мысль» из ответа субагента, передайте ему контекст руками: «у меня от тебя был отчёт, теперь проверь только модуль X, опираясь на пункты 3 и 5».

Ошибка 3: отдать субагенту то, что нужно в основном диалоге

Если результаты работы агента нужны вам прямо сейчас в диалоге для обсуждения деталей, лучше сделать в основном окне. Субагент уйдёт думать на 5–15 минут, и потом всё равно вернётся с одним summary, которое придётся разворачивать дополнительными вопросами.

Субагент про «уйди разберись и вернись с готовым». Не про «помоги мне порассуждать».

Ошибка 4: запускать одного агента, когда нужно три

Если задача распадается на независимые подзадачи, запускайте параллельно. Например, «после изменений в API проверь: безопасность endpoints через security-auditor, актуальность тестов через test-runner, обновление документации через doc-writer, все три параллельно». Получите три отчёта за время одного.

Грабли и ограниченияСкопировано

Чтобы не наступить на типовые ошибки, держите в голове ограничения движка.

Рекурсия только на один уровень

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

Изоляция контекста

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

Стоимость в токенах

Запуск субагента — это новая сессия с системным промптом, который весит пару тысяч токенов. Плюс работа самого агента: чтение файлов, инструменты, ответ. По грубой оценке, один вызов субагента стоит в 1,5–2 раза больше, чем такой же запрос в основной сессии. На массовых задачах это заметно. Для дешёвой рутины ставьте model: haiku.

Зависимость от качества описания

Родительская сессия выбирает агента по полю description. Если оно общее («помогает с кодом»), родитель либо не позовёт агента, либо позовёт не того. Описание должно содержать триггер-условие: «когда X, используй для Y». Хорошее описание — половина пользы от субагента.

Не подходит для интерактивных задач

Если задача требует уточнений по ходу, субагент не подходит. Он запускается с одним промптом и работает до конца без обратной связи. Для интерактивной работы оставайтесь в основной сессии или используйте Agent Teams.

Дрейф ролей

На длинных задачах субагент-ревьюер может «увлечься» и начать предлагать рефакторинги. Это лечится жёсткой формулировкой в системном промпте: «ты не пишешь код. Ты только возвращаешь замечания. Любая попытка предложить реализацию — нарушение твоей роли».

Где научиться работать с Claude Code и AI-инструментамиСкопировано

Субагенты — это уже продвинутый уровень работы с AI-инструментами. Чтобы дойти до них с пользой, важна база: понимание, как устроены LLM, как формулировать промпты, как встраивать AI в реальные рабочие процессы.

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

Больше программ — в полном каталоге курсов по нейросетям и искусственному интеллекту

Если хочется свериться с фундаментом до курсов, прочитайте обзорный материал «Что такое нейросети простыми словами» и рассказ про AI-native людей: это даст контекст, для кого вообще создаются такие инструменты.

Из официальных источников по Claude Code обязательно прочитайте документацию Anthropic про subagents: там есть свежие детали по интерфейсу /agents и тонкости разрешений.