Суб-агенты — специализированные работники

Модуль: 8. Армия агентов | Время: ~30 мин теории + 45 мин практики

Суть урока

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

Ключевые концепции

• Суб-агент = отдельный агент с независимым контекстом (своё контекстное окно)
• 5 причин использовать: контекст, инструменты, переиспользование, специализация, стоимость
• Встроенные суб-агенты: Explore (read-only), Plan (read-only), General-purpose (все инструменты)
• Формат файла: Markdown с YAML frontmatter в .claude/agents/<name>.md
• Создание кастомного суб-агента: попросить Claude или написать файл вручную (мастер /agents из старых версий убран)
• Области видимости: проект (.claude/agents/), пользователь (~/.claude/agents/), CLI, managed, plugin
• Настройка: 18 полей frontmatter (роль, инструменты, модель, хуки, память, цвет и др.)
• Вложенность ограничена: по умолчанию суб-агенты могут вызывать других, но не глубже трёх уровней
• Когда НЕ использовать суб-агентов

Теория

Что такое суб-агент — технически

🎨 Образ: Суб-агент — как юрист на аутсорсе. Ты CEO, нужна юридическая экспертиза — ты не учишь право сам. Нанимаешь юриста, объясняешь задачу, он работает в своём кабинете и приносит готовый результат. Твой рабочий стол чист.

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

Используй суб-агента когда побочная задача засорит основной разговор результатами поиска, логами или содержимым файлов которые ты больше не будешь использовать. Суб-агент делает работу в своём контексте и возвращает только summary.

Создавай кастомного суб-агента когда ты постоянно запускаешь одного и того же работника с одними и теми же инструкциями.

Когда основной агент вызывает суб-агента — создаётся отдельный экземпляр Claude с чистым контекстом. Этот экземпляр:

• Получает конкретное задание и кастомный системный промпт (НЕ полный системный промпт Claude Code)
• Работает независимо — не видит историю основной сессии (исключение — fork, см. ниже)
• Имеет доступ только к разрешённым инструментам
• По завершении возвращает результат основному агенту и "умирает"
• Его контекст освобождается

Основной агент (накопленный контекст: 30K токенов)
│
├── Вызывает суб-агент "researcher"
│   ├── Суб-агент получает: задание + нужные данные
│   ├── Работает в чистом контексте (0 + задание = ~2K токенов)
│   ├── Собирает информацию, анализирует
│   └── Возвращает: сжатое summary (500 токенов) → умирает
│
Основной агент продолжает с summary
(30K + 500 = 30.5K — не 30K + вся работа суб-агента)

🎨 Образ: Суб-агент сжигает свой контекст как одноразовый стакан — выполнил задачу и в мусор. Основной агент получает только дистиллят: один абзац вместо 50 страниц логов.

Без суб-агентов каждое действие добавляется в основной контекст. Через 2 часа работы — контекст перегружен, модель начинает "забывать" ранние части разговора.

