3-layer review і людські контрольні точки

1. Автономність без точок контролю — це відкладений хаос

Коли ви вперше запускаєте кілька паралельних треків, виникає дуже спокуслива думка: «Ну все, тепер агенти самі розберуться, а я потім подивлюся підсумок». На папері це майже мрія. А на практиці дуже швидко виходить ситуація, де ніхто не знає, який план затверджено, який diff допустимий, чому CI червоний і хто дозволив чіпати payments/. Автономність добра рівно до тієї секунди, поки хтось не має взяти ризик на себе.

Тут важливо розвести два схожі, але різні поняття. Checkpoint — точка усвідомленого переходу між станами роботи: схвалення плану, дозвіл на edits, рішення про merge, підтвердження розгортання. Quality gate — бар’єр на перевірках: не пропускає зміну далі, поки не виконано умови. Простіше кажучи, checkpoint відповідає на питання «хто зараз приймає рішення», quality gate — «що має пройти, щоб це рішення мало сенс обговорювати».

У паралельній роботі без цих двох речей усе починає плисти. Уявіть Commerce OS: один трек рефакторить кошик, другий змінює знижки, третій пише тести. Не зафіксували, коли план approved, який diff у межах ownership і хто вирішує merge order — і хороші окремо зміни конфліктують, як сусіди, що одночасно вирішили свердлити стіну. Не злі. Просто немає координації.

Корисно дивитися на це як на інженерний конвеєр:

flowchart TD
    A[План] --> B[Зміни]
    B --> C[Layer 1
локальний review]
    C --> D[Layer 2
CI і quality gates]
    D --> E[Layer 3
людське схвалення]
    E --> F[Merge / випуск]

Ця схема здається простою, але в ній є важлива думка: людина не «заважає автоматизації» — вона ставить точки, де її перестає вистачати. Немає checkpointʼів — workflow не прискорився. Хаос просто відкладено на момент, коли ціна помилки вища.

2. 3-layer review як карта відповідальності

Коли розробник уперше чує про human checkpoints, він часто починає писати один нескінченний список: перевірити план, diff, тести, merge, розгортання, секрети, а потім ще раз про всяк випадок. Виходить не інженерна система, а тривожний список на холодильнику. Набагато корисніше розкласти точки контролю за знайомою вам моделлю 3-layer review.

Тут слово Layer — шар review-рішень: хто і на якому рубежі дивиться на зміну. Не рівень тестів, не таксономія session / worktree / Git / human.

Нижче — компактна карта, яка допомагає не плутатися:

Ця модель корисна тим, що прибирає зайві дублювання: не потрібно ставити одного «охоронця» біля кожних дверей. No-secrets scan уже стоїть blocking gate на Layer 2 — немає сенсу вручну перечитувати репозиторій на Layer 3, коли задача не high-risk.

Із цієї карти випливає ще одна корисна думка: шари не конкурують. Layer 1 дешевий і швидкий, Layer 2 беземоційний (йому байдуже, що агент «дуже старався»), Layer 3 потрібен там, де ціна помилки вища за ціну паузи. Нудніше за фантазії про автономну розробку — зате витримує реальний проєкт.

3. Layer 1: дешеві локальні checkpoints

Локальний review багатьом здається нудним етапом — саме тому його найчастіше й пропускають. Але правда в тому, що Layer 1 — найдешевший шар контролю: помилка тут коштує хвилини, а після merge кількох треків — уже годин і настрою всієї команди.

У паралельній роботі Layer 1 зазвичай включає чотири зрозумілі рішення. Спочатку хтось схвалює план або розбиття задачі. Потім, якщо задача нетривіальна, — checkpoint перед реальними edits. Далі — читання diff до commit. І нарешті — швидкий локальний прогін перевірок під поточний scope.

Для Workflow Kit це зручно зафіксувати простим артефактом, наприклад у CHECKPOINTS.md:

# CHECKPOINTS.md

