Прохання "Перевір сторінку" лишає рев'юеру чимало рішень: шукати помилки в поведінці, оцінювати оформлення чи пропонувати інший спосіб написати код. У відповідь можна отримати охайний список зауважень, який майже не допомагає з вашим завданням. Розберемо, як передати субагенту 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 бриф допомагає зберегти ваше очікування, поки головний агент передає завдання рев'юеру. Постійний формат спрощує читання відповіді. Але брати участь усе одно доведеться, і ось у чому:
- головний агент складає доручення і передає його придатній ролі; ви задаєте очікувану поведінку і межі;
- рев'юер вивчає файли і повертає підстави висновків; а охоплення і суттєві знахідки перевіряєте вже ви;
- головний агент може уточнити звіт або виправити підтверджену помилку за окремим дорученням; ви вирішуєте, що змінювати і як підтвердити результат.
Для списку покупок підсумком буде не просто порада "додай виклик функції", а перевірене пояснення: за якої дії число застарівало, де порушувалося оновлення і що змінилося після виправлення. З таким результатом уже можна працювати.