Політика AI-кодування команди

1. Команді потрібен AI_CODING_POLICY.md

Коли команда вперше починає активно використовувати Claude Code, здається, що все можна вирішити здоровим глуздом. Але в здорового глузду є одна неприємна особливість: у кожної людини він трохи свій. Для одних «безпечно» — накидати через AI чорновик README, для інших — дати йому автоматично лізти в гілку з платіжною логікою. Усе тримається на усних домовленостях, а потім зʼясовується, що ніхто не знає, де закінчується «можна» і починається «лише через review».

Тому AI_CODING_POLICY.md потрібен не з любові до документів. Це engineering agreement — коротка домовленість про те, як саме ви використовуєте AI в розробці. Не юридичний трактат і не маніфест про світле майбутнє, а набір дорожніх знаків. Їх не роблять романом на 300 сторінок: водій прочитає заголовок, зітхне й поїде зустрічною смугою з принципу.

У контексті нашого курсу це особливо добре видно на звʼязці Commerce OS і Workflow Kit: продукт живе в Commerce OS, правила й артефакти команди — у Workflow Kit. Тому AI_CODING_POLICY.md логічно тримати поруч з іншими shared assets:

# AI_CODING_POLICY.md

Мета: використовувати Claude Code швидко, але безпечно.
Сфера дії: Commerce OS і Workflow Kit.
Власник: команда backend/platform.

Цього вже достатньо, щоб документ перестав бути «якоюсь нотаткою» і став явним командним артефактом. Далі ви наповнюєте його правилами, але мета залишається тією ж: прибрати двозначність. Коли спливає «а так узагалі можна?», відповідь живе не в голові найупевненішого розробника, а в короткому документі, який бачать усі.

2. Policy проти сусідніх артефактів

На цьому місці студенти часто плутаються, і це нормально: документів кілька, назви серйозні, а відчуття — ніби команда колекціонує markdown-файли. Розведіть їх за ролями, і плутанина зникає. У кожного документа своє запитання.

Policy не повинна повторювати вміст сусідніх файлів. Інакше одна й та сама заборона на production deploy житиме в чотирьох місцях, і команда почне сперечатися, яка версія «головніша».

Цю різницю зручно показати і схематично:

flowchart TD
    P["AI_CODING_POLICY.md"] -. задає загальні правила .-> R["RISK_CLASSIFICATION.md"]
    P -. задає загальні правила .-> Q["QUALITY_GATES.md"]
    P -. задає загальні правила .-> D["Production Decision Gate"]

    R --> Q --> D

Хороша policy не відповідає на запитання «які саме тести запускаємо для цієї фічі» — для цього є quality gates і план перевірки. Вона відповідає на рівень вище: «що взагалі дозволено робити з AI без погодження, а що ні». Не виділіть цей шар окремо — інші артефакти працюватимуть нерівно.

3. Три запитання, на які policy зобовʼязана відповідати

Якщо ви хочете написати коротку й справді робочу policy, не починайте з великих розділів — почніть із трьох запитань. Звучать вони майже по-дитячому просто, але саме на них спираються всі інші правила. Що дозволено? Що дозволено лише через review? Що заборонено без явного human approval?

У зоні, де можна працювати без зайвої драми, зазвичай опиняються дослідження кодової бази, пояснення наявного коду, чорновики документації, підготовка PR_DESCRIPTION.md, невеликі локальні рефакторинги з тестами або чорновики тестів. AI прискорює роботу, ризик низький.

Review-required — це вже код, конфіги, залежності, write-capable MCP, shared hooks, правки в чутливих зонах, зміни публічного API, оновлення shared assets. Робити можна, але не в режимі «Claude сказав — я повірив»: потрібен інженерний цикл plan, diff, перевірки, review, traceability.

А от без явного human approval не повинно відбуватися нічого, що дорого коштує команді: production deploy, destructive DB operations, force push, direct push у protected branches, правки IAM, secrets, shared infra, зовнішні write-дiї через ризикові інструменти. Тут AI готує plan, checklist, release notes — але не вирішує за команду.

Навіть у зовсім короткій policy це вже має бути видно — наприклад, у самому каркасі файлу:

## Дозволено
Чернетки docs, дослідження codebase, нотатки до PR, невеликий локальний рефакторинг із тестами.

## Потрібно рев'ю
Feature code, зміни конфігів, оновлення залежностей, shared skills/plugins/hooks.

## Заборонено без явного схвалення людини
Production deploy, destructive DB ops, force push, secrets and infra changes.

Зверніть увагу: тут немає кілометрів прикладів, і це добре. Policy має читатися перед першою кавою, а не після звільнення.

4. Розділи policy, яку справді читають

Зазвичай документ починає «пухнути» не тому, що команда любить писати багато, а тому, що намагається запхати в одне місце все одразу. Обмежте склад наперед: приблизно десяти тем вистачає майже будь-якій engineering-команді на Claude Code — закрити хаос і не перетворити файл на енциклопедію.

Тут особливо важливо не переплутати policy із сусідніми артефактами. Policy може сказати: «для multi-file changes використовуємо plan-first workflow», але перелічувати всі команди та кроки перевірки вона не зобовʼязана — це живе в CLAUDE.md, QUALITY_GATES.md, REVIEW_CHECKLIST.md та інших артефактах Workflow Kit.

