Subагенты Claude Code: настройка, конфигурация и сценарии использования

Большинство сессий Claude Code становятся медленными и загроможденными по одной и той же причине: каждый исследовательский grep, каждый дамп логов и каждое «подождите, я проверю еще один файл» навсегда остаются в основном разговоре.

Подагенты (subagents) существуют именно для решения этой проблемы. Они являются одним из базовых строительных блоков агентов, встроенных в Claude Code, предназначенных для обработки шумных задач, которые можно распараллелить, — это способ изолировать хаос в отдельном окне и вернуть только ту сводку, которая имеет значение.

Подагент — это не более умный Claude, и это не то же самое, что Skill (Навык). Это отдельный агент размышлений со своим собственным окном контекста, своим собственным списком разрешенных инструментов (allowlist) и без памяти о вашем текущем разговоре, если вы явно не создали от него ответвление (fork). Понимание этого различия — разница между настройкой подагентов, которая незаметно экономит ваш бюджет контекста, и той, которая просто добавляет задержку без какой-либо пользы.

Подагенты vs Навыки vs MCP

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

Полезное практическое правило: хук (hook) обеспечивает жесткое ограничение детерминированным образом, Навык дает основному агенту способность inline, а подагент предназначен для работы, которую вы хотите делегировать и полностью исключить из основного контекста. Если задача Навыка заключается в оркестровке инструмента, который еще не существует, это обычно признак того, что вам нужен сервер MCP, а не подагент. Claude Code не единственный в своей структуре — экосистема OpenCode имеет сопоставимую идею в своих специализированных агентах, которые разделяют планирование, исследование и ревью между специализированными ролями аналогичным образом.

Что такое подагент на самом деле

Три свойства определяют подагент Claude Code, и все три важны для того, как вы его используете:

• Изолированный контекст. Подагент начинает с чистого окна. Он не видит историю вашего разговора, если вы явно не создали от него ответвление, что предотвращает загрязнение его вывода тем, о чем вы обсуждали три хода назад.
• Ограниченный список разрешенных инструментов. Подагенты могут использовать только подмножество того, что уже есть у родительской сессии — они не могут предоставлять себе новые возможности, и хорошо спроектированный подагент должен получать только те инструменты, которые требуются для его задачи (например, инструменты только для чтения для исследовательского агента).
• Отсутствие видимости между подагентами. Подагенты не видят работу друг друга в процессе. Если задаче B действительно нужен вывод задачи A, это последовательная зависимость, а не то, что можно распараллелить между двумя подагентами.

Триггером для использования подагента является не «эта задача сложна». Это «эта задача шумная» — тот вид работы, который генерирует много промежуточного вывода (десятки чтений файлов, длинный лог, исследовательский grep по всему репозиторию), где ни один из этого промежуточного материала не должен сохраняться в вашем следующем ходе разговора.

Когда использовать подагента (а когда нет)

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

Плохие варианты: быстрые запросы на две секунды («что возвращает эта функция»), всё, что требует плотной обратной связи и уточнений, и зависимые задачи, которые вы пытаетесь «распараллелить», хотя вторая задача нуждается в ответе первой. Использование подагента для тривиального поиска просто добавляет накладные расходы на запуск нового окна контекста без реальной пользы от изоляции.

Измерение выгоды: математика контекста и стоимости

Питч для подагентов абстрактен, пока вы не подставите цифры в реальную задачу. Возьмем распространенную: grep по сервису с ~500 файлами, чтобы найти все места, где все еще считывается устаревший ключ конфигурации, а затем сообщить точные совпадения file:line.

Это примерно 15-20-кратное сокращение того, что должна нести ваша основная сессия для этого шага, что и является реальным механизмом за утверждением «подагенты ускоряют сессии» — это не магия, это контекст, который вообще никогда не загружается.

Сторона стоимости усугубляется тем же образом. Используя цены из разбивки цен на Claude Code, запуск этой же исследовательской итерации на Opus ($5/MTok вход, $25/MTok выход) обойдется примерно в $0.20-0.25 только за ~40K входных токенов. Маршрутизация на Haiku ($1/MTok вход, $5/MTok выход) снижает это до $0.04-0.05 — и бюджет Opus основной сессии вообще не затрагивается токенами исследования, поскольку она видит только сводку на ~2K токенов.

Определение пользовательского подагента

