Claude Code Subagents в 2026: пошаговая инструкция и 5 готовых примеров

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

Что такое subagent в Claude Code и почему это не «ещё один Skill»?

В документации Claude Code определение звучит так:

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

Subagents в Claude Code работают так же. Главный чат - директор. Subagent - специалист с узкой задачей, своим контекстом и набором инструментов. Когда задача матчится с описанием специалиста, директор делегирует - и сам не утопает в деталях.

5 целей, для которых Anthropic построил subagents

В документации Anthropic перечисляет ровно пять причин, зачем создавать собственного subagent:

Самое практичное из этого списка для непрограммиста - контроль затрат. Можно отправить тяжёлую research-задачу на дешёвый Haiku, а основной разговор продолжать на Sonnet или Opus. Экономия токенов прямо пропорциональная.

Важное ограничение - вложенности нет

Subagent не может породить другого subagent. Цитата из документации: «This prevents infinite nesting (subagents cannot spawn other subagents)». То есть глубина оркестрации - один уровень. Это упрощает архитектуру, но накладывает ограничение: если задача правда нужна в три уровня - её надо переразбить так, чтобы каждый subagent делал плоскую работу.

Чем subagent отличается от Skill, slash-команды и hook?

В предыдущем гайде про Skills я разбирал, что навыки и slash-команды в Claude Code фактически слились в один формат. Но subagent - это уже другая сущность, не просто «навык побольше».

Сводная таблица четырёх механизмов:

Хорошая формулировка из англоязычного гайда: skills - это рецепты, subagents - это специализированные коллеги.

По смыслу так: skills включаются автоматически по совпадению description с задачей, subagents вызываются явно - либо основной чат решает делегировать, либо ты зовёшь по имени.

Дерево решений «что выбрать»

Когда возникает мысль «надо чтобы Claude делал X», прогоняй её через 4 вопроса:

1. Это знание, которое должно быть всегда? Например, «у нас RU-локализация», «не используем длинное тире». Положи в CLAUDE.md.
2. Это методология с триггером, которую делаешь руками сейчас? Например, «каждый понедельник пишу отчёт по продажам». Делай skill.
3. Это задача, которую съест весь контекст основного чата, или которую можно запустить параллельно? Например, «глубокий research по 30 источникам», «security-аудит пока я пишу новую фичу». Делай subagent.
4. Тебе нужна автоматическая реакция на событие в Claude Code? Например, «после каждого Edit запускать линтер». Пиши hook.

90% задач предпринимателя попадают в первые две категории. Subagents - это инструмент следующего уровня, когда выходишь из режима «одна задача за раз» в режим оркестрации.

Где живут subagents и кто перекрывает кого?

Иерархия subagents - 5 уровней, сверху вниз по приоритету:

Логика приоритета такая же, как в Skills и CLAUDE.md: организация перекрывает CLI, CLI перекрывает проект, проект перекрывает личное, личное перекрывает плагин.

Что важно знать про подгрузку

Subagents подгружаются при старте сессии Claude Code. Если ты руками поправил файл агента на диске - изменения не подхватятся, пока ты не перезапустишь сессию. Через интерактивный UI /agents правки применяются мгновенно.

Один subagent в одном scope - один файл. Если у тебя в .claude/agents/ лежат code-reviewer.md и второй code-reviewer.md рядом (например, из старого бэкапа) - один из них Claude Code молча проигнорирует. Уведомления не будет.

Plugin subagents - отдельная история. У них есть ограничения по безопасности: они не поддерживают поля hooks, mcpServers и permissionMode. Это сделано, чтобы установка чужого плагина не давала ему права запускать произвольный код на твоей машине.

Как устроен файл subagent изнутри: frontmatter и тело

Минимальный пример из официальной документации - всего 9 строк:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Этого достаточно. Если в основном чате юзер говорит «проверь мой PR», Claude матчит «reviewer / code / quality» с description, делегирует на subagent. Subagent читает diff, выдаёт комментарии, возвращает summary в главный чат. Главный чат не загромождается логами и промежуточным анализом.

Полная схема frontmatter

Поле model: haiku - это и есть та самая «контроль затрат» из 5 целей. Если у тебя research-агент, который читает 50 страниц документации - запускай его на Haiku, экономия в 5-7 раз против Opus.

Поле isolation: worktree решает важную проблему: subagent делает потенциально опасные правки (рефакторинг, миграция), но ты не хочешь, чтобы он трогал твою рабочую копию. Указываешь isolation: worktree, и Claude Code сам создаёт временную git-копию проекта, subagent работает там, возвращает diff на ревью.

Тело файла - это системный промпт

После frontmatter идёт обычный markdown - это и есть системный промпт subagent. Никакой особой структуры не требуется, но проверенный паттерн такой:

