Ролі агентів і 3-шарова модель review

1. Межа ролі важливіша за список можливостей

Коли роль, тригер запуску, формат результату та stop conditions уже зібрані, саме час перевірити їх на першій по-справжньому робочій спеціалізації. Нею майже завжди виявляється reviewer: вузький, щоб не розповзтися в «агента на все», і корисний, щоб одразу вбудуватися в review-процес.

Коли ви вперше налаштовуєте агента, дуже хочеться думати в дусі «а давайте дамо йому побільше інструментів, щоб був корисніший». Думка природна, але саме з неї починається хаос — роль розповзається, відповідальність за нею. На виході не reviewer, не tester і не debugger, а дуже ініціативний знайомий, який обіцяв подивитися diff, а до вечора вже переписав півпроєкту.

У ролі агента є чотири прості опори: що він читає, що запускає, що пише і де зобовʼязаний зупинитися. Не визначено хоч одну — у вас не роль, а розмите побажання. «Це reviewer-агент» — недостатньо, доки ці чотири осі не задані явно.

Саме тому межа ролі починається не зі слів «вміє робити review», а зі слів «не має права правити код». Спочатку периметр, потім таланти. Інакше агент вирішить, що він не просто ревʼюер, а ревʼюер, розробник, архітектор і, якщо дати ще пʼять хвилин, трохи психотерапевт вашого репозиторію.

У контексті нашого Workflow Kit це особливо важливо. Файл agents/reviewer.md потрібен не заради красивої теки .claude/agents/, а як передбачуваний артефакт: людина відкриває його і одразу бачить — агент не впроваджує зміни, не сперечається зі scope, не «лагодить заодно» стиль і сусідні модулі. Одна робота: перевірити diff і повернути findings.

2. Чотири базові ролі агентів

Щоб не збирати кожного нового агента з нуля, корисно мати базові шаблони ролей. У курсі їх чотири: reviewer, tester, debugger і documenter — не «всі можливі агенти світу», а чотири зрозумілі каркаси, з яких потім зручно збирати майже все інше. І тут дуже допомагає дивитися на них не через красиві назви, а через осі read, run, write, stop.

Тепер давайте перекладемо таблицю на людську мову. reviewer перевіряє: чи відповідає diff задачі, чи не вийшов за scope, чи є evidence, чи не втрачено edge cases. Дайте право редагувати код — і він змішує автора та перевіряльника.

tester виглядає дуже схоже, але фокус у нього інший — сценарії перевірки: які тести є, чого бракує, що відтворити. Дозвольте змінювати production-код — стане тестувальником, який трохи виправив логіку, щоб усе пройшло. Так проблему ховають під килим.

debugger потрібен, коли ви ще не впевнені, у чому причина помилки. Почав «заодно рефакторити модуль, раз уже розбирався» — вийшов із ролі. Його результат: root cause, evidence і мінімальний план виправлення, а не архітектурне оновлення століття.

documenter багатьом здається найнешкідливішою роллю — і в цьому пастка. Без опори на код документація стає красивим вигадуванням. Він пише лише те, що підтверджується командами, файлами та реальною поведінкою системи.

Нижче — короткий приклад findings від reviewer-агента для PR у Commerce OS:

severity: medium
file: payments/RefundService.java:48
evidence: є перевірка статусу замовлення, але немає перевірки ролі оператора
suggested_action: додати guard і цільовий тест на доступ

Хороший результат ролі завжди виглядає саме так: коротко, перевірювано, без драми і без раптового «я вже все полагодив».

3. Схема ролі: read, run, write, stop

На попередній лекції ви вже розбирали тіло інструкції як контракт. Зараз корисно подивитися на те саме трохи технологічніше: чотири опори описують будь-яку роль і лягають на reviewer, tester і будь-яку майбутню спеціалізацію без магії та без літературних талантів. Відкрийте agents/reviewer.md із Workflow Kit не як frontmatter, а як схему обовʼязків:

read: diff, related files, tests
run: only safe local checks, якщо вони дозволені поточною конфігурацією
write: nothing
stop: if diff is too broad or touches a sensitive area

Точні назви tools і capability IDs залежать від поточного інтерфейсу /agents — тримайте в голові не список літер, а межу ролі.

Тут особливо важливі дві речі. Ось write порожня — у reviewer немає права писати. І останній рядок інструкції не декоративний: Зупинись, якщо diff занадто широкий — не ввічливе прохання, а інженерне правило. Не пропишете — агент буде «корисним» до кінця і почне коментувати все підряд, включно з тим, що вже час відправити на декомпозицію.

Початківці часто вчиняють одну й ту саму добру, але шкідливу дію: видають reviewer write-доступ «на випадок дрібних правок». Сьогодні описка, завтра форматування, післязавтра «трохи поліпшив» умову в бізнес-логіці — і це вже не reviewer, а тихий співавтор diff. Маленька незручність чесніша за зручного агента. З іншими ролями так само: tester пише тільки в тестові файли, documenter — лише в docs. Втрачаєте вісь write — роль тече; втрачаєте stop conditions — тече довго.

Але цієї схеми мало, щоб зрозуміти місце reviewer у процесі: вона описує лише саму роль. Далі потрібна ще одна координата — хто дивиться на докази і на якому gate вирішує, чи йти далі. Тести, збірка, lint, логи залишаються віссю доказів.

4. Трирівнева модель review