Пользовательские подагенты существуют как файлы Markdown с YAML-фронтматтером, либо на уровне проекта в .claude/agents/ (закоммичены в репозиторий, используются всей командой), либо на уровне пользователя в ~/.claude/agents/ (личные инструменты, которые вы берете с собой в каждый проект).

---
name: code-reviewer
description: >
  Reviews staged changes for bugs, security issues, and style violations
  before commit. Use when the user asks to review, audit, or check
  changes prior to committing or opening a PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
You are a careful code reviewer. Read the staged diff, flag concrete
issues with file:line references, and end with a short pass/fail summary.
Do not modify any files.

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

Поле tools — это ваша граница изоляции. Дайте исследовательскому подагенту Read, Grep и Glob и ничего больше; предоставление ему всех доступных инструментов нивелирует всю цель запуска его в ограниченном песочнице. Опциональное поле skills предварительно загружает полный контент названных Навыков в контекст запуска подагента — полезно, когда подагенту нужны знания предметной области, не тратя ход на их обнаружение и загрузку посреди задачи.

Маршрутизация моделей: дешевые модели для рутинной работы

Подагенты — это также место, где контроль затрат становится реальным. Маршрутизируйте обнаружение файлов, сканирование логов и другую работу, которую дешево проверить, на Haiku, и оставляйте Sonnet или Opus для шагов, требующих сложных рассуждений — архитектурные решения, неоднозначное отладки, всё, где ошибка стоит дорого. Haiku примерно в 15 раз дешевле на токен, чем Opus, и в том виде шумного исследования, для которого созданы подагенты, этот разрыв быстро накапливается в течение реальной рабочей сессии.

Паттерн Explore, Plan, Execute

Для сложной многоступенчатой работы паттерн, который оправдывает себя на практике, — это Explore, Plan, Execute (Исследуй, Планируй, Исполняй) — используя дешевые подагенты для частей, которые генерируют шум, и сохраняя шлюз ревью человека в том единственном месте, где он действительно важен.

Ключевой деталью, которую люди понимают неправильно, является то, где должен находиться шлюз ревью. Исследование дешево, поэтому позвольте подагенту читать свободно, не спрашивая разрешения сначала. Планирование аналитично, поэтому позвольте агенту самостоятельно разработать подход. Но прежде чем любой агент изменит файлы, вы хотите увидеть план и одобрить его — для этого предназначен режим планирования Claude Code (permissionMode: plan), и это тот же принцип, который обсуждается в более широких лучших практиках vibe coding вокруг ревью каждого diff до того, как он попадет в код.

Распространенные ошибки

Несколько ошибок появляются снова и снова, когда команды начинают писать пользовательские подагенты:

• Размытые описания. «Помогает с кодом» никогда не будет маршрутизироваться правильно. Назовите точное условие триггера.
• Чрезмерно широкий доступ к инструментам. Предоставление подагенту только для чтения доступ на запись и bash снимает гарантию изоляции, которая сделала его создание worthwhile в первую очередь.
• Параллелизация зависимых задач. Если задаче B нужен завершенный вывод задачи A, запускайте их последовательно — подагенты не могут координироваться посреди задачи так, как это может общий оркестратор. Для рабочих процессов, которым действительно нужны агенты, общающиеся друг с другом посреди задачи, это другая форма проблемы; см. паттерны оркестровки мультиагентных систем если вы строите production-систему, а не workflow для одного репозитория.
• Использование подагента для тривиальной работы. «Отформатируй этот JSON» или «выполни эту одну команду» не требует нового окна контекста; просто сделайте это напрямую.

Подробный пример: подагент code-review от начала до конца

Допустим, вы хотите, чтобы каждый нетривиальный коммит проходил ревью перед попаданием в main. Поместите определение code-reviewer, показанное ранее, в .claude/agents/code-reviewer.md, закоммитьте его, чтобы вся команда использовала одного и того же ревьюера, и вызовите его естественным запросом, например «проверь мои staged изменения перед коммитом». Claude Code сопоставляет ваш запрос с description подагента, запускает его с доступом только к Read, Grep и Glob, и он возвращает находки со ссылками file:line и сводку pass/fail — весь шум от файла к файлу, необходимый для этого, никогда не затрагивает вашу основную сессию.

Как это выглядит в основной транскрипции, с аннотациями:

You:  review my staged changes before I commit

Main: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,
       zero of it shown here]

Main: code-reviewer findings:
      - auth/session.go:142 — token refresh path doesn't handle expired
        refresh token; falls through to nil dereference
      - auth/session.go:203 — style: error wrapped without %w
      PASS/FAIL: FAIL (1 blocking issue)

Произошло шесть чтений файлов и один проход grep, и ваша основная сессия заплатила ровно за четыре строки этого. Этот разрыв — всё, что сделал подагент, против трехстрочной сводки, которую вы действительно видите, — это вся ценность предложения в одной транскрипции.

Если ваша команда также использует каркасы Spec-Driven Development, подагент ревью естественно встраивается в шаг валидации; см. GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows чтобы увидеть, как этот шлюз ревью сравнивается в портативных и интегрированных в IDE настройках SDD.

Стоит ли настраивать пользовательские подагенты?

Не в первый день. Встроенный универсальный подагент уже покрывает большую часть делегирования по исследованию и поиску, не требуя от вас написания ни одного YAML-файла, и одного прохода Explore-Plan-Execute достаточно для большей части повседневной работы. Пишите пользовательский файл .claude/agents/*.md только тогда, когда вы делегировали одну и ту же задачу вручную три раза — ревьюер кода, диспетчер тестов, агент поиска документации для одной конкретной внутренней библиотеки. Команды, которые пишут пять подагентов в первую неделю, обычно заканчивают с пятью устаревшими полями description, которые никто не обновляет, когда фактическое условие триггера дрейфует, что тихо ломает автоматическую маршрутизацию месяцами позже. Начните с нуля пользовательских подагентов, добавляйте по одному, и только когда повторение, а не теоретическая полезность, потребует этого.

Известные ограничения

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

• Нет рекурсивной делегации. Подагент не может породить своих собственных подагентов. Если задаче действительно нужен второй уровень делегации, это признак того, что вам нужна другая форма оркестровки — см. паттерны оркестровки мультиагентных систем чтобы увидеть, как это выглядит за пределами одной сессии Claude Code.
• Нет памяти между вызовами. Каждая диспетчеризация начинается с нуля, даже если вы вызывали тот же подагент пять минут назад для связанной задачи. Не существует встроенного механизма для того, чтобы подагент запоминал свой последний запуск.
• Изоляция — это allowlist инструментов, а не песочница. Подагент с доступом Bash все еще может касаться файловой системы и сети, как и любой другой вызов инструмента. Ограничение tools снижает радиус взрыва; оно не создает жесткую границу безопасности.

Устранение неполадок

Подагент никогда не срабатывает. Почти всегда проблема в описании. Перепишите его вокруг конкретного условия триггера вместо общего утверждения о возможностях, и дважды проверьте, что файл находится в .claude/agents/ (проект) или ~/.claude/agents/ (личный) с правильным расширением.

Подагент все равно сжигает слишком много контекста. Проверьте allowlist tools — чрезмерно широкий набор инструментов приглашает к чрезмерно широкому исследованию. Также проверьте, не следовало ли разделить задачу на два подагента вместо того, чтобы один делал всё.

Перечисленный навык не загружается внутри подагента. Claude Code пропускает отсутствующий или отключенный навык, названный в поле skills, вместо того чтобы завершать выполнение с ошибкой, и записывает об этом строку в вывод отладки (/debug из основной сессии, затем воспроизведите диспетчеризацию) — что-то вроде skill "security-checklist" not found, skipping. Запустите /doctor после этого, чтобы подтвердить, что остальная часть вашей настройки здорова.

Результаты кажутся непоследовательными между запусками. Это часто проблема маршрутизации моделей, а не проблема дизайна подагента — работа, требующая рассуждений, назначенная дешевой модели, будет варьироваться больше. Перенесите её на Sonnet или Opus и оставьте Haiku для детерминированных шагов с низкой неоднозначностью.

Подагенты — лишь часть гораздо более крупного набора инструментов; если вы сравниваете Claude Code с остальной частью экосистемы инструментов для разработчиков AI перед тем, как committing к этому workflow, этот обзор — хорошая следующая остановка.

Полезные ссылки

• Установка и настройка Claude Code для Ollama, llama.cpp, цены
• Claude Skills и SKILL.md для разработчиков
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• Что такое Vibe Coding?
• Паттерны оркестровки мультиагентных систем: Практическое руководство
• Глубокое погружение в специализированные агенты Oh My Opencode
• Инструменты для разработчиков AI: Полное руководство