Risk-класифікація і capability envelope

1. Класифікація ризику відбувається раніше за перший prompt

У багатьох розробників ланцюжок до цього моменту виглядав приблизно так: побачили issue, відкрили Claude, сформулювали задачу — а про ризик подумали вже по ходу. На pet-проєкті це ще можна пережити; у Commerce OS це вже імпровізація з елементами цирку.

Класифікація ризику потрібна не заради бюрократії і не заради гарної таблички в Notion. Вона відповідає на дуже приземлене запитання: яким буде blast radius помилки, якщо Claude зробить зайве. Правка README.md і правка production-конфіга платежів — це зовсім різні наслідки, а Claude при цьому старанний однаково. Проблема не в старанності, а в тому, що старанний асистент із доступом не туди — це вже маленький виробничий інцидент.

Раніше на safety було легко дивитися з хвоста процесу: tests, review, quality gates, merge. Із production питання зміщується лівіше: спочатку — що Claude взагалі можна доручити, потім закріпити межі в репозиторії, не тягнути в сесію зайві дані, ризиковані кроки запускати в дешевому середовищі, і лише потім підходити до релізу.

Корисно одразу розвести чотири сутності, які легко переплутати:

Risk classification з’являється до prompt і до execution. Це не quality gate перед merge: gate питає «чи можна пропускати результат далі?», а класифікація — «який режим роботи взагалі допустимий із самого початку?».

Наочно це виглядає так:

flowchart TD
    A["Нова задача"] --> B["Класифікація ризику"]
    B --> C["Capability envelope"]
    C --> D["Task spec / prompt"]
    D --> E["Робота Claude"]
    E --> F["Checks / review / gate"]

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

2. Shortcut: low-risk, review-required, high-risk

Гарна новина: у щоденній роботі вам не потрібен комітет із філософії ризиків. Для більшості задач вистачає дуже грубого, але корисного shortcut, який можна прогнати буквально за п’ять секунд. Його мета не в академічній точності. Його мета — вчасно зупинити занадто бадьорий старт.

Ось базова схема:

На перший погляд правило грубе. І так, спеціально: воно розраховане на того, хто вирішує швидко по задачі з backlog, а не на техліда, який пише політику на квартал уперед. Якщо вам, щоб класифікувати задачу, потрібно пів години сперечатися, low-risk це чи review-required, значить shortcut уже спрацював: показав, що задача не така вже й очевидна.

Дуже важливо зрозуміти останній рядок: якщо не впевнені, за замовчуванням — review-required, не low-risk. Це правило потрібне не тому, що світ злий, а тому, що невизначеність сама по собі підвищує ризик. Коли ви їдете в тумані, нормальний водій не тисне на газ зі словами «так, мабуть, там пряма».

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

3. Однієї мітки замало — потрібен capability envelope

Одна мітка review-required корисна приблизно як наліпка «обережно» на дверях: вона каже, що всередині серйозне, але що саме робити, чого не робити і де вогнегасник — не сказано. Тому після risk label потрібна наступна річ — capability envelope, тобто контур дозволених можливостей для цієї конкретної задачі. Найзручніший формат тут — короткий шаблон, який підходить і для RISK_CLASSIFICATION.md, і для PR description, і для handoff note:

## Capability envelope

Рівень ризику: review-required
Дозволені інструменти: Read, Edit у `support/**`, run tests
Потрібні схвалення: human PR review
Потрібні перевірки: unit tests, integration tests, lint
Заборонені дії: edits у `payments/**`, `migrations/**`, `.env*`
Очікуваний відкат: revert PR, regression test залишається

Шість полів, кожне — за своє:

Зверніть увагу на корисну деталь: capability envelope не підміняє task spec. Task spec скаже: «виправити сортування refund-запитів». Envelope скаже: «редагувати лише support-частину, у payments не лізти, після змін — такі-то перевірки». Тобто одна сутність відповідає за сенс задачі, а інша — за межі поведінки.

І ще один практичний момент щодо міри: low-risk задачам не потрібен роман у десяти главах, для них envelope може бути дуже коротким. High-risk задачі, навпаки, майже завжди вимагають явної заборони на виконання і режиму plan-only. Не треба однаково докладно оформлювати все підряд, інакше люди перестануть читати документ уже на третьому README fix.

4. Shortcut на задачах Commerce OS

Щоб не жити в абстракції, давайте прогонимо shortcut на знайомих задачах із Commerce OS. На папері майже все виглядає очевидно, але в реальному backlog раптом з’ясовується, що «маленька правка» і «безпечна правка» — далеко не синоніми.

Ось кілька типових прикладів:

Найкорисніше дивитися на прикордонні випадки. Припустімо, у вас задача: «трохи поправити конфіг feature flag». Новачок легко скаже: «це ж просто конфіг, майже як текстовий файл». А на практиці конфіг може вимкнути половину checkout-потоку, змінити доступи або зламати сумісність. Тому в цьому shortcut зміни конфігів за замовчуванням ідуть у review-required. Не тому, що всі конфіги однаково страшні, а тому, що shortcut захищає від занадто раннього оптимізму.