До цього моменту ми говорили про ролі так, ніби вони існують самі по собі. Але в реальній розробці агент не висить у вакуумі — він вбудовується в review-процес команди. Тут працює проста 3-шарова модель, і відповідає вона не «чим перевіряємо», а «хто і коли має право сказати: йдемо далі».

Сьогодні нас цікавить передусім Layer 1 — саме тут живе reviewer-агент поточного рівня. Поки diff перед очима, контекст свіжий, відкат дешевий, він ловить грубі проблеми до того, як зміна поїде в дорогі шари. Корисно уявити це як сходи:

flowchart TD
    D[Локальний diff] --> L1[Layer 1: локальний review]
    L1 --> L2[Layer 2: gate і автоматичні перевірки]
    L2 --> L3[Layer 3: team approval]

Модель із трьох шарів корисна навіть новачку. Немає Layer 1 — сирі зміни йдуть одразу в дорогу частину процесу. Немає Layer 2 — технічний барʼєр на совісті людей. Немає Layer 3 — чутливі рішення проходять тому, що «начебто все зелене». Локальний reviewer — не весь review, а перший, найшвидший і найдешевший шар. Він не вдає з себе Layer 2 і Layer 3: не затверджує реліз, не замінює командне рішення, не ставить фінальну печатку. Скромніший — і тому надійніший.

5. Review і verification: відмінності

Тут справді легко все змішати: поруч опиняються review-шари і вже знайома verification-вісь. Але завдання у них різні — review-шари потрібні як карта місця reviewer у процесі, verification відповідає за самі докази. Давайте акуратно розведемо це, поки суп не втік.

Мнемоніка коротка:

L + число — це verification.
Layer + число — це review.

На прикладі Commerce OS це виглядає так. Припустімо, ви виправляєте повернення коштів. Verification каже — запусти регресійний тест, перевір цільовий сценарій, переконайся, що збірка ціла. Review каже інше — спочатку локально прочитай diff, потім пропусти через технічний gate, а якщо зачеплена чутлива фінансова логіка, фінальне рішення за людиною.

Тобто verification — докази, review — ворота. reviewer-агент Layer 1 не підміняє тести: він перевіряє, що докази є, що вони підходять до задачі, і що diff не вдає, ніби все перевірено, коли насправді перевірено півтора сценарії та два молитовні жести над терміналом. Ця відмінність насправді дуже звільняє: перестаєте вимагати від нього «і знайди баги, і сам усе перевір, і виріши, чи можна в prod» — і чесна роль виявляється кращою за універсальний комбайн, який уміє все, але не відповідає ні за що.

6. Layer 1: спеціалізації одного reviewer

Коли базова reviewer-роль стала зрозумілою, виникає наступна спокуса: а давайте створимо окремого агента на кожен випадок життя. reviewer-security, reviewer-performance, reviewer-tests, reviewer-architecture, reviewer-db, reviewer-frontend і парочку на важкий понеділок. Технічно можливо, методично — не завжди. Набагато корисніше думати про них як про спеціалізації однієї reviewer-ролі.

Сенс тут дуже практичний: один базовий шаблон reviewer, а фокус задається інструкцією, варіацією description або додатковим контекстом. Інакше .claude/agents/ перетворюється на маленький зоопарк, де половина агентів відрізняється на одну фразу, а друга забула, навіщо її створювали.

У Commerce OS це добре видно на одному й тому самому diff. security reviewer подивиться, чи не обійшли перевірку прав під час повернення коштів. performance reviewer помітить зайвий запит у циклі. test quality reviewer запитає, чому немає тесту на повторний запит повернення. Не три механіки — три пари окулярів у одного локального reviewer-шару. Хочете оформити спеціалізацію файлом — вона компактна:

---
name: reviewer-security
description: Read-only reviewer focused on auth, secrets and input validation
tools: [read, grep, run_static_analysis]
---

Але це все ще Layer 1 reviewer. Він не перетворюється на службу безпеки компанії — дивиться на той самий diff під вужчим кутом.

7. agents/reviewer.md як живий артефакт

Найкорисніша думка фіналу цієї лекції дуже проста: агент — не «налаштування в продукті», а живий артефакт команди. Його читають, ревʼюять, оновлюють і іноді чесно спрощують. agents/reviewer.md добрий рівно настільки, наскільки допомагає пройти Layer 1 review швидше й акуратніше, без хибного відчуття безпеки.

Коли кодова база змінюється, має змінюватися і агент. Зʼявилися в Commerce OS нові чутливі зони — reviewer має знати, де вони. Втомилися від хибних спрацювань на дрібному стилі — вкоротіть інструкцію. Diff постійно занадто широкі — проблема не в reviewer, а в розмірі задач. Хороший агент не лікує організаційні хвороби магією — він робить їх виднішими.

Тому ставтеся до agents/reviewer.md як до шаблону PR, чек-листа релізу або CLAUDE.md: частина робочого процесу, а не священний текст. І тримайте його на своєму місці в моделі: це Layer 1, найшвидший і найдешевший шар, а не gate і не team approval. Reviewer-агент ловить грубі ризики по свіжому diff і передає матеріал далі — він не замінює ні автоматичні перевірки, ні рішення власника зони. Знає свою межу — економить команді дорогі шари review; вдає з себе всіх одразу — дає хибне відчуття безпеки. Чітка роль на зрозумілому шарі: саме цього ми від нього й хочемо.