3-layer review и human checkpoints

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 approved before edits
- scope confirmed for current track
- diff reviewed before commit
- targeted checks passed locally

Здесь важен не сам файл как фетиш, а повторяемость. Когда у вас два-три параллельных 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, где решают не обещания, а сигналы: тесты, линт, сборка, типы, 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: прогнать форматирование, заблокировать коммит с утёкшим секретом, запустить небольшой регрессионный набор. В конфиге это может выглядеть так:

{
  "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, о конфигурации или о выпуске нельзя передать механизму, который проверял линт.

Хорошее правило для команды можно зафиксировать прямо в CLAUDE.md или policy-документе Workflow Kit:

## Правила слоя 3

Не выполнять без явного одобрения человека:
- merge в main
- deployment
- изменения в config и secrets
- destructive commands
- внешние write-actions

Это простой кусок текста, но он делает важную вещь: снимает двусмысленность. У агента нет пространства для «я подумал, что тут, наверное, можно»: high-risk упирается в человека. И это не недоверие к инструменту, а нормальная инженерная дисциплина. Никто не считает унизительным, что релиз подписывает ответственный инженер, а не shell-скрипт.

На этом слое также особенно важно иметь владельца зоны. Задели payments/, pricing/ или общий конфиг — решает не абстрактный «кто-нибудь из команды», а конкретный человек или роль. Иначе — коллективная безответственность: все участвовали, никто ничего не разрешал.

6. Hooks помогают, но не одобряют

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

Хороший способ думать о hook’ах — как о помощниках на проходной. Они подсветят проблему, не пустят очевидно плохое действие, вовремя подадут сигнал. Но инженерное решение за команду не принимают. 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

Track: feature/checkout-refactor
Layer 1: plan approved, diff reviewed
Layer 2: tests/lint/build green
Layer 3: merge paused until promo owner review
Decision: split PR, cherry-pick tests first

Это кажется мелочью, но именно такие мелочи делают 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 при этом честно знает свой потолок: он может остановить, но не одобрить. Выстройте эти рубежи — и автономность агентов перестаёт быть ставкой «а вдруг пронесёт»: она ограничена там, где риск реальный, и свободна там, где ошибка дешёвая.