Про вложенность: в ранних версиях суб-агенты не могли вызывать других суб-агентов. Сейчас могут, но не глубже трёх уровней под основным разговором (предел настраивается переменной CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Для начала проще держать цепочку плоской: вызывай суб-агентов по очереди из основного разговора, так легче понять, кто что сделал.

5 причин использовать суб-агентов

Причина 1: Сохранение контекста

Сбор 50 страниц данных в основном агенте = 50 страниц в контексте навсегда. Делегируй суб-агенту → он соберёт, сожмёт до 1 страницы summary → вернёт. Контекст основного агента чист.

Причина 2: Ограничение инструментов

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

Суб-агент "исследователь" имеет доступ только к веб-поиску и чтению файлов. Суб-агент "кодер" имеет доступ к bash и редактированию файлов. Основной агент имеет всё.

Почему это важно? Суб-агент не может случайно удалить файл если у него нет доступа к bash. Принцип минимальных привилегий.

Причина 3: Переиспользование

Создал суб-агента "competitor-researcher" один раз → используешь в 10 разных проектах. Не нужно каждый раз описывать как проводить конкурентный анализ.

Причина 4: Специализация

Агент сфокусированный на одной задаче делает её лучше чем универсальный агент. "researcher" со специальным промптом для поиска информации → лучше чем "делай всё" агент пытающийся и искать и анализировать и писать одновременно.

Причина 5: Контроль стоимости

🎨 Образ: Не нанимай шеф-повара чистить картошку. Haiku для механической работы (собрать данные, отформатировать), Opus только для стратегии. Разница в цене между Haiku и Opus — в разы, до самой сильной модели — на порядок.

Разные задачи требуют разных моделей:

Сбор данных (механическая работа) → Claude Haiku ($1 вход / $5 выход за 1 млн токенов)
Анализ данных (требует рассуждения) → Claude Sonnet ($2 / $10)
Стратегические решения → Claude Opus ($4 / $20)

Цены API, на октябрь 2026. Актуальные цены и версии: Актуальное сейчас. Выбирая правильную модель для каждой задачи — экономишь в несколько раз на механических задачах.

Встроенные суб-агенты Claude Code

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

Explore — быстрый read-only поиск по кодовой базе

• Модель: по умолчанию как у основной сессии, можно переопределить
• Инструменты: только чтение (Write и Edit запрещены)
• Назначение: поиск файлов, навигация по коду, анализ структуры проекта
• При вызове Claude указывает уровень тщательности: quick (точечный поиск), medium (баланс), very thorough (полный анализ)

Plan — исследователь для режима планирования

• Модель: наследует от основной сессии
• Инструменты: только чтение (Write и Edit запрещены)
• Назначение: сбор контекста перед составлением плана
• Используется когда ты в plan mode и Claude нужно понять кодовую базу

General-purpose — универсальный для сложных задач

• Модель: наследует от основной сессии
• Инструменты: все доступные
• Назначение: сложные исследования, многошаговые операции, модификация кода

Вспомогательные:

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

Формат файла суб-агента (официальный)

Суб-агенты определяются как Markdown файлы с YAML frontmatter. Это официальный формат Anthropic:

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

Структура: YAML frontmatter (настройки) + тело в Markdown (системный промпт суб-агента). Суб-агент получает этот системный промпт, задание от основного агента, CLAUDE.md проекта и снимок git status, но НЕ полный системный промпт Claude Code и НЕ историю разговора.

Все поля YAML frontmatter (18 полей)

Где хранить суб-агентов (области видимости)

Проектные (.claude/agents/) — для команды, коммить в git. Пользовательские (~/.claude/agents/) — личные, доступны везде.

При конфликте имён побеждает более высокий приоритет.

Создание суб-агента: три способа

Способ 1: Попросить Claude (рекомендуемый)

В старых версиях для этого был мастер /agents. С версии 2.1.198 его убрали: команда /agents теперь только напоминает, что делать. Суб-агента создают просьбой к Claude:

Создай личного суб-агента market-researcher в ~/.claude/agents/:
исследует рынки и конкурентов, только читает файлы и ищет в вебе,
модель haiku, цвет green

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

Способ 2: Вручную — создать .md файл

Создай файл .claude/agents/market-researcher.md:

---
name: market-researcher
description: Исследует рынки и собирает данные о конкурентах. Используй когда нужно собрать информацию о рынке, конкурентах, ценах или трендах.
tools: Read, Glob, Grep, WebFetch, WebSearch
model: haiku
color: green
---

Ты исследователь рынков. Собирай данные из открытых источников,
анализируй конкурентов, находи тренды. Возвращай структурированное
summary с ключевыми находками.

Суб-агенты загружаются при старте сессии. Если создал файл вручную — перезапусти сессию для загрузки.

Способ 3: Через CLI (для автоматизации / быстрого теста)

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

CLI суб-агенты живут только в текущей сессии и не сохраняются на диск.

Выбор модели

Claude Haiku  → для механических задач (сбор данных, форматирование, поиск)
Claude Sonnet → для задач требующих рассуждения (анализ, код, написание)
Claude Opus  → для сложных стратегических задач (архитектура, критический анализ)

Приоритет выбора модели (от высшего к низшему):

1. Параметр model при конкретном вызове
2. Поле model в frontmatter суб-агента
3. Переменная окружения CLAUDE_CODE_SUBAGENT_MODEL
4. Модель основной сессии

Чтобы заставить всех суб-агентов работать на одной модели, добавь вторую переменную CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1: тогда она перекрывает остальное.

Примечание на октябрь 2026: Claude Haiku 4.5 может быть выведен из API не раньше 15.10.2026. Следи за страницей Актуальное сейчас.

Управление инструментами: tools vs disallowedTools

Allowlist — указать ТОЛЬКО разрешённые:

tools: Read, Grep, Glob, Bash

Суб-агент НЕ может редактировать файлы, писать, использовать MCP.

Denylist — запретить конкретные, остальное наследовать:

disallowedTools: Write, Edit

Суб-агент наследует ВСЁ кроме записи и редактирования файлов.

Если указаны оба — сначала применяется disallowedTools, потом tools.

Ограничение вложенных вызовов: Agent(type)

Когда суб-агент запускается как основной (через --agent), можно ограничить каких суб-агентов он может вызывать. Если вообще убрать Agent из списка tools, суб-агент не сможет никого запускать:

tools: Agent(worker, researcher), Read, Bash

Только worker и researcher разрешены. Остальные — блокируются. Глубину вложенности целиком ограничивает CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (значение 1 выключает вложенность).

Постоянная память (memory)

🎨 Образ: Суб-агент с памятью — как бухгалтер который ведёт записную книжку. После десяти аудитов твоего кода он знает все твои паттерны наизусть. Без памяти — каждый раз с нуля, как первый день на работе.

Суб-агент может накапливать знания между сессиями:

memory: project

При включённой памяти суб-агент автоматически получает инструкции для чтения и записи в свою MEMORY.md.

Цветовое кодирование

В терминале разные суб-агенты отображаются разными цветами. Доступны: red, blue, green, yellow, purple, orange, pink, cyan.

Визуально видишь кто сейчас работает.

Примеры кастомных суб-агентов (в официальном формате)

Code Reviewer (read-only):

---
name: code-reviewer
description: Анализирует код на баги, безопасность и качество. Используй ПОСЛЕ написания любого кода перед коммитом.
tools: Read, Glob, Grep
model: sonnet
color: red
memory: project
---

You are a code reviewer. Focus on code quality, security, and best practices.
Check your memory for patterns you've seen before.

Debugger:

---
name: debugger
description: Debugging specialist for errors and test failures. Используй когда есть конкретный error message.
tools: Read, Grep, Glob, Bash
model: sonnet
color: yellow
---

You are an expert debugger. Analyze errors, identify root causes, and provide fixes.

Build Validator (на дешёвой модели):

---
name: build-validator
description: Запускает тесты и проверяет что код компилируется. Используй перед каждым деплоем.
tools: Bash, Read
model: haiku
color: green
---

Run tests and build checks. Report only failures with error messages.

Суб-агент с собственным MCP сервером:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Вызов суб-агента: четыре способа

1. Автоматическая делегация — Claude сам решает на основе описания суб-агента:

Проанализируй производительность базы данных
→ Claude видит что есть суб-агент db-reader → делегирует

2. Упоминание в промпте — подскажи Claude:

Use the code-reviewer subagent to look at my recent changes

3. @-mention — гарантирует вызов конкретного суб-агента:

@"code-reviewer (agent)" посмотри на auth модуль

4. Запуск всей сессии как суб-агент:

claude --agent code-reviewer

Основной промпт заменяется на системный промпт суб-агента.

Foreground vs Background и fork

🎨 Образ: Foreground — отдал задание и ждёшь у двери пока сделают. Background — отдал задание и пошёл делать своё: агент работает параллельно, ты не простаиваешь.

• Foreground — блокирует основной разговор до завершения. Запросы на разрешения проходят к тебе.
• Background — работает параллельно пока ты продолжаешь. В интерактивных сессиях сейчас суб-агенты по умолчанию работают в фоне (включён fork mode). Запросы на разрешения всплывают в основной сессии с именем суб-агента.

Нажми Ctrl+B чтобы отправить текущую задачу в фон.

Fork — суб-агент, который наследует весь разговор (системный промпт, историю, инструменты, модель), а не стартует с чистого листа. Он использует общий кэш промпта, поэтому дешевле обычного суб-агента. Запустить fork вручную: /subtask <описание задачи>.

Когда использовать суб-агентов

✅ Используй суб-агентов:

• Задача производит массу вывода который не нужен в основном контексте (тесты, логи, документация)
• Нужно ограничить доступные инструменты или разрешения
• Работа самодостаточная и можно вернуть summary
• Задачи выполняемые многократно в разных проектах

✅ Параллельное исследование:

Исследуй модули authentication, database и API параллельно в отдельных суб-агентах

Каждый суб-агент исследует свою область независимо, потом Claude синтезирует находки.

❌ Не используй суб-агентов:

• Задача требует частого back-and-forth (итеративная доработка)
• Несколько фаз делят значительный контекст (plan → implement → test)
• Быстрые точечные правки (overhead > сама задача)
• Важна скорость — суб-агент стартует с нуля и тратит время на сбор контекста

Для быстрого вопроса по текущему контексту используй /btw вместо суб-агента — он видит полный контекст но не имеет инструментов.

Практика

Задание 1: Создать суб-агента "исследователь" просьбой к Claude

1. Открой Claude Code
2. Попроси: «Создай личного суб-агента market-researcher в ~/.claude/agents/», и опиши параметры:
   • Name: market-researcher
   • Description: объясни когда его использовать (2-3 предложения)
   • Tools: только чтение и веб-поиск
   • Model: haiku (экономия)
   • Color: green
   • Memory: не нужна
3. Открой созданный файл и проверь frontmatter
4. Протестируй: попроси Claude "используй суб-агент market-researcher для исследования топ-3 конкурентов в нише онлайн-образования"
5. Наблюдай как основной агент делегирует задачу суб-агенту в терминале (зелёный цвет)
6. Убедись что суб-агент вернул структурированное summary

Задание 2: Создать суб-агента вручную как файл

1. Создай файл .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
color: red
memory: project
---

You are a senior code reviewer. Analyze code and provide specific,
actionable feedback on quality, security, and best practices.
Update your agent memory with patterns and conventions you discover.

2. Перезапусти сессию Claude Code
3. Проверь: набери @ и убедись что code-reviewer есть в подсказках
4. Протестируй: @"code-reviewer (agent)" посмотри на файл server.ts

Задание 3 (бонус): Создать суб-агента через CLI

claude --agents '{"quick-search": {"description": "Fast codebase search", "prompt": "Search the codebase and return concise findings.", "tools": ["Read", "Grep", "Glob"], "model": "haiku"}}'

Инструменты и ресурсы

• Просьба к Claude — основной способ создать суб-агента (мастер /agents убран в версии 2.1.198, сейчас команда лишь напоминает о папках)
• claude agents — экран всех фоновых сессий (agent view, research preview), а не список файлов суб-агентов
• .claude/agents/ — папка проектных суб-агентов (.md файлы с YAML frontmatter)
• ~/.claude/agents/ — папка пользовательских суб-агентов (доступны во всех проектах)
• Встроенные агенты: Explore (read-only), Plan (read-only), General-purpose (все инструменты), fork
• Документация: https://code.claude.com/docs/en/sub-agents

Ключевые выводы

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

Файл суб-агента = Markdown с YAML frontmatter. 18 полей настройки: от модели и инструментов до памяти, хуков и собственных MCP серверов.

Принцип минимальных привилегий: tools: Read, Grep, Glob — researcher читает, не пишет. disallowedTools: Write, Edit — другой путь к тому же результату.

Haiku для сбора данных, Sonnet для анализа, Opus для стратегии. Правильная модель = экономия в разы.

Вложенность ограничена тремя уровнями. Для начала держи цепочку плоской: вызывай суб-агентов по очереди из основного разговора.

Суб-агент с memory: project накапливает знания между сессиями. Через 10 ревью кода он знает паттерны твоего проекта.

Что дальше

→ Команды агентов: параллельная работа