Ще одна корисна евристика: якщо розділ потребує більше одного-двох коротких абзаців, деталі вже час виносити. Чутливі зони коротко позначте в policy, докладні правила блокування шляхів залиште settings.json, hooks або project rules. Інакше policy перетворюється на шафу, куди складають усе підряд. А шафи, як ви знаєте, хороші для зимових курток, але не для чітких інженерних рішень.

5. Фрагменти AI_CODING_POLICY.md для Commerce OS

Тепер зберемо policy не в теорії, а у вигляді реального фрагмента для нашого курсу. Уявіть, що файл лежить у workflow-kit/docs/AI_CODING_POLICY.md і стосується роботи над Commerce OS. Ідеал з першого разу не потрібен — важливіші вдалий розмір, тон і чіткі формулювання.

Ось хороший стартовий фрагмент базових правил:

## Базові правила

- Код, згенерований AI, перевіряється так само, як і код, написаний людиною.
- Для змін у кількох файлах використовуємо plan-first workflow.
- Secrets і реальні customer data не потрапляють у prompts.
- Перед merge обов'язкові small diff і test evidence.
- Остаточне рішення щодо merge ухвалює людина.

Тут кожен рядок робить одну річ і знімає міф «запропонував AI — значить, майже готово». Ownership залишається у розробника і команди.

Тепер фрагмент про те, що не можна робити без явного approval:

## Заборонено без explicit approval

- production deploy і destructive DB operations;
- force push і direct push у protected branches;
- правки IAM, secrets і shared infra;
- зовнішні write-actions через risky MCP tools.

Такі рядки мають бути максимально конкретними. «Будьте обережні з продакшеном» звучить виховано, а працює ніяк. А ось «production deploy заборонений без explicit approval» — уже робоче правило: його можна перевірити, йому можна навчити новачка, покласти поруч із enforcement.

Окремий шматок policy зазвичай варто звʼязати з PR-описом: через policy або PR template команда робить звичний блок AI-assisted workflow notes обовʼязковою частиною PR_DESCRIPTION.md — де допоміг AI, де людина підтвердила план і фінальні перевірки, чи не затягнули в нотатки чутливі дані. Ви не публікуєте transcript на пів екрана, але й не робите вигляд, що AI не брав участі. На code review reviewer одразу бачить, де AI-внесок, а де human decisions.

6. Policy без enforcement — це прохання

На цьому місці хочеться сказати: «Ну все, документ написано, тепер команда захищена». На жаль, ні. Policy без enforcement — як табличка «по газону не ходити» посеред стежки, яку витоптали сто людей. Гарна, морально підтримує, а трава не відростає.

В інженерній практиці policy має спиратися хоча б на мінімальні технічні обмеження — знайомі вам з курсу session permissions, team-level settings, hooks, protected paths і branch protection. Саме вони перетворюють правило із побажання на справді працюючу межу. Політика каже: «force push не можна». Enforcement робить так, щоб це було незручно, помітно або просто заборонено.

Схематично це можна показати так: policy — правила дорожнього руху, а permissions і hooks — шлагбауми, лежачі поліцейські та камери. Повну копію policy в settings.json тягнути не треба, але найкритичніші заборони дублювати туди корисно. Приклад умовний, бо точний синтаксис залежить від поточної версії Claude Code:

{
  "permissions": {
    "deny": ["Bash(git push --force*)", "Edit(.env*)"],
    "ask": ["Bash(npm publish*)", "Edit(payments/**)"]
  }
}

Цього вже достатньо, щоб policy не висіла у вакуумі. Аналогічно посилайтеся на неї з CLAUDE.md, щоб Claude у кожній сесії бачив базові командні правила:

## Правила команди
Дотримуйтеся `docs/AI_CODING_POLICY.md`.
Для змін у кількох файлах: спочатку план, тримайте diff маленьким, звітуйте про запущені тести.

Саме така звʼязка зазвичай працює найкраще. Policy відповідає на запитання «що ми вважаємо нормою», enforcement — «як ми не даємо цій нормі непомітно розвалитися».

7. Policy має бути живою, але не розпухлою

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

Здоровий підхід простіший: оновлюйте policy, коли повторюється патерн, а не поодинокий випадок. Reviewer skill дав хибне спрацювання — правити треба сам SKILL.md, а не policy. А от утретє ловите розробників за встановленням write-capable MCP без схвалення — це кандидат на правило policy.

Корисно тримати в голові таку маленьку матрицю:

Якщо правило справді командне, його варто зафіксувати через PR і короткий запис у changelog:

## 2026-05-14
Додали правило: write-capable MCP tools за замовчуванням read-only.
Причина: випадковий зовнішній запис під час синхронізації підтримки.

Хороша policy не намагається описати весь світ. Вона робить річ скромнішу, але кориснішу: знімає невизначеність. Коли спливає «а чи можна так працювати з AI?», відповідь беруть не з памʼяті, не зі Slack-потоку за минулу пʼятницю і не з настрою тимліда, а з короткого спільного документа. І це, чесно кажучи, один із найдешевших способів зекономити команді багато нервів.