1. Кто ты - одна фраза: «ты code-reviewer», «ты security-auditor», «ты documentation-maintainer».
2. Когда тебя вызывают и что ты делаешь сразу - первые 2-3 действия после получения задачи.
3. Чек-лист проверок или шагов - 5-10 пунктов, по которым subagent работает.
4. Что возвращаешь - формат итогового отчёта. Это критично: если не задать формат, subagent выдаёт «эссе», а не структурированный summary.
5. Чего НЕ делаешь - явные ограничения. Без этого блока subagent скатывается в творчество.

Тело файла можно держать в пределах 200-500 строк. Если становится больше - выноси длинные референсы в отдельные файлы рядом и в промпте делай ссылки.

Как написать description, чтобы Claude точно вызвал твой subagent?

Главная боль из тредов на Hacker News - человек ставит subagent для code-review, а Claude всё делает сам, не используя агента. Причина одна: description написан в стиле «Helper for code review». Claude не понимает, в каких ситуациях триггерить.

Формула рабочего description (3 части)

Часть 1 - что делает. Одно предложение про результат, не про процесс. Не «анализирует код», а «находит уязвимости в коде и возвращает список с severity и фиксом».

Часть 2 - когда триггерить. 3-5 фраз в кавычках, как реально просят пользователи. Не угадывай - посмотри в свою историю чатов и в реальные формулировки.

Часть 3 - когда НЕ триггерить. 1-2 фразы про похожие задачи, на которые этот subagent не должен реагировать. Без этого блока два близких агента постоянно конфликтуют.

Магическая фраза «use proactively»

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

То есть Claude по умолчанию склонен не вызывать subagent, если в описании нет явных сигналов. Добавляешь «use proactively» или «use immediately after writing code» - и активация резко повышается.

Сильный description выглядит так

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

Что здесь работает:

• Глагол «reviews» + «returns» - конкретный результат, не процесс.
• «Proactively» и «immediately after» - явный триггер.
• «Do not invoke for...» - закрывает конфликт с похожим subagent.
• Английский в описании - стандарт. Claude матчит лучше на английском, даже если основной диалог идёт на русском.

5 готовых subagent-ролей, которые работают через 10 минут

Каждая роль ниже - это один файл .claude/agents/<имя>.md. После создания файла - перезапусти Claude Code, открой /agents и проверь, что новый агент появился в списке. После этого можешь вызывать через @agent-имя.

1. code-reviewer - ревью кода после каждой правки

Это официальный пример из документации Anthropic, адаптированный под русскоязычный workflow:

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files only
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

Ключевое - tools: Read, Grep, Glob, Bash (только чтение и git diff), и Bash без права писать. Это базовая безопасность: code-reviewer не должен случайно что-то править.

2. security-auditor - поиск уязвимостей и утечек

Эта роль идёт с другой моделью - opus, потому что security-аудит требует более глубокого reasoning, и с memory: project - чтобы помнить контекст между сессиями:

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
memory: project
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1-2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Read-only по инструментам, model: opus для сложных проверок типа цепочек уязвимостей.

3. research-agent - глубокий research через 8+ источников

Это паттерн, который описывает сам Anthropic в статье про multi-agent research system. Ключевое - явный формат вывода и запрет на дамп сырых результатов:

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3-5 sub-queries
2. WebSearch each sub-query, fetch top 3-5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 - страховка, чтобы research не уходил в бесконечную итерацию. Anthropic в своей multi-agent системе репортит цифру:

Девяносто процентов - это в Bench-задачах research. На практике для бизнес-задач прирост скромнее, но порядок такой.

4. doc-maintainer - синхронизация документации с кодом

Эта роль на model: haiku - типичный пример «контроля затрат». Документация не требует Opus, Haiku справляется за треть цены:

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent - безопасный рефакторинг через worktree

Эта роль использует isolation: worktree - subagent работает в отдельной копии репозитория, ты потом merge'ишь только если ОК:

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

С такой ролью самая болезненная проблема рефакторинга «сломал и не знаю как откатить» отпадает: исходная копия не тронута, subagent работает в изолированном worktree.

Хочешь не просто скопировать готовые subagents, но и собрать связку, которая делает Claude стабильным инструментом? Subagents - это часть ИИ-клона: способ дать Claude специализированную команду, которая работает в твоей логике. На практикуме за 3 эфира разбираем все три кита методологии: ИИ-клон (Skills + Subagents) + Второй мозг + Контекст-инжиниринг. Эта связка превращает Claude из помощника, который угадывает, в инструмент, который думает в твоей логике.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 26–28 мая  ·  2 000 ₽

Записаться →

Запускаем 5 subagents параллельно: оркестратор + исполнители