Тепер приклад із support-потоку. Виправлення сортування refund-запитів — це review-required. Тут не потрібно оголошувати надзвичайний стан, але й не можна писати prompt у стилі «Claude, швидко поправ і заодно почисть усе навколо». Правильний режим — обмежити область support/**, заборонити payments/**, вимагати regression test і diff review. Жодної драми, просто дисципліна.

А ось rotation production key — уже зовсім інша розмова. Тут Claude корисний як підготовник матеріалів: plan, checklist, rollback window, список залежних сервісів. Але не як виконавець. І це важлива зміна інтонації. У low-risk ви можете просити «онови». У review-required — «спочатку досліди й запропонуй план». У high-risk — «нічого не виконуй, лише підготуй матеріали». Одна лише зміна дієслова сильно зменшує шанс випадково зробити зайве.

5. RISK_CLASSIFICATION.md у Workflow Kit

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

Добрий RISK_CLASSIFICATION.md має бути коротким, жорстким до невизначеності й читатися за хвилину. Наприклад, так:

# RISK_CLASSIFICATION.md

## Швидка класифікація
- production / DB / secrets / спільна інфраструктура / масове видалення -> high-risk
- code / config / dependencies / API contracts -> review-required
- docs / README / small local refactor with tests -> low-risk
- якщо не впевнені -> review-required

## Шаблон capability envelope
Рівень ризику:
Дозволені інструменти:
Потрібні схвалення:
Потрібні перевірки:
Заборонені дії:
Очікуваний відкат:

Так, вона коротка — і саме тому її реально читатимуть. А якщо перетворити цей файл на корпоративний роман із тридцятьма винятками, студенти, розробники і навіть сам Claude почнуть сприймати документ як інтерʼєр, а не як інструмент.

Зазвичай далі команда робить дві корисні речі. По-перше, посилається на цей файл із CLAUDE.md, щоб у Claude був той самий словник, що й у людей. По-друге, вставляє capability envelope у PR description для review-required і high-risk задач — тоді ревʼюер бачить не просто diff, а одразу контекст: який ризик, що дозволено, що заборонено, які перевірки обов’язкові:

## Capability envelope
Рівень ризику: review-required
Дозволені інструменти: Read, Edit у `support/**`, run tests
Потрібні перевірки: unit + integration tests
Заборонені дії: `payments/**`, `migrations/**`, `.env*`
Очікуваний відкат: revert PR

Зверніть увагу, як швидко такий блок охолоджує хаос. Розмова в ревʼю перестає звучати як «я наче поправив, подивіться» — і починає звучати як «ось у яких межах велася задача і чому diff виглядає саме так». Для production-команди це дуже доросла різниця.

6. Постановка задачі після класифікації

Найпрактичніший наслідок сьогоднішньої теми видно не в документах, а в тому, як ви формулюєте задачу для Claude: один і той самий issue за різної класифікації отримує різні стартові дієслова, різний обсяг роботи і різний рівень свободи. І, чесно кажучи, це одна з найкорисніших звичок усього модуля.

Для low-risk задач формулювання може звучати майже прямолінійно:

Онови `README.md`: команда запуску змінилася на `./gradlew bootRun`.
Зачепи лише документацію.
Покажи підсумковий diff.

Жодної драми — швидка зрозуміла правка без зайвого процесу.

Для review-required тон змінюється:

Задача review-required: виправити сортування refund-запитів у support inbox.
Спочатку досліди affected files і запропонуй короткий план.
Не змінюй `payments/**`, `migrations/**` і `.env*`.
Після плану дочекайся підтвердження.

Зверніть увагу, як з’являється фраза «спочатку досліди й запропонуй план». Це і є застосування класифікації на практиці — не якийсь далекий policy-файл, а конкретна робоча інтонація.

Для high-risk тон змінюється сильніше:

Задача high-risk: підготувати план для rotation production Stripe key.
Нічого не виконуй і не редагуй.
Підготуй checklist, rollback notes, список залежностей і ризиків.

Тут Claude перетворюється з виконавця на аналітика й редактора артефактів. І це абсолютно нормально: іноді найкращий спосіб використати AI — не дати йому зробити дію, а дати добре підготувати людину до цієї дії.

Із цієї ж логіки виростає ще одна корисна звичка. Якщо під час роботи ви раптом розумієте, що low-risk задача зачіпає API-контракт або вимагає походу до продової бази, ви не «дотискаєте» старий prompt, а перекласифіковуєте задачу: змінюєте capability envelope і лише потім продовжуєте. Це здається дрібницею, але саме в таких дрібницях workflow перестає бути красивою схемою на слайді і стає страховкою від самовпевненої дурості.

Але capability envelope живе на рівні конкретної задачі. Якщо заборона на payments/** або .env* є лише в одному task spec, вона занадто крихка: наступна задача буде сформульована інакше, і межа розчиниться. Тому envelope для задачі потрібен разом із загальним baseline репозиторію, де чутливі зони закріплені не як побажання в prompt, а як загальна policy.

Коли команда звикає до цієї мови, перше запитання по новій задачі за участю AI звучить уже не «який тут prompt написати?», а «який тут ризик?». І ось із цього моменту у вас з’являється не просто Claude в проєкті, а керована система роботи з ним.