## Рівень 1
- plan схвалено перед внесенням змін
- scope підтверджено для поточного треку
- diff переглянуто перед commit
- цільові перевірки пройдено локально

Тут важливий не сам файл як фетиш, а повторюваність. Коли у вас два-три паралельні workstreamʼи, пам’ять дуже швидко починає підміняти факти: «план наче обговорювали», «диф наче нормальний», «тести хтось запускав». Запис в артефакті повертає процес із туману в перевірювану реальність.

На цьому ж шарі reviewer-agent особливо корисний, але роль у нього має бути дуже скромна. Він не «приймає PR» — допомагає побачити scope creep, дивні зміни в сусідніх файлах, відсутність тестів, прогалини в reasoning. Хороший Layer 1: автор робить зміну, reviewer-agent повертає findings, людина читає diff і вирішує. Поганий: агент сказав «looks good», і всі радісно розійшлися.

4. Layer 2: детерміновані quality gates

Коли зміна виходить за межі локального контексту і рухається далі, потрібен шар, якому взагалі не важливо, хто писав код — ви, агент, колега чи дуже натхненна кавомашина. Layer 2 саме такий: CI і quality gates, де вирішують не обіцянки, а сигнали: тести, lint, збірка, типи, smoke checks, регресійні перевірки, перевірка секретів, наявність опису ризику.

Головна сила Layer 2 в тому, що він не сперечається. Падає ./gradlew test — ніяка харизма агента не зробить цей факт менш червоним. Не «як вам здається», а «пройшло чи ні».

Для Commerce OS на цьому шарі розумно тримати мінімум такий набір: тести за зачепленим модулем, збірка, статичні перевірки, smoke check для основного сценарію та no-secrets scan. Іноді додають AI-assisted review по diff — але порядок ролей пам’ятайте: AI review тут доповнення до deterministic checks, а не їхня заміна.

Навіть hookʼи найкраще почуваються саме на стику Layer 1 і Layer 2: прогнати форматування, заблокувати commit із витеклим секретом, запустити невеликий регресійний набір. У конфігурації це може виглядати так:

{
  "pre-commit": [
    { "name": "no-secrets", "command": "scripts/no-secrets.sh", "blocking": true },
    { "name": "format", "command": "scripts/format.sh", "blocking": false }
  ]
}

Тут дуже важлива дрібниця: blocking і non-blocking — принципово різні ролі. Форматування — помічник, підчищає хвости. Перевірка на секрети — справжній gate. Але навіть блокувальний hook не «фінальний схвалювач»: він лише не пропускає зміну далі, поки умову не виконано.

Ще одна важлива думка: gate, який ніколи не падає, марний — він поверхневий або його давно не переглядали. Gate, що падає в половині задач через шум, теж поганий: команда починає його ігнорувати. Справжній quality gate ловить реальні порушення і залишається вузьким, щоб йому вірили.

5. Layer 3: дорогі рішення залишаються за людиною

На Layer 1 і Layer 2 багато чого автоматизується, і це прекрасно. Але є зона, де автоматизація має вміти вчасно зупинитися й чесно сказати: «Далі, будь ласка, людина». Зазвичай це рішення, що зачіпають спільну історію проєкту, чутливі зони або дорогі наслідки помилки. Тут починається Layer 3.

У паралельній роботі Layer 3 особливо важливий, тому що саме тут найчастіше зустрічаються результати кількох треків одразу. Один агент підготував refactor checkout flow, другий правив promo rules, третій додав тести та документацію. Окремо все добре. Але рішення про merge order, про об’єднання в main, про конфігурацію або про випуск не можна передати механізму, який перевіряв lint.

Гарне правило для команди можна зафіксувати прямо в CLAUDE.md або policy-документі Workflow Kit:

## Правила рівня 3

Не виконувати без явного схвалення людини:
- merge в main
- розгортання
- зміни в config і secrets
- деструктивні команди
- зовнішні write-actions

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