Параллельная оркестрация - это конструкция «дирижёр + оркестр». Дирижёр держит план, не пишет ноты сам, и проверяет то, что играют музыканты. Если кто-то сфальшивил - просит переиграть, не пытается доиграть за него.

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

Минимальный промпт оркестрации

В главном чате достаточно одной фразы:

Запусти пять subagents параллельно: три research-agent на разные источники
(Anthropic docs, GitHub repos, ИИ-блогеры), один critic-agent для отсева
слабых выводов, один summary-agent для финального документа.

Контекст: пишу гайд про X. Целевой объём - 2000 слов с источниками.
Перед стартом каждый читает CLAUDE.md.

Дальше Claude сам делегирует пятёрке агентов. Каждый работает в своём контексте: research-агенты идут по своим источникам, critic фильтрует, summary собирает. В главный чат возвращаются только итоговые выжимки.

Где параллельность реально окупается

Не везде. Параллельный запуск имеет смысл только когда:

1. Задачи независимы друг от друга. Если research-агент №2 ждёт результата research-агента №1, параллельности не получится - они станут последовательными по факту.
2. Задачи долгие. Параллелить ради «trim trailing whitespace» бессмысленно - overhead на запуск subagents съест выигрыш.
3. У тебя достаточно лимитов. Об этом в отдельном разделе ниже - параллельные subagents жгут токены быстро.

Multi-agent v2 от Anthropic - ещё один шаг

В мае 2026 Anthropic выпустил Multi-Agent Orchestration v2 с тремя важными отличиями от классического запуска параллельных subagents. Об этом - следующий раздел.

Что нового в Multi-agent v2: Orchestration, Outcomes, Dreaming

Multi-Agent Orchestration - shared filesystem + mid-workflow check-ins

Anthropic описывает фичу так:

Ключевое отличие от классических subagents - общая файловая система. Раньше каждый subagent работал в полной изоляции, и обмен происходил только через возвращаемый summary. Теперь специалисты могут писать в общую папку, lead-агент читает результаты по ходу работы, а не только в конце. Это решает проблему «весь день работали, в конце выяснилось, что у двоих несовместимые подходы».

Второе - mid-workflow check-ins. Lead-агент может прерваться, спросить «как там у тебя» у любого специалиста, скорректировать общий план. Это близко к реальной работе руководителя команды.

Outcomes - rubric вместо пошаговой инструкции

С Outcomes ты пишешь критерии успеха, а агент сам ищет способ их достичь. Отдельный grader проверяет результат в своём контексте, чтобы не быть «заражённым» reasoning'ом основного агента.

Плюс десять процентов на сложных задачах - это серьёзный прирост. Особенно когда задача формулируется как «соберите лонгрид с такими-то критериями качества», а не «следуйте шагам 1-7».

Dreaming - агенты накапливают опыт между сессиями

Это самая концептуально новая фича. Agent проходит по прошлым сессиям, находит паттерны ошибок и удач, обновляет memory store. Можно настроить ручную проверку перед применением, можно дать ему править память сам.

Anthropic репортит: Harvey (юр-tech компания) после внедрения Dreaming зафиксировал примерно 6-кратный рост успеха в legal-drafting задачах. Это уже работает в проде, не только в демо.

Что это значит для предпринимателя без программистов

Multi-Agent Orchestration пока что доступен через Claude Agent SDK, не напрямую в Claude Code CLI. Но направление ясное: оркестрация переходит от «руками запускаешь N subagents» к «описал задачу, lead-агент сам решил, кого и как делегировать». Если ты только начинаешь с subagents - не парься про v2 пока. Освой классический паттерн «1 главный чат + 3-5 subagents с разными ролями», и через 3-6 месяцев перейдёшь на Managed Agents естественно.

7 ошибок, из-за которых subagent лежит мёртвым грузом

Ошибка 1. Description в стиле «Helper for X» - не триггерится

Симптом: написал subagent, проверил структуру, всё валидно, но Claude его не вызывает на запросы пользователя. Причина почти всегда одна - description написан абстрактно: «Helper for code review». Лечение: пропиши 3-5 реальных фраз пользователя в кавычках прямо внутри description + фразу «use proactively» / «use immediately after».

Ошибка 2. Сделал subagent там, где должен быть Skill

Subagent дороже Skill - он создаёт свой контекст, грузит свой системный промпт, ест больше токенов. Если задача короткая, не съест основной контекст, и её можно сделать в один заход - это Skill, не subagent. Пример антипаттерна: subagent format-validator, который проверяет JSON-схему по 20 правилам. Это Skill: одна модель, никакой изоляции не нужно, контекст не загружается.

Ошибка 3. Запускать «60 параллельных агентов» с самого начала

Это самая массовая иллюзия. Видишь в твиттере «у меня 1500 агентов работают», думаешь «надо так же». На практике - 60 агентов жрут лимиты Pro-плана за час, генерируют гору противоречивых результатов, и в конце дня у тебя ничего готового нет.

