Гейт виробничих рішень команди

1. «У мене все готово» вже недостатньо

Коли ви самі працюєте в маленькій експериментальній гілці, легко жити за моделлю: «я все перевірив — отже, готово». У команді на продукті на кшталт Commerce OS вона ламається. Merge — це не лише технічний факт, а й організаційне рішення: хто бере на себе наслідки, якщо зміна зачіпає гроші, авторизацію, дані клієнтів або продакшен-конфіг.

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

Саме тому особиста готовність задачі, CI gate і team decision gate — це не одне й те саме. Вони відповідають на різні запитання.

Добра інженерна практика починається там, де ви перестаєте плутати ці три рівні. Автор може бути впевнений у коді, CI може бути зеленим, але лише team decision gate відповідає на запитання: чи готова команда поставити підпис під цією зміною. Це не бюрократія — це визнання того, що наслідки merge стосуються не лише автора гілки.

2. Layer 3 — це review, а не permissions

На попередніх модулях у вас уже зʼявилася трьохшарова модель review. Тут важливо не змішати її з іншими моделями курсу. У цій моделі третій шар називається Layer 3 і означає team approval gate: прийняти або не прийняти зміну після того, як локальний review і CI вже відпрацювали.

Зручно уявити це як коротку схему:

Layer 1: local review  ->  Layer 2: CI / quality gates  ->  Layer 3: team decision gate
      diff, tests,               lint, build, tests,            approvals, rollback,
      reviewer notes             deterministic checks           known risks, GO / HOLD

Тут легко заплутатися, тому що в попередньому модулі вам уже траплявся L3 — але в моделі permissions, тобто в іншому namespace курсу. Щоб у голові не було каші, тримайте просте правило: Layer 3 — про review, «хто ухвалює рішення»; L3 permissions — «що Claude та агенти взагалі мають право робити».

ask

deny

Це важлива відмінність. Gate не замінює перевірок, не проганяє тести знову і не пише код. Він бере вже зібране evidence — diff, CI, reviewer notes, risk notes — і перетворює все це на командне рішення: «доказів достатньо, ризикуємо merge/release» — або «ні, HOLD».

І так, HOLD — це нормальний результат gate. Не провал. Не сором. Не привід терміново вигадувати, як усе ж таки проштовхнути PR. Іноді найзріліша відповідь — це «код хороший, перевірки зелені, але мерджити зарано: staging не відстояв потрібний час, не призначено власника зони ризику».

3. Дві опори: risk classification і permissions

Якщо спробувати впровадити gate у вакуумі, вийде одна з двох безглуздих конструкцій. Або трьохсторінковий high-risk шаблон на кожну описку в документації — команда зненавидить саму ідею. Або рядок «ну, здається, ок», який усі пролистують. Виручають дві вже знайомі опори: risk classification і L3 team permissions.

Risk classification відповідає, наскільки ризикованою є зміна, і визначає, який шаблон рішення потрібен. Якщо задача low-risk, команді не потрібен довгий документ з rollback plan. Якщо задача review-required, уже потрібні не лише summary, а й evidence, checks, approvals. Якщо задача high-risk, без rollback і явних approverʼів рухатися далі не можна.

Permissions відповідають за enforcement. Це той випадок, коли наклейка «не чіпати» перетворюється на справжній замок, а не лишається папірцем на дверцятах холодильника. Якщо у вас у політиці написано, що міграції та destructive commands потребують окремого погодження, це правило має підтримуватися не лише словами, а й налаштуваннями.

Невеликий приклад такого enforcement може виглядати так:

{
  "permissions": {
    "ask": ["Edit(migrations/**)", "Bash(flyway *)"],
    "deny": ["Bash(git push --force*)"]
  }
}

Сенс тут не в синтаксисі, а в логіці. Claude або агент не можуть «випадково» прослизнути повз командні правила. Якщо gate каже, що high-risk зміна потребує окремого рішення, permissions мають щонайменше не дозволяти обійти це рішення технічно.

Виходить дуже здорова звʼязка. Risk classification каже, наскільки ситуація небезпечна. Permissions обмежують поле дій. Gate ухвалює фінальне командне рішення. Якщо прибрати хоча б один елемент, конструкція розсиплеться. Без risk classification ви не розумієте, який шаблон застосовувати. Без permissions gate легко обійти. Без gate команда залишається із зеленим CI, але без явної відповіді на запитання «хто бере на себе наслідки».

4. Один gate, три масштаби ризику

Найчастіша помилка новачка на цьому етапі — спробувати вигадати один «універсальний» шаблон на всі випадки життя. На практиці це майже завжди погана ідея. Якщо шаблон занадто короткий, він нічого не дає для складних змін. Якщо занадто довгий, він убиває швидкість на дрібницях. Тому production decision gate масштабується за рівнем ризику.

Цю ідею зручно тримати в такій таблиці:

Для low-risk зміни gate може бути зовсім коротким — наприклад, звичайною секцією всередині PR_DESCRIPTION.md, а не окремим файлом. Це важливий момент: не потрібно створювати новий артефакт на кожен PR лише заради краси структури. Найчастіше gate живе прямо в описі PR або в чеклісті релізу.

Найпростіший low-risk блок може виглядати так:

## Гейт виробничого рішення

### Підсумок змін
Оновлено інструкцію локального запуску в README.

### Фінальне рішення
Злиття схвалено. Зміна документації low-risk.

У цьому місці не треба зображати корпоративний театр. Немає сенсу писати rollback plan для абзацу в документації. Якщо команда починає так робити, вона сама собі риє яму з формальностей.

