Субагенты Claude Code: настройка и пять готовых ролей

Что такое субагент Claude Code и чем он отличается от Skill?#

В документации Claude Code субагенты описаны так:

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

Субагенты Claude Code устроены сходным образом: основной чат координирует работу, а специализированные помощники решают отдельные задачи. Когда запрос соответствует описанию субагента, главный чат может делегировать ему работу, оставив детали за пределами своего контекста.

Для чего Anthropic предлагает создавать субагентов

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

Для пользователя без опыта программирования особенно полезно управление расходами: исследовательскую задачу можно поручить Haiku, а основной разговор продолжить на Sonnet или Opus. Объём токенов зависит от задачи и её выполнения.

Проверяйте поддержку вложенности в установленной версии

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

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

В статье о Skills рассматриваются навыки и slash-команды Claude Code. Субагент — отдельный механизм, а не просто более крупный навык.

Сравнение четырёх средств:

Кратко: Skills можно представить как рецепты, а субагентов — как коллег со специализацией.

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

Как выбрать подходящий механизм

Если вы хотите поручить Claude новую задачу, ответьте на четыре вопроса:

1. Это постоянная информация? Например, правила локализации или форматирования текста. Добавьте её в CLAUDE.md.
2. Это методика с условиями запуска, которую нужно применить сейчас? Например, еженедельная подготовка отчёта по продажам. Оформите её как Skill.
3. Задача займёт значительную часть контекста основного чата или может выполняться одновременно с другой? Например, исследование множества источников или аудит безопасности. Рассмотрите субагента.
4. Нужно автоматически реагировать на событие в Claude Code? Например, запускать линтер после каждого Edit. Настройте hook.

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

Где хранятся субагенты и как работает приоритет?#

Уровни расположены в порядке приоритета:

Принцип приоритета сходен с правилами для Skills и CLAUDE.md: настройки организации имеют преимущество перед сессионными, затем идут проектные, личные и настройки плагина.

Когда изменения вступают в силу

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

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

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

Из чего состоит файл субагента: frontmatter и основная часть#

Краткий пример из официальной документации:

---
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 и поручить работу субагенту. Тот изучит diff, подготовит замечания и передаст краткий отчёт в основной чат.

Поля frontmatter

Значение model: haiku позволяет поручить задачу модели Haiku, когда её возможностей достаточно. Реальный расход зависит от объёма работы и конфигурации.

Параметр isolation: worktree помогает отделить потенциально рискованные изменения, например рефакторинг или миграцию, от основной рабочей копии. Claude Code создаёт временную копию проекта в git worktree, где субагент выполняет задачу; полученный diff можно проверить.

Основная часть файла — системный промпт

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

1. Роль: кратко укажите специализацию, например code-reviewer, security-auditor или documentation-maintainer.
2. Действия при запуске: перечислите первые два-три шага после получения задачи.
3. Список проверок или этапов: задайте от пяти до десяти пунктов.
4. Формат результата: опишите структуру отчёта, чтобы получить краткий и удобный для проверки ответ.
5. Ограничения: перечислите действия, которые субагенту выполнять нельзя.

Основную часть можно ограничить 200–500 строками. Более объёмные справочные материалы можно вынести в соседние файлы и сослаться на них в промпте.

Как составить description, чтобы Claude вызывал субагента?#

Общее описание вроде «Helper for code review» не объясняет, когда именно следует запускать агента. Поэтому конкретные условия делегирования стоит прописать в description.

Формула description из трёх частей

Часть 1 — действие и результат. Одним предложением объясните, что выдаёт субагент. Например: «находит уязвимости и возвращает список с уровнем серьёзности и рекомендациями по исправлению».

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

Часть 3 — исключения. Укажите одну-две похожие задачи, для которых агент не предназначен. Это помогает разделить обязанности близких по назначению субагентов.

Выражение «use proactively»

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

Добавьте в description конкретный сигнал, например «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...» отделяет эту задачу от работы doc-maintainer.
• Описание написано на английском; язык формулировок можно подобрать с учётом того, как модель распознаёт ваши запросы.

Пять примеров ролей субагентов#

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

1. code-reviewer — проверка изменений в коде

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

---
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
model: inherit
color: blue
---

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

При вызове:
1. Прочитай diff и список изменённых файлов от основной сессии. Если их нет, запроси у неё.
2. Изучи нужные файлы через Read, Grep и Glob.
3. Верни замечания без изменения файлов и команд оболочки.

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, Write и Edit. Основная сессия готовит и передаёт diff. Инструкция «запускай только git diff» не ограничила бы полностью выданный Bash.

2. security-auditor — аудит безопасности

Для глубокого анализа выбрана opus с теми же инструментами Read, Grep и Glob. Постоянная память из этого шаблона только для чтения исключена: её включение также добавляет возможность записи памяти:

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

Инструменты здесь преимущественно предназначены для чтения, а для сложных проверок выбран Opus.

3. research-agent — исследование по нескольким источникам

В статье Anthropic о многоагентной исследовательской системе описывается подход с явным форматом результата и без передачи необработанных поисковых данных:

---
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 задаёт предел шагов для исследовательской задачи. Anthropic сообщала о таком результате при сравнении многоагентной системы с одиночной моделью:

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

4. doc-maintainer — актуализация документации

В примере выбрана модель 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 позволяет выполнять изменения в отдельной копии проекта и затем проверять diff:

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

При таком подходе исходная рабочая копия остаётся отдельно, а изменения субагента можно просмотреть до объединения.

Параллельный запуск пяти субагентов: координатор и исполнители#

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

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

Пример запроса для координации

В основном чате можно задать задачу так:

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

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

Claude может распределить работу между указанными субагентами. Исследователи изучают назначенные материалы, critic проверяет аргументы, а summary-agent готовит сводный документ. В основной чат возвращаются результаты работы.

Когда имеет смысл работать параллельно

Параллельность подходит не каждой задаче. Она уместна, если:

1. Задачи независимы. Если второй исследователь не может начать без результата первого, работа будет последовательной.
2. Задачи достаточно продолжительны. Для мелкой правки время на запуск субагента может перевесить выигрыш.
3. Доступных лимитов хватает. Несколько субагентов могут быстрее расходовать доступный объём использования.

Multi-agent v2 от Anthropic

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

Возможности Multi-agent v2: Orchestration, Outcomes и Dreaming#

Multi-Agent Orchestration: общие файлы и промежуточные проверки

Anthropic описывает эту возможность следующим образом:

Общая файловая система позволяет участникам обмениваться рабочими материалами по ходу выполнения задачи. Ведущий агент может ознакомиться с ними до завершения работы всех специалистов.

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

Outcomes: критерии результата вместо пошаговой инструкции

С помощью Outcomes можно задать критерии успешного результата, оставив агенту выбор способа их выполнения. Затем отдельный grader оценивает результат в собственном контексте.

При таком подходе задачу можно описать через критерии качества, а не только через последовательность шагов.

Dreaming: накопление опыта между сессиями

Dreaming анализирует предыдущие сессии, выявляет повторяющиеся ошибки и удачные решения, а затем обновляет хранилище памяти. Можно включить ручную проверку изменений перед применением или разрешить системе обновлять память самостоятельно.

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

Multi-Agent Orchestration доступна через Claude Agent SDK, а не напрямую через Claude Code CLI. Для начала можно освоить классическую схему: основной чат распределяет задачи между несколькими субагентами с разными специализациями. Позднее этот опыт поможет перейти к инструментам Managed Agents, если они подходят для ваших задач.

Семь ошибок, из-за которых субагенты не приносят пользы#

Ошибка 1. Description вида «Helper for X» не задаёт условия запуска

Субагент может быть правильно оформлен, но не вызываться на запросы пользователя, если description слишком общее. Уточните триггер: добавьте три-пять характерных формулировок запросов и выражение вроде «use proactively» или «use immediately after».

Ошибка 2. Субагент используется вместо Skill

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

Ошибка 3. Сразу запускать десятки параллельных агентов

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

Ошибка 4. Выдавать всем агентам полный набор инструментов

Ревьюеру и аудитору выдавайте только Read, Grep и Glob и передавайте diff из основной сессии. Bash даёт возможность оболочки и не ограничивается автоматически git diff. Research-agent может получить WebFetch, WebSearch, Read и Write, если это соответствует его задаче.

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

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

Ошибка 6. Давать расплывчатые поручения

Субагент не получает автоматически всю историю основного чата. Ему доступны собственный новый контекст, CLAUDE.md и информация, явно переданная при делегировании. Поэтому вместо «исправь авторизацию» опишите конкретную проблему и укажите релевантный файл: «Исправь цикл OAuth-перенаправления: после успешного входа пользователя направляет на /login, а не на /dashboard. Файл — src/lib/auth.ts».

Передавайте контекст так, как если бы поручали задачу новому участнику проекта.

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

Набор ролей вроде frontend-developer, backend-developer и qa-engineer не всегда помогает разделить работу: каждому исполнителю может не хватать общего контекста проекта. Полезнее формулировать повторяемые задачи и ожидаемые результаты: например, explore-ui-tree, refactor-component или audit-accessibility.

Сколько стоят параллельные субагенты и когда они полезны?#

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

Подробнее об использовании лимитов Claude Code можно узнать в отдельном руководстве. В рамках субагентов учитывайте, сколько времени занимает задача и насколько полезно выносить её в отдельный контекст. Для небольших правок может оказаться достаточно основного чата или Skill.

Как связать субагентов с CLAUDE.md, Skills и базой знаний?#

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

1. Актуальный CLAUDE.md. В нём можно описать контекст проекта, правила и ограничения, которые субагенту важно учитывать.
2. Нужные Skills. Навыки задают повторяемые методики; для субагента можно указать только те, которые необходимы для его работы.
3. Структурированная база знаний. Организованные материалы проекта помогают субагентам учитывать важные сведения при выполнении задач.

Если контекста недостаточно, субагенту труднее учитывать особенности конкретного проекта. Поэтому его инструкции и источники знаний следует настраивать под реальные задачи.

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