Как поручить ревью субагенту и проверить отчёт

Просьба "Проверь страницу" оставляет ревьюеру немало решений: искать ошибки в поведении, оценивать оформление или предлагать другой способ написать код. В ответ можно получить аккуратный список замечаний, который почти не помогает с вашей задачей. Разберём, как передать субагенту Claude Code понятное поручение и затем проверить, выполнено ли оно.

Если reviewer ещё не настроен, сначала создайте роль и выполните первый запуск. Здесь сосредоточимся на самом поручении и полноте ответа.

1. Что передать ревьюеру

Ревьюер проверяет чужую работу и возвращает замечания с основаниями. В наших примерах это настроенный пользовательский субагент с именем reviewer, которому доступны только чтение и поиск по файлам: Read, Grep, Glob. Он изучает код, но не исправляет его и не запускает страницу в браузере. Имя reviewer не создаёт такую роль автоматически: предполагается, что она уже настроена в вашем проекте.

При новом обычном запуске такой субагент не получает автоматически всю историю вашего разговора. Главный агент, с которым вы общаетесь, составляет для него отдельное задание. Поэтому важное требование вроде "две покупки с одинаковым названием считаются разными записями" должно попасть в поручение или в документ, который ревьюеру поручено прочитать. Этот порядок описан в документации по контексту субагентов; здесь речь о запуске пользовательской роли, а не о fork с копией разговора.

Сравните "Посмотри проект" и "Проверь удаление записей и обновление счётчика; код не меняй". Во втором случае уже понятно, куда смотреть и какого действия вы не ждёте. Осталось уточнить, что считать правильным результатом.

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

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

2. Четыре части поручения

Цель отвечает на вопрос, какое поведение нужно проверить. Для страницы списка покупок это добавление, удаление и счётчик записей. "Сделать проект лучше" слишком широко: непонятно, какое улучшение сейчас важно.

Вход указывает файлы и ожидаемое поведение. Одного пути к app.js мало, если из кода нельзя понять, разрешены ли одинаковые названия. Это продуктовое решение нужно передать явно. Заодно обозначьте, чем проверять: у нас это только чтение кода, без браузера.

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

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

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

Итак, вместо "Проверь страницу списка покупок" передадим следующее поручение. Его можно отправить сообщением или сохранить в REVIEW_BRIEF.md в корне проекта:

# Проверка списка покупок
Цель: проверить по коду добавление, удаление и счётчик.
Вход: index.html и app.js в корне проекта.
Ожидается: добавленный пункт появляется в списке;
счётчик равен числу пунктов; удаление одной записи
не удаляет другую запись с тем же названием.
Границы: файлы не менять; стили, мобильный вид и сохранение
списка между сеансами в эту проверку не входят.
Если нужного файла или требования не хватает, укажи пробел,
не додумывай его и верни результат по доступной части.
Результат: следуй формату reviewer; укажи, что проверено
и что осталось непроверенным. Отсутствие находок допустимо.

Формат reviewer разберём сразу ниже. Если постоянного формата у вашей роли ещё нет, его можно включить в то же разовое сообщение. Названия полей не обязательны: важна информация, которую они помогают не забыть.

Просьба "в отчёте сначала покажи три самые существенные находки" ограничивает объём ответа, а не глубину проверки. Если такой лимит нужен, попросите отдельно указать, есть ли другие находки. Останавливаться после третьего замечания и объявлять задачу проверенной нельзя.

3. Что сохранить в файлах

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

Output contract, или контракт результата, здесь означает согласованный формат ответа. Звучит солиднее, чем есть на самом деле: это обычные инструкции для ревьюера, не специальная настройка Claude Code и не автоматическая проверка качества. Формат помогает найти нужные сведения в отчёте, но не делает их достоверными.

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

Вот раздел, который можно добавить в текстовую часть уже существующего файла роли .claude/agents/reviewer.md, после его настроек:

## Формат результата
Укажи проверенные файлы и критерии.
Для каждой находки: место, ожидаемое поведение, основание,
условия проверки и влияние; приоритет поясни.
Отделяй подтверждённое кодом от непроверенных предположений.
Отдельно назови ограничения и недостающие данные.
Если проблем по критериям не нашёл, так и напиши.

Это фрагмент инструкции, не полный файл субагента. У нашей роли только чтение и поиск, поэтому постоянное поле "изменённые файлы" ей не нужно. В более широком отчёте сведения об изменениях должны отражать факты: нельзя заранее предписывать строку "изменённые файлы: нет" независимо от того, что произошло.

Когда бриф сохранён, отправьте главному агенту такой запрос:

Поручи reviewer прочитать REVIEW_BRIEF.md в корне проекта
и проверить указанные файлы по его критериям.
Верни итоговый отчёт целиком.

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

4. Как проверить отчёт

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

Удобно сопоставить каждый критерий брифа с ответом. Например, в учебном частичном отчёте получилось так:

Отсутствие строки про одинаковые названия не означает, что ошибок нет. При этом одна обоснованная находка про счётчик не закрывает пропущенную часть задания. Верните отчёт с конкретным уточнением:

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

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

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

Отчёт без находок тоже может пройти эту проверку. Например: "Проверены пути добавления и удаления, независимость одинаковых записей и обновление счётчика в index.html и app.js. По этим критериям проблем не нашёл; в браузере не запускал". Такой итог не обещает отсутствия всех ошибок в проекте. Он сообщает о результате в названных пределах, и при необходимости вы сверяете ключевые пути сами.

А вот "Не нашёл app.js по указанному пути, поведение удаления проверить не смог" означает нехватку данных, а не отсутствие ошибок. Тут нужно передать правильный путь и продолжить проверку. Короткий честный ответ полезнее длинного отчёта, в котором пробел спрятан.

Принять отчёт не означает поручить исправить всё перечисленное. Вы признали результат проверки обоснованным; какие изменения делать сейчас, решаете отдельно.

5. Когда нужен ещё один проход

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

Верни reviewer отчёт на уточнение: в находке про счётчик
не указан путь его обновления после удаления.
Пусть проверит этот путь и добавит основание для вывода.
Код не менять.

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

После исправления полезен ещё один проход по тому же брифу:

Поручи reviewer повторно прочитать REVIEW_BRIEF.md и проверить
текущий код удаления и счётчика. Прежняя находка:
после удаления счётчик не обновлялся.
Пусть укажет, устранена ли проблема и на чём основан вывод,
а также проверит, не затронута ли независимость записей
с одинаковым названием. Код не менять.

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

Отчёт может стать короче, длиннее или не содержать новых находок. Не в этом успех. Важно, чтобы прежний дефект был устранён, вывод опирался на текущий код, а непроверенные части оставались видны. Решили отложить исправление? Тогда сохраните подтверждённую находку и причину отсрочки; повторять ревью неизменённого кода только ради нового ответа незачем.

6. От поручения к проверенному результату

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

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

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