Один практик из Medium формулирует это так:

Лечение: на старте - один subagent на одну задачу. Освоил - добавляешь второй с другой ролью. Освоил оркестрацию двух - переходишь к команде из 3-5. Прыжок «вчера ставил Claude Code, сегодня 20 параллельных» гарантированно ломает код и сжигает лимиты.

Ошибка 4. Все tools всем агентам

Если у тебя code-reviewer имеет доступ к Bash, Write и WebFetch - это огромная дыра в безопасности и в стоимости. Reviewer не должен иметь права писать в файлы и тем более ходить в интернет.

Лечение: жёстко ограничивай tools. Code-reviewer - только Read, Grep, Glob. Security-auditor - то же самое плюс при необходимости Bash для git diff. Research-agent - WebFetch, WebSearch, Read, Write. Не давай subagent больше прав, чем ему нужно для одной конкретной задачи.

Ошибка 5. Subagent дампит сырые результаты в основной контекст

Если research-agent возвращает в главный чат «вот все 30 страниц, которые я нашёл, разбирайся сам» - ты потерял главное преимущество subagents (изоляцию шума). Лечение: в системном промпте subagent явно требовать формат итога. «Return ONLY: 3-bullet TL;DR + 5-source list. NO code dumps, NO raw search results». Этот формат должен быть жёстким - subagent не должен иметь свободы «эссеизировать».

Ошибка 6. Vague invocations - расплывчатые запросы при делегировании

Subagent не видит историю основного диалога. Он стартует с чистого контекста + CLAUDE.md + что ты ему явно написал. Если ты пишешь «исправь авторизацию» - subagent будет фантазировать. Нужно: «Исправь OAuth redirect loop, где после успешного логина юзера редиректит на /login вместо /dashboard. Файл - src/lib/auth.ts».

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

Ошибка 7. Role-based agents вместо task-based

Соблазнительный паттерн: «давайте сделаем frontend-developer, backend-developer, qa-engineer, и пусть они работают как команда». Не работает. Каждый «роль» теряет контекст всего проекта, и они не могут договориться о деталях, потому что не видят друг друга.

Лечение: subagent = повторяющаяся задача с явным выходом, не роль. Не «frontend-developer», а «explore-ui-tree», «refactor-component», «audit-accessibility». Каждый task-based subagent делает одну конкретную работу и возвращает один конкретный результат.

Сколько стоят параллельные subagents и когда они окупаются?

Грубые цифры из аналитики CloudZero (отчёт за 2026):

Pro-план задушится за час, если запускать 5 параллельных subagent на сложных задачах. Max 5x ($100) - это реалистичный минимум для регулярной параллельной работы. Команды и Enterprise - там вопрос о деньгах уже решается на уровне бюджета на инструменты.

Подробнее про экономию токенов в Claude Code - в отдельном гайде про лимиты. В контексте subagents главное правило: subagent окупается на задаче от 10 минут чистой работы. Если задача меньше - не плоди subagent, делай в основном чате или Skill'ом.

Как встроить subagents в свой ИИ-клон и Второй мозг?

Subagent опирается на три вещи, которые должны быть в проекте до того, как ты сделаешь первого специалиста:

1. Правильный CLAUDE.md. Subagent перед стартом читает CLAUDE.md - это его «трудовой договор». Без него subagent не знает контекст проекта, не знает запретов, не знает тон. Будет фантазировать.

2. Базовые Skills. Skill = упакованная методология. Subagent подтягивает только нужные ему Skills, не загружает всё подряд. Без Skills subagent повторяет одну и ту же работу с нуля каждый раз.

3. Второй мозг - структура знаний. Папка business/ (или аналог в твоей нише) - это библиотека, к которой обращаются все subagents. Без неё subagent выдаёт средний ChatGPT-ответ, не отличимый от чужого.

Перевернуть этот порядок - значит получить хайп без результата. «У меня 60 параллельных subagents» при пустой business/ - это 60 средних ChatGPT-сессий с одинаковым подходом.

Полная связка - ИИ-клон + Второй мозг + Контекст-инжиниринг - это 3 кита, которые делают Claude стабильным. Subagents - часть ИИ-клона: способ дать Claude специализированную команду, которая работает в твоей логике.

Самый быстрый способ начать - скопировать code-reviewer из первого примера выше в .claude/agents/code-reviewer.md, перезапустить Claude Code и вызвать @agent-code-reviewer на следующем коммите. Через 5 минут будет понятно, нужны тебе subagents или хватает основного чата.

Полная схема по вайб-кодингу за вечер - ИИ-клон + Второй мозг + Контекст-инжиниринг. 3 эфира, записи остаются у тебя.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 26–28 мая  ·  2 000 ₽

Записаться →