На цьому шарі також особливо важливо мати власника зони. Зачепили payments/, pricing/ або загальний конфіг — вирішує не абстрактний «хтось із команди», а конкретна людина або роль. Інакше — колективна безвідповідальність: усі брали участь, ніхто нічого не дозволяв.

6. Hooks допомагають, але не схвалюють

Коли у workflow з’являється багато автоматизації, hooks дуже легко переоцінити. Вони справді зручні: нагадають про тести, відформатують, заблокують небезпечну команду, додадуть контекст, запустять перевірки після edits. Після кількох вдалих спроб виникає майже магічне відчуття: «тепер workflow сам себе охоронить». А це вже хибна безпека.

Добрий спосіб думати про hooks — як про помічників на прохідній. Вони підсвітять проблему, не пропустять очевидно погану дію, вчасно подадуть сигнал. Але інженерного рішення за команду не приймають. Hook не знає бізнес-контекст, не несе відповідальності за merge і не повинен схвалювати high-risk крок лише тому, що формальні ознаки зелені.

Це особливо важливо в multi-agent сценаріях. Hook блокує запис у payments/ — чудово. Але якщо зміна все-таки допустима, хто вирішить, що її можна проводити? Не hook. Людина на Layer 3. CI пройшов — отже можна merge? Не завжди: можливо, паралельний трек готує конфліктний випуск; можливо, власник домену ще не дивився diff; можливо, ризик технічно валідний, але продуктово сумнівний.

Тому корисно тримати в голові дуже просту формулу: hook може зупинити, але не може схвалити. Намагаючись стати «маленьким начальником», автоматизація перетворюється або на перешкоду, або на фальшиве відчуття безпеки.

7. Checkpoints живуть в артефактах, а не в голові

У перших спробах побудувати автономний workflow всю систему контролю тримають у голові. «Ми ж знаємо: читаємо план, потім diff, чекаємо CI, обережно merge». Поки один трек і одна людина — це ще працює. Щойно з’являється кілька workstreamʼів, пам’ять починає зраджувати. Саме тому checkpoints і gates перетворюємо на артефакти.

Для поточного рівня курсу особливо зручний той самий parallel-session-log.md. У ньому фіксуємо не лише те, які треки йшли паралельно, а й те, які шари review реально спрацювали:

# parallel-session-log.md

Трек: feature/checkout-refactor
Layer 1: plan approved, diff reviewed
Layer 2: tests/lint/build успішні
Layer 3: merge призупинено до review власника promo
Рішення: розділити PR, спочатку винести тести окремо

Це здається дрібницею, але саме такі дрібниці роблять workflow спостережуваним. Відкрийте лог у будь-який момент і не згадуйте, а бачте: де був людський checkpoint, де спрацював quality gate, де рішення відклали, де прийняли. На межі поточного блоку курсу такий лог особливо цінний: він показує, що extension + orchestration layer у вас засвоєно не на словах, а працює як система.

Часто поруч із цим логом має сенс тримати і CHECKPOINTS.md для команди — щоб спільні правила не залежали від пам’яті конкретного розробника. Розділення те саме, що для handoff-контракту: policy-версія CHECKPOINTS.md живе в Workflow Kit, а фактичне проходження треку через ці checkpoints фіксує runtime-лог поруч із проєктом.

Зберімо три шари в одну картину. Layer 1 ловить помилку за хвилину, поки вона дешева; Layer 2 беземоційно відсікає те, що не пройшло тести, збірку і no-secrets scan; Layer 3 залишає за людиною рівно ті рішення, де ціна помилки вища за ціну паузи — merge в main, розгортання, конфіг, чутливі зони. Hook при цьому чесно знає свою стелю: він може зупинити, але не схвалити. Вибудуйте ці рубежі — і автономність агентів перестає бути ставкою «а раптом пронесе»: вона обмежена там, де ризик реальний, і вільна там, де помилка дешева.