Для review-required зміни блок уже помітно багатший. Наприклад, ви змінюєте API-флаг у Commerce OS, не зачіпаєте базу і не лізете в auth, але все ж змінюєте робочу поведінку сервісу.

## Гейт виробничого рішення

### Рівень ризику
review-required

### Докази
CI green, diff reviewed, API contract preserved.

### Потрібні схвалення
Backend owner

### Фінальне рішення
Злиття схвалено.

Тут уже видно, що рішення не висить у повітрі. Є рівень ризику, є evidence, є конкретний власник зони, який подивився на зміну.

А ось high-risk варіант — зовсім інша історія. Якщо PR зачіпає refund flow, міграції або шлях авторизації, шаблон стає повним.

## Гейт виробничого рішення

### Рівень ризику
high-risk

### Потрібні схвалення
Payments owner, security owner

### Шлях відкату
Відкотити PR, вимкнути `refund_v2`, відновити попередній знімок схеми.

### Фінальне рішення
HOLD, доки не завершиться staging soak test.

Зверніть увагу на важливу річ: тут HOLD — це не «нам усе не подобається», а «нам потрібне ще одне доказове підтвердження перед merge». У сильній команді це вважається нормою, а не слабкістю.

Якщо ж ви працюєте самі, Layer 3 нікуди не зникає — він просто стискається до особистого рішення з явною паузою. І навіть у цьому випадку короткий блок на кшталт «summary + decision» допомагає не мерджити зміни за принципом «ну, здається, працює, поїхали».

5. Re-classification: ризик змінюється дорогою

Найпідступніша ілюзія на цьому етапі — думати, що ризик задачі визначається на початку, а потім залишається незмінним. У реальній розробці майже ніколи не так. Задача може починатися як звичайний feature PR, а через годину дослідження раптом виявляється, що без міграції таблиці або зміни auth path не обійтися. І в цей момент старий risk label уже неактуальний.

Це називається re-classification, і ставитися до неї потрібно спокійно. Це не ознака поганого планування. Це нормальна реакція команди на нову інформацію. Поганий не перегляд ризику, а відмова його переглядати.

Припустімо, у Commerce OS ви почали задачу як review-required: треба було додати новий прапорець для обробки повернень. Дорогою зʼясувалося, що старе поле в базі не вміщує новий статус, а отже потрібна міграція. У цей момент задача вже не та, з якою ви стартували вранці. У неї новий рівень ризику, а отже потрібен і новий gate.

Таку переоцінку дуже зручно фіксувати прямо в PR:

## Лог перекласифікації
- Initial: review-required
- Updated: high-risk
- Reason: DB migration required for `refund_requests.status`
- Action: added rollback and payments owner approval

Тут важливі дві речі. По-перше, re-classification фіксують явно, а не мовчки. По-друге, разом із нею змінюється не лише label, а й увесь decision process: додаються approverʼи, rollback, можливо staging soak test або додатковий smoke.

Окремо варто сказати про downscaling, тобто зниження ризику. Формально воно можливе. Практично це дуже небезпечна зона, тому що саме тут терміни починають нашіптувати на вухо різні погані ідеї. Якщо задача здавалася high-risk, а потім раптом «ну, здається, не така вже й небезпечна», знижувати рівень можна лише з явним схваленням, а не за принципом «давайте вже проштовхнемо PR до вечора». Інакше gate перестає бути захисним механізмом і перетворюється на інструмент самозаспокоєння.

6. Commerce OS: як це виглядає в реальному PR

Тепер зберемо все разом у проєктному контексті курсу. Уявіть PR у Commerce OS: команда виправляє порядок підтвердження повернень, щоб заявки не потрапляли в обробку без потрібного рівня погодження. Це вже чутлива зона, тому що зачіпаються гроші, внутрішня рольова модель і журнал аудиту. Workflow Kit до цього моменту вже постачає QUALITY_GATES.md, RISK_CLASSIFICATION.md і налаштування permissions. Тобто технічний каркас у нас є. Залишилося ухвалити рішення.

У реальній команді блок gate найчастіше живе прямо в PR_DESCRIPTION.md. Не окремим священним документом на кожен рух мишею, а короткою секцією, яку reviewer і approver читають разом із diff та перевірками.

Наприклад, так:

## Гейт виробничого рішення

### Рівень ризику
high-risk

### Докази
CI green, refund regression tests passed, reviewer notes attached.

### Потрібні схвалення
Payments owner, support lead

### Шлях відкату
Revert PR, disable `refund_v2`, restore previous handler.

### Фінальне рішення
HOLD, доки не пройдуть staging smoke і ручний сценарій повернення коштів.

Подивіться, як тут працюють усі шари одночасно. Layer 1 уже дав diff review і reviewer notes. Layer 2 уже дав зелений CI та regression tests. Risk classification уже сказала, що зона high-risk. Permissions уже не дають мовчки прослизнути з міграцією або небезпечною командою. І лише після цього Layer 3 робить те, чого не може зробити жоден автоматичний інструмент: відповідає, чи готова команда взяти цю зміну в загальний контур.

Саме в цей момент production readiness перестає бути красивою фразою з корпоративної презентації й стає звичайною інженерною дією. Іноді це Merge approved. Іноді — HOLD. Іноді — прохання розділити PR на дві частини, тому що одна частина безпечна, а інша вже лізе в іншу risk-зону. Але в будь-якому з цих випадків рішення стає явним, читабельним і колективно зрозумілим. А це вже зовсім інший рівень зрілості, ніж просте «ну, у мене локально все пройшло». І тримається такий gate не на загальному відчутті, а на явному сліді зміни: що хотіли змінити, що реально змінили, чим це перевірили і хто сказав фінальне «так».