AI coding policy команды

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-действия через рискованные инструменты. Тут AI готовит plan, checklist, release notes — но не решает за команду.

Даже в совсем короткой policy это уже должно быть видно — например, в самом каркасе файла:

## Разрешено
Черновики docs, codebase exploration, PR notes, small local refactor with tests.

## Требуется ревью
Feature code, config changes, dependency upgrades, 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-generated code reviewится так же, как human-written code.
- Для multi-file changes используем 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 в каждой сессии видел базовые командные правила:

## Правила команды
Follow `docs/AI_CODING_POLICY.md`.
For multi-file changes: plan first, keep diff small, report tests run.

Именно такая связка обычно работает лучше всего. 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.
Причина: accidental external write during support sync.

Хорошая policy не пытается описать весь мир. Она делает вещь скромнее, но полезнее: снимает неопределённость. Когда всплывает «а можно ли так работать с AI?», ответ берут не из памяти, не из Slack-потока за прошлую пятницу и не из настроения тимлида, а из короткого общего документа. И это, честно говоря, один из самых дешёвых способов сэкономить команде много нервов.