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

Что такое субагенты Claude Code

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

Ключевое слово здесь — изоляция. Всё, что субагент прочитал по дороге — десятки файлов, длинный вывод тестов, тупиковые гипотезы, — остаётся в его контексте и не попадает в контекст основной сессии. Основной агент видит короткий результат: «ошибка в функции X, причина такая-то, вот три места, которые затронуты».

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

Зачем нужна изоляция контекста

Окно контекста — главный ресурс агента. В него одновременно помещаются инструкции из CLAUDE.md, история диалога, прочитанный код и вывод команд. Когда агент полчаса ищет причину бага, контекст заполняется мусором: файлами, которые оказались не при чём, и логами, из которых важна одна строка.

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

• Поиск и исследование. «Найди все места, где вызывается функция оплаты, и опиши, как они устроены» — типичная задача для субагента.
• Шумные проверки. Прогон тестов и разбор упавших — отдать субагенту, получить список причин.
• Чтение больших документов. Спецификация на сотни страниц нужна ради нескольких фактов — пусть субагент их извлечёт.

Как настроить субагента: папка .claude/agents

Собственный субагент описывается Markdown-файлом с YAML-заголовком. Файлы проекта лежат в .claude/agents/ в репозитории и доступны всей команде через git, личные — в ~/.claude/agents/ и работают во всех ваших проектах. Создать и отредактировать субагента можно и интерактивно, командой /agents в Claude Code.

---
name: code-reviewer
description: Проверяет изменения в коде на ошибки и нарушения правил проекта. Используй после завершения задачи, перед коммитом.
tools: Read, Grep, Glob, Bash
---
Ты — ревьюер кода. Тебе не нужно ничего исправлять.

1. Посмотри изменения: git diff.
2. Проверь каждое изменение на ошибки логики, обработку ошибок,
   безопасность (SQL, экранирование вывода, секреты).
3. Сверься с правилами из AGENTS.md.
4. Верни список замечаний: файл, строка, проблема, почему это важно.
   Если замечаний нет — так и напиши.

Что означают поля:

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

Как вызвать субагента

Главный агент может выбрать субагента сам, если задача подходит под его description. Надёжнее попросить явно: «Используй субагента code-reviewer, чтобы проверить изменения». Фразы вроде «используй проактивно» в описании повышают шанс, что агент вызовет его без напоминания, но не гарантируют этого.

Субагент-исследователь

Второй файл, который стоит завести почти в любом проекте, — исследователь только для чтения. Он отвечает на вопросы о коде и ничего не меняет.

---
name: explorer
description: Ищет в кодовой базе ответы на вопросы о том, где и как что-то устроено. Используй, когда нужно прочитать много файлов ради короткого вывода.
tools: Read, Grep, Glob
---
Ты исследуешь код и ничего не меняешь.
Верни: краткий ответ на вопрос, список файлов со строками,
на которые он опирается, и то, что проверить не удалось.

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

Схема «оркестратор и исполнители»

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

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

Слабое место схемы — передача задачи. Субагент знает только то, что ему написали. Поручение «почини тот баг, который мы обсуждали» для него пустое: он не видел обсуждения. Хорошее поручение читается как задача для нового коллеги, который впервые открыл репозиторий.

Что должен вернуть исполнитель

Задавайте формат ответа заранее: список файлов, вывод, найденные причины, что не удалось проверить. Короткий структурированный ответ экономит контекст оркестратора, а пункт «что не проверено» защищает от ложной уверенности — исполнитель, как и любой агент, склонен рапортовать об успехе.

Отдельный ревьюер: зачем отделять судью от исполнителя

Когда один и тот же агент пишет код и сам его проверяет, судья и подсудимый делят одну голову. Агент помнит, что хотел сделать, и видит в коде свой замысел, а не то, что написано. К тому же он заинтересован закончить: проверка превращается в формальность.

Ревьюер в отдельном контексте лишён этих проблем. Он не знает истории решений, видит только diff и правила проекта и оценивает результат свежим взглядом. Это тот же принцип, что и в живой команде: автор не принимает свой собственный pull request.

• Дайте ревьюеру только инструменты чтения и запуска проверок — без права редактировать файлы. Тогда он не начнёт «тихо исправлять» вместо того, чтобы сообщить о проблеме.
• Опишите критерии проверки явно: что считается ошибкой, какие правила проекта обязательны.
• Решение, что делать с замечаниями, оставьте оркестратору или человеку. Ревьюер находит, исполнитель исправляет.

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

Параллельный запуск субагентов

Claude Code умеет запускать несколько субагентов одновременно. Это ускоряет работу, когда части задачи действительно независимы: изучить три модуля, проверить изменения с трёх сторон (безопасность, производительность, тесты), собрать информацию из нескольких источников.

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

• Параллельно — исследование, анализ, ревью. Последовательно — правки в пересекающихся файлах.
• Если исполнители всё же пишут параллельно, разделите зоны: каждый работает только в своих файлах или в своей копии репозитория (например, в отдельном git worktree).
• Сводит результаты один узел — оркестратор, а не исполнители между собой.

Когда субагенты не нужны

Мультиагентная схема — это цена: больше токенов, больше времени, больше мест, где теряется информация при передаче. Субагенты Claude Code окупаются не всегда.

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

Типичные ошибки с субагентами

Размытое описание

Описание «помощник для кода» не помогает главному агенту выбрать, когда его звать. Пишите триггер: «после изменений в папке api/, перед коммитом».

Поручение без контекста

Субагент получает задачу без путей, без критериев готовности и без ограничений — и тратит половину работы на то, чтобы угадать, чего от него хотят. Лечится шаблоном поручения: цель, входные данные, ограничения, формат ответа.

Слишком широкие права

Исследователю и ревьюеру не нужно право редактировать файлы. Ограничение tools — дешёвый способ сделать роль механикой, а не просьбой в промпте.

Доверие к отчёту без проверки

«Все тесты прошли» в ответе субагента — это утверждение, а не факт. Оркестратор должен опираться на проверяемое: вывод команды, код возврата, конкретные строки.

Итог

Субагенты Claude Code — инструмент для трёх задач: держать основной контекст чистым, отделять проверку от исполнения и распараллеливать независимую работу. Описываются они короткими Markdown-файлами в .claude/agents/, а качество их работы почти целиком определяется описанием роли, набором инструментов и тем, насколько самодостаточно сформулировано поручение. Там, где задача маленькая или тесно связана с диалогом, один агент по-прежнему лучше. Переход от одного цикла к системе из узлов, рёбер и общего состояния подробно разобран на практике в курсе.