Проектируем эффективного субагента

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

Одна задача, а не «помощник по фронтенду»

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

Причина практическая. Субагент стартует с чистым контекстом и получает одно сообщение с заданием. Чем у́же задача, тем меньше нужно объяснять в задании, тем точнее инструкция и тем проще проверить результат. Широкий субагент требует широкой инструкции, а широкая инструкция — это набор общих слов, которые ни на что не влияют.

Если задача распадается на две непохожие части — сделайте двух субагентов. Проверка контраста и проверка клавиатурной навигации могут жить в одном a11y-checker, потому что у них одинаковый вход, одинаковый выход и один читатель. А вот «проверить доступность» и «переписать компонент под новый API» — разные субагенты, даже если оба работают с одними файлами.

Description и инструкция — для разных читателей

В файле субагента два текста, и их часто путают.

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

# Слабо: описание работы, а не условие
description: Ревьюер кода

# Лучше: когда звать и что получится
description: Ревью изменений в текущей ветке перед созданием merge request. Use proactively, когда пользователь говорит, что закончил задачу или собирается открыть MR.

Описания всех ваших субагентов загружаются в основной контекст постоянно, поэтому держите их короткими: одно-два предложения.

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

Формат отчёта важнее всего

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

Плохой отчёт: «Я проверил код, в целом всё неплохо, есть несколько замечаний по стилю и одна потенциальная проблема с обработкой ошибок». Из него нельзя ничего сделать: непонятно, где, что и насколько серьёзно.

Хороший отчёт задан шаблоном в инструкции:

Верни отчёт строго в таком виде:

## Проблемы
Для каждой: `путь/к/файлу:строка` — суть проблемы — важность
(критично / стоит исправить / замечание) — что сделать.
Если проблем нет, напиши «Проблем не найдено».

## Что проверено
Список файлов и аспектов, которые ты реально просмотрел.

## Что не проверено
Что не удалось посмотреть и почему (нет доступа, файл слишком
большой, не хватило шагов). Если проверено всё — так и напиши.

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

Явные критерии готовности и честность о провалах

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

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

Поэтому в инструкции нужны прямые формулировки:

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

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

Минимум инструментов, подходящая модель

Дайте субагенту ровно те инструменты, которые нужны для задачи. Ревьюер получает Read, Grep, Glob и не может ничего изменить. Если ему нужно запускать тесты — добавьте Bash, но подумайте, стоит ли: субагент с Bash может сделать что угодно. Для подстраховки есть permissionMode: plan — режим только чтения на уровне разрешений.

Модель выбирайте по задаче. Для механических проверок с чётким чек-листом хватит более быстрой модели. Для ревью логики, поиска гонок и архитектурных замечаний нужна сильная. Поле maxTurns ограничивает число шагов — полезно, чтобы исследовательский субагент не ушёл в бесконечный поиск.

Пример: ревьюер изменений перед MR

Соберём всё вместе. Субагент для команды разработки, который проверяет ветку перед merge request:

---
name: mr-reviewer
description: Ревью изменений в текущей ветке перед merge request. Use proactively, когда пользователь говорит, что закончил задачу или собирается открыть MR.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
maxTurns: 25
memory: project
---

Ты — старший разработчик, делающий ревью перед merge request.
Твоя задача — найти проблемы, а не исправить их.

## Что делать
1. Получи список изменённых файлов: `git diff --name-only main...HEAD`.
2. Для каждого файла прочитай diff (`git diff main...HEAD -- <файл>`)
   и, если нужно понять контекст, сам файл.
3. Проверь: обработку ошибок, граничные случаи, безопасность
   (ввод пользователя, секреты в коде), соответствие соглашениям
   из CLAUDE.md, наличие тестов на новую логику.

## Чего не делать
- Не редактируй файлы и не запускай команды, меняющие состояние.
- Не оценивай стиль, если он не нарушает CLAUDE.md.
- Не делай выводов о файлах, которые не прочитал.

## Формат отчёта
### Критично
`файл:строка` — проблема — что сделать
### Стоит исправить
(тот же формат)
### Замечания
(тот же формат)
### Что проверено
Список файлов.
### Что не проверено
Что и почему. Если всё проверено — «Всё проверено».

Ты закончил, когда каждый файл из diff либо упомянут в проблемах,
либо перечислен в «Что проверено». Если diff пуст или ветка
не отличается от main — напиши об этом первой строкой.

Записывай в память повторяющиеся проблемы этого проекта,
чтобы в следующий раз проверять их в первую очередь.

Здесь есть всё из урока: узкая задача, description как условие срабатывания, только чтение через permissionMode: plan (при этом Bash нужен для git diff), шаблон отчёта с градацией, критерий готовности, инструкция на случай пустого diff и память проекта для накопления опыта.

Проверяйте на известном

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