AI Kit для 8 продуктовых команд: центральный плагин и продуктовые сервисы
Привет, Хабр. Меня зовут Роман, я внешний консультант по платформенной разработке. В одном из проектов меня позвали разобраться, что делать с AI-инструментами в продуктовой компании на восемь команд. У каждой свой микросервис, свой стек, свои нюансы. Есть общие конвенции, общий security baseline, общий подход к observability. И ровно ноль централизованного подхода к AI.
В январе 2026-го у клиента стало понятно: AI-инструменты разработки больше не эксперимент. Claude Code, Cursor, Copilot — кто во что горазд. У одного разработчика в ~/.claude/CLAUDE.md свой набор правил, у другого .cursorrules с другими. В одном репо команды лежал 400-строчный CLAUDE.md с дублирующимися общими конвенциями, в другом пустота. AI отвечал по-разному в одном и том же сервисе в зависимости от того, кто его спрашивал.
За полгода мы вместе с платформенной командой построили то, что внутри назвали AI Kit. Централизованный набор правил, skills, subagents и CI-инструментов для AI-ревью. Дальше: путь, грабли и цифры. И что я бы сделал иначе, если бы начинал заново.
Если у вас несколько продуктовых команд и AI-инструменты уже есть, но дисциплины их использования нет, статья для вас. Полезно тимлидам, CTO, инженерам платформенных команд и AI Champions.
За 6 месяцев получили: 8 команд на одном плагине, multi-agent CI-ревью с tiered моделями (около $0.05 за средний PR), acceptance rate AI-комментариев 47%, время review PR упало на 32%.
Главный урок: AI Kit — это продукт, а не документ. У него есть владелец, версионирование, метрики и пользователи.
Главный антипаттерн, который мы повторили четыре раза: пытаться сразу описать «все правила компании» в одном огромном CLAUDE.md. Не работает. Skills плюс иерархия Enterprise/Project/Personal — работает.
Что внутри: архитектура AI-агентов на пальцах, история проекта по месяцам, шаблоны CLAUDE.md, multi-agent ревью с ценами в $, J-curve adoption, метрики ROI без гадания на DORA, план внедрения на 90 дней.
Часть 1. Предистория
Мы провели внутренний аудит и обнаружили:
В 6 из 8 продуктовых репозиториев был CLAUDE.md или аналог. Все разные.
В 4 из них была фраза «используй best practices» (бесполезно).
В 2 устаревшие правила про библиотеки, которые выпилили полгода назад.
В одном правила про PHP 5 (давно на 8.4).
Никто не отвечал за обновление общих частей.
Разработчики копировали правила друг у друга, накапливая искажения как в детской игре «испорченный телефон».
Самый показательный момент случился в команде заказов. Новый разработчик пришёл, посмотрел на CLAUDE.md (350 строк), сказал «не буду это читать» и начал писать свой ~/.claude/CLAUDE.md с нуля. К концу первой недели у него был свой набор правил, который противоречил командному в 3 местах из 12.
Что я понял в этот момент
Это не индивидуальная проблема разработчика. Это системная проблема организации, которая раздала AI-инструменты, но не дала им структуры. И это происходит везде, не только у этого клиента.
Что говорят данные по индустрии
Пока готовили обоснование для CTO, перечитали свежие исследования.
По данным Panto AI 2026, 51% профессиональных разработчиков ежедневно используют AI-инструменты. State of AI Engineering 2026 показывает, что 80% команд преодолели порог 50% еженедельно активных пользователей AI.
За этими цифрами огромный разброс результатов. Coder в своём отчёте по enterprise-внедрениям пишет:
Many developers’ first introduction to AI in the enterprise was GitHub Copilot. Enterprises formed teams to procure and roll out AI assistants. The results? Underwhelming, given the investment. The customers and analysts I speak with will cite roughly a 10% productivity gain.
Анализ Faros по 22 000 разработчиков из 4000 команд (отчёт «The Acceleration Whiplash», апрель 2026) показывает картину тревожнее: у команд, внедривших AI без сопровождающих практик, метрики качества деградировали два года подряд.
Это пугало. Не хотелось оказаться в этой статистике. При этом другие компании показывают другие результаты:
Компания | Результат |
Anthropic | +67% PR throughput на инженера за год после внедрения Claude Code |
Stripe | 1370 инженеров; миграция 10 000 строк Scala в Java за 4 дня вместо оценочных 10 человеко-недель |
Wiz | Миграция 50 000-строчной Python-библиотеки на Go за 20 часов вместо 2–3 месяцев |
Ramp | Около 50% инженеров используют AI еженедельно, время расследования инцидентов упало на 80% |
Rakuten | Время доставки фичи: 24 рабочих дня → 5 |
Что общего у успешных кейсов? Все они вкладываются в платформенную работу вокруг AI: документация, кастомные команды, внутренние плагины, метрики, governance. Это и стало внутренним обоснованием для AI Kit.
Главный антипаттерн, который дошёл до меня только потом: гниение правил
Cloudflare в апрельском блог-посте 2026 про их систему AI-ревью на 5169 репозиториях формулирует ключевую проблему лучше нас:
AI coding agents rely heavily on AGENTS.md files to understand project conventions, but these files rot incredibly fast. If a team migrates from Jest to Vitest but forgets to update their instructions, the AI will stubbornly keep trying to write Jest tests.
Это именно то, что было видно у клиента. Команда мигрировала на новый ORM, AI продолжал писать на старом. Команда поменяла структуру проекта, AI продолжал предлагать старую. Никто не обновлял правила, потому что никто за них не отвечал.
У Cloudflare есть отдельный AI-агент materiality reviewer, который смотрит на PR и ругается, если разработчик меняет тест-фреймворк, но забыл обновить AI-инструкции. Эту идею мы своровали в чистом виде. Позже.
* * *
Часть 2. Краткий ликбез: как устроен современный AI-агент
Прежде чем рассказывать, что мы делали, объясню базовые понятия. Если вы давно работаете с Claude Code или Cursor, пропускайте часть. Если нет, она важна для понимания дальнейших решений.
Агентский цикл
В основе любого современного AI-coding-агента лежит agentic loop. Цикл «получить контекст, принять решение, вызвать инструмент, получить результат, повторить».
Agentic loop: gather context → take action → verify results, цикл повторяется до результата
Когда я это понял, многое встало на места. В академической работе «Dive into Claude Code» (arxiv 2604.14228) авторы дизассемблировали Claude Code v2.1.88 (около 1900 TypeScript файлов, около 512K строк кода) и обнаружили факт, который изменил подход к проектированию AI Kit:
Только 1.6% кода это AI decision logic, остальные 98.4% детерминированная инфраструктура: permission gates, context management, tool routing, recovery logic.
Главный инсайт
Производительность AI-инструментов определяется не моделью, а обвязкой вокруг неё. Качество AI-помощи в команде зависит не от выбора Claude vs Cursor, а от того, как организован контекст. Это и есть платформенная задача.
Контекстное окно как самый дефицитный ресурс
Это второй ключевой момент, который я понял не сразу. У любой модели контекстное окно конечное (200K токенов для Claude Sonnet, 1M для Gemini). Это самый дефицитный ресурс в работе с AI.
Согласно исследованию Imperial College (arxiv 2602.22402), типичная картина при использовании Claude Code:
После 30 минут работы накапливается около 132K токенов состояния (76% capacity).
Автокомпакция сжимает это до 2.3K токенов (12% capacity), сокращение на 98%.
Большая часть «понимания» проекта теряется.
Каждый байт CLAUDE.md, который попадает в каждую сессию, конкурирует за место с пониманием самого кода. Раздутый CLAUDE.md не просто бесполезен, он активно мешает: вытесняет важное.
Иерархия расширений по контекст-стоимости
Это знание получено самым болезненным путём: методом проб и ошибок. Anthropic-документация описывает четыре основных механизма расширения. Чем выше элемент, тем больше он стоит контекста.
Иерархия расширений по контекст-стоимости: CLAUDE.md, Skills, Subagents, MCP, Hooks
Когда мы это поняли, переписали половину AI Kit. Сдвинули максимум содержимого вниз, в skills и subagents. В CLAUDE.md оставили только то, что действительно нужно знать всегда. Это сократило размер CLAUDE.md в среднем в пять раз и улучшило качество ответов AI (по subjective feedback команд).
Subagents: главный архитектурный приём
Пожалуй, главная находка. По реверс-инжинирингу Claude Code v2.1.88 subagents работают так:
Главный агент вызывает Task инструмент с описанием задачи.
Запускается новый агент с собственным контекстным окном.
Subagent выполняет задачу, потенциально вызывая множество tool calls.
Возвращает только summary в главный контекст, не полную историю.
Subagents: главный агент делегирует security/style/architecture, каждый со своей моделью и стоимостью
Из этого следуют два важных свойства.
Изоляция контекста: subagent может прочитать 50 файлов в исследовательской задаче, а главный диалог получит только 2K-токенов summary.
Специализация: у каждого subagent своя роль, свой системный промпт, свой набор инструментов и даже своя модель. Дорогую Opus можно использовать для security-аудита, дешёвую Haiku — для проверки стиля. Об экономике подробнее в части про CI-ревью.
* * *
Часть 3. Концептуальная модель: что в итоге выстроили
Иерархия трёх уровней
Главное архитектурное решение AI Kit — иерархия из трёх уровней, которые никогда не смешиваются. Пришли к этому методом проб и ошибок. Та же модель в официальной документации Claude Code, OpenCode, Gemini CLI и других инструментах. Все сходятся на одной концепции.
Уровень | Где живёт | Кто владеет | Что туда кладём |
Enterprise / Org | Центральный плагин или managed settings | Platform team | Конвенции компании, security baseline, общие skills |
Project | Команда продукта | Архитектура этого сервиса, специфические нюансы | |
Personal | ~/.claude/CLAUDE.md или CLAUDE.local.md | Разработчик | Личные предпочтения, не коммитится |
Правило приоритета: более специфичный уровень переопределяет более общий. Если на enterprise написано «использовать Jest», на project — «использовать Vitest», в локальной сессии действует Vitest.
Грабли, на которые наступили
Первые два месяца личные предпочтения разработчиков складывали в project-уровень. Один старший инженер любит конкретный стиль комментариев. Это уехало в общий CLAUDE.md проекта. Через две недели вся команда страдала. Урок простой: личное в personal, проектное в project, корпоративное в enterprise. Не смешивайте.
Knowledge vs Workers
Самое полезное ментальное разделение взяли из статьи на Level Up Coding:
Plugins — упаковка Knowledge и Workers для распространения. То, что мы делаем через центральный acme-ai-kit плагин.
Skills vs CLAUDE.md: правило, к которому пришли
Самый частый вопрос от тимлидов: «положить инструкцию в CLAUDE.md или сделать skill?». После трёх итераций пришли к простому правилу.
Конкретный тест
Если в CLAUDE.md появилась секция длиннее 10 строк с пошаговой процедурой, выносите её в skill. Skills грузятся on-demand, CLAUDE.md грузится всегда.
Часть 4. Структура AI Kit
Концепция golden path
AI Kit построен по принципу golden path. Концепция из platform engineering, изначально введённая Spotify. Netflix это называет paved road. Смысл одинаков: команда платформы делает стандартный путь, и идти по нему проще, чем не идти.
Cloud Native Computing Foundation определяет golden path так:
Templated composition of well-integrated code and capabilities for rapid project development.
Свойства хорошего golden path по Google Cloud:
Optional. Команда может отказаться, но это будет дороже.
Transparent. Видно, что внутри.
Extensible. Команда может дополнить.
Customizable. Есть точки расширения.
Главный принцип AI Kit
AI Kit это golden path для работы с AI. Команда не обязана его использовать, но если использует, получает готовые правила, skills, ревью без дополнительной настройки.
Что я понял про опциональность
Сначала хотели сделать AI Kit обязательным для всех команд. Мол, теперь все так. Это не сработало. Команды формально подключали, но на практике игнорировали. После того как сделали его опциональным, но удобным, adoption вырос с 30% до 80%+. Люди не любят, когда им что-то навязывают, но любят, когда им что-то облегчает жизнь.
Структура центрального репозитория
Структура центрального репозитория acme-ai-kit
acme-ai-kit/ # центральный репо
├── .claude-plugin/
│ └── plugin.json # метаданные, версия (semver)
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── skills/ # общие навыки (Knowledge)
│ ├── code-review/
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── severity-levels.md
│ │ └── examples.md
│ ├── write-tests/SKILL.md
│ ├── audit-security/SKILL.md
│ ├── api-design/SKILL.md
│ └── observability/SKILL.md
├── agents/ # субагенты (Workers)
│ ├── security-reviewer.md # Opus
│ ├── style-checker.md # Haiku
│ ├── architecture-reviewer.md # Sonnet
│ └── materiality-reviewer.md # Haiku
├── commands/
│ ├── review-pr.md # /review-pr
│ └── new-microservice.md # /new-microservice
├── hooks/
│ └── hooks.json
├── mcp/
│ └── .mcp.json
├── templates/
│ ├── claude-md-template.md
│ ├── review-md-template.md
│ └── REVIEW.md # для AI-ревью PR
└── docs/
├── quickstart.md
└── governance.md
Структура репозитория сервиса
Каждая команда продукта в своём репо имеет минимум:
product-service-orders/
├── CLAUDE.md # короткий, 50-100 строк
├── REVIEW.md # (опционально) для PR-ревью
├── .claude/
│ ├── settings.json # { "plugins": ["acme-ai-kit@^2.0.0"] }
│ └── skills/ # project-specific skills
│ └── outbox-pattern/SKILL.md
├── docs/
│ ├── architecture.md
│ ├── event-schemas.md
│ └── adr/
└── internal/
├── domain/
└── usecase/
Ключевая идея
В CLAUDE.md сервиса нет дублирования общих правил. Они приходят из центрального плагина. В сервисе только специфика этого сервиса.
Распространение через marketplace
Использовали модель plugin marketplace. Создали репозиторий-маркетплейс с marketplace.json:
{
"name": "Acme Corp Internal Plugins",
"plugins": [
{
"name": "acme-ai-kit",
"version": "2.3.1",
"author": "Platform Team",
"repository": "https://github.com/acme/ai-kit"
}
]
}
Каждый разработчик в ~/.claude/settings.json:
{
"marketplaces": ["https://github.com/acme/ai-kit"],
"plugins": ["acme-ai-kit@^2.0.0"]
}
Похоже на npm или pip, интуитивно. Поддерживает semver. Обновления через claude plugin update. Команды могут пиниться:
acme-ai-kit@2.3.1: точная версия (для критичных команд).
acme-ai-kit@~2.3.0: patch updates only.
acme-ai-kit@^2.0.0: minor updates within major (рекомендую большинству).
* * *
Часть 5. CLAUDE.md / AGENTS.md: что туда пишем
CLAUDE.md (или AGENTS.md, они взаимозаменяемы; в проекте использовали AGENTS.md как универсальный, потому что его понимают и Claude Code, и OpenCode, и Cursor) попадает в контекст каждой сессии. Это и его сила, и его слабость.
Что туда пишем
По исследованию HumanLayer, CLAUDE.md должен покрывать три аспекта (структуру я у них своровал):
WHAT: стек, структура, что делает сервис.
WHY: какую проблему решает, где в архитектуре, кто пользователи.
HOW: команды для сборки, специфические конвенции, чего не делать.
Шаблон, который зашёл
Реальный (немного анонимизированный) CLAUDE.md из одного сервиса клиента:
# product-service-orders
Микросервис управления заказами в платёжной системе.
Owner team: payments-platform.
## Stack
- Go 1.22, Postgres 15, gRPC, Kafka, Redis
- Service mesh: Istio
- Observability: OpenTelemetry → Datadog
## Команды
- make test: все тесты
- make test-integration: интеграционные
- make lint: линтер
- make migrate: применить миграции
## Архитектура
- Чистая архитектура: domain/ → usecase/ → adapter/
- Бизнес-логика только в internal/domain/ и internal/usecase/
- HTTP/gRPC handlers тонкие, без логики
- Kafka events: outbox pattern (см. internal/outbox/)
## Чего НЕ делать
- Не править internal/generated/, генерится из proto
- Миграции только через make migrate
- Не использовать time.Now(), только через clock.Clock
## Дополнительный контекст
@docs/architecture.md
@docs/event-schemas.md
@docs/runbook.md
Обратите внимание: тут нет общих правил компании про логирование, security, git workflow. Они приходят из центрального плагина. Тут только специфика этого сервиса. Файл 35 строк.
Чего туда не пишем
Стиль кода: работа линтера. «Используй tabs», «именуй в camelCase», «не забывай ;». Всё это покрывает gofmt + golangci-lint в make lint. Никогда не отдавайте LLM работу, которую можно сделать детерминированным инструментом.
Очевидные вещи и языковые дефолты. «Используй best practices», «пиши чистый код», «используй async/await в JS». Модель и так это знает. Каждое такое правило крадёт место в контекстном окне на ровном месте.
Длинные code-сниппеты. Они быстро устаревают. Лучше pointer на документацию, которая поддерживается. Ссылайтесь на существующий код как образец: «стандартный паттерн handler см. internal/adapter/grpc/order.go».
Общие конвенции компании. Они должны быть в центральном плагине, не в каждом репозитории. Это и есть «писать рулсы по 100 раз».
Размер: 60 строк как золотой стандарт
Системный промпт Claude Code сам по себе содержит около 50 инструкций. По исследованиям LLM, instruction-following начинает деградировать после 150–200 инструкций. У вас остаётся около 100–150 «слотов» на свой проект.
Размер | Качество |
< 30 строк | Слишком мало, AI не понимает контекст |
30–100 строк | Sweet spot |
100–200 строк | Допустимо для сложных проектов |
200–500 строк | Признак, что нужны skills |
> 500 строк | Деградация attention |
Эмпирическое правило, которым пользуемся: «Would removing this line cause Claude to make mistakes?». Если ответ «нет», удаляем. Применяем правило при каждом quarterly review.
Грабли, которые поймали
Первая итерация шаблона CLAUDE.md была 250 строк. Туда вставили «всё хорошее»: naming conventions, git workflow, code style, examples. Через месяц один из тимлидов прислал PR с урезкой до 80 строк со словами «AI стал отвечать заметно лучше». Замерили. Действительно лучше. Меньше — это часто больше.
Часть 6. Skills: процедурное знание
Skills — относительно новый, но важный механизм. Процедурные инструкции, загружаемые on-demand на основе их description. Если CLAUDE.md описывает то, «что AI знает всегда», то skills описывают то, «что AI знает по запросу».
Структура skill
Минимальный skill это файл SKILL.md с YAML frontmatter:
---
name: code-review
description: |
Проводит ревью кода по конвенциям команды.
Активируется при запросе ревью, при работе с открытым PR,
или когда пользователь просит проверить код.
Использует references/severity-levels.md для классификации.
---
# Code Review
## Когда использовать
- Сделать ревью кода
- Проверить PR
- Найти проблемы в существующем коде
## Workflow
1. Прочитай контекст:
- Локальный CLAUDE.md сервиса
- references/severity-levels.md
- Если есть REVIEW.md в репозитории, приоритет ему
2. Проанализируй diff:
- Группируй находки по severity
- Для каждой конкретная ссылка на файл:строку
- Предлагай конкретный fix, не абстрактный
3. Что не комментируй:
- Стиль (его ловит линтер)
- Auto-generated файлы
Чёткий description критичен для активации
AI решает, нужен ли skill, на основе description. Если описание расплывчатое, skill не активируется когда нужен. Это самые большие грабли, на которые мы наступили со skills.
Плохо:
description: Помогает с тестами
Хорошо:
description: |
Пишет unit и integration тесты по конвенциям проекта.
Использует testify + table-driven для Go,
pytest fixtures для Python, vitest для TypeScript.
Активируется когда: пользователь просит написать тесты,
после имплементации новой функциональности,
при работе с _test.go или *.test.ts.
Что намерили
После того как переписали description у всех skills с подробным указанием когда активироваться, частота автоматической активации skills выросла с 15% до 62% от случаев, когда они должны были активироваться. Это была разница между «skills есть, но никто не пользуется» и «skills работают как часы».
Распределение skills по уровням
Уровень | Что туда |
Enterprise (плагин) | Общие skills: code-review, write-tests, audit-security, api-design, observability, error-handling |
Project (.claude/skills/) | Специфичные для сервиса: outbox-pattern, event-sourcing-orders, domain-validation |
Personal (~/.claude/skills/) | Личные shortcuts разработчика |
* * *
Часть 7. Multi-agent CI-ревью: production-пайплайн
Часть, которой я доволен больше всего. Multi-agent ревью стандарт de facto в зрелых командах в 2026. По данным Cloudflare и независимого блога про multi-agent code review, победившая архитектура выглядит так.
Multi-agent CI-ревью: materiality first, потом параллельные style/logic/security и aggregator
Зачем multi-agent (история провала с single-agent)
Сначала сделали один agent, который ревьюит всё. Казалось простым и достаточным. Через две недели в Slack в канале команды заказов появилось сообщение от senior-разработчика:
Я отключил AI-ревью в нашем репо. Он каждый PR пишет «consider edge cases» и «add error handling without specifics». Бесполезный шум.
Классическая проблема, которую формулирует независимый анализ multi-agent code review:
Single-agent AI models often produce generic, low-value feedback when tasked with broad code review objectives. By decoupling style, logic, and security into specialized agents, teams can prevent production bugs like race conditions and auth bypasses.
Когда переехали на multi-agent с разделением ролей и tiered-моделями, картина изменилась радикально.
Tiered-модели экономят бюджет
Модель | Применение | Цена ревью |
Haiku | Style checker, materiality assessor | ~$0.002 |
Sonnet | Logic, architecture | ~$0.05 |
Opus | Security (только для важных PR) | ~$0.50 |
В сумме 80% PR обрабатываются дёшево, дорогие модели включаются только когда нужно. Средний месячный билл за AI-ревью на 8 продуктов — около $180. Меньше, чем дневная зарплата одного джуна.
Materiality reviewer: защита от rule rot
Решение мы скопировали у Cloudflare. Идея простая: отдельный AI-агент смотрит на каждый PR в первую очередь и определяет, нужно ли обновлять AI-инструкции:
Уровень материальности | Примеры | Действие |
High | Смена тест-фреймворка, билд-инструмента, реструктуризация директорий, новые env vars | Требовать обновления |
Medium | Major dependency bumps, новые linting rules, изменения API клиента | Предложить обновление |
Low | Bug fixes, новые фичи в существующих паттернах, CSS изменения | Не нужно |
Materiality reviewer работает на Haiku (дёшево) и запускается на каждом PR в первую очередь. Если детектирует high, пишет в PR description предупреждение и блокирует merge до обновления AI-инструкций. Главное лекарство против гниения правил.
Структура GitHub Actions пайплайна
Реальный workflow (упрощённо):
# .github/workflows/ai-review.ymlname: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
materiality-check:
runs-on: ubuntu-latest
outputs:
level: ${{ steps.assess.outputs.level }}
needs_security: ${{ steps.assess.outputs.needs_security }}
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- id: assess
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: node scripts/materiality-assessor.js
style-review:
needs: materiality-check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: node scripts/run-agent.js --agent style --model haiku
logic-review:
needs: materiality-check
if: needs.materiality-check.outputs.level != 'low'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: node scripts/run-agent.js --agent logic --model sonnet
security-review:
needs: materiality-check
if: needs.materiality-check.outputs.needs_security == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: node scripts/run-agent.js --agent security --model opus
aggregate:
needs: [style-review, logic-review, security-review]
if: always()
runs-on: ubuntu-latest
steps:
- run: node scripts/aggregate-and-post.js
Ключевые архитектурные решения:
Materiality first. Маленькие cosmetic PR не запускают дорогие агенты.
Параллелизм. Style, logic, security работают одновременно.
Continue-on-error. Если security agent failed (rate limit), pipeline не валится.
Aggregation. Дедупликация и форматирование в едином месте.
REVIEW.md: настройка под репозиторий
Каждый сервис может иметь свой REVIEW.md, который инжектится с высшим приоритетом в системный промпт ревью-агентов. Это позволяет команде кастомизировать ревью под свою специфику без изменения центрального AI Kit:
# Review Guidelines for product-service-orders
## Severity calibration
### Critical (блокирует merge)
- Любая работа с PaymentToken, обязательно security review
- Изменения в internal/domain/order/ без обновления тестов
- Breaking changes в gRPC API без версионирования
### Important (требует фикса перед merge)
- Запросы в hot path без индексов
- Missing context propagation
- Любые panic() вне init()
### Skip (не комментируй)
- Стиль (его ловит golangci-lint)
- Изменения в internal/generated/
## Don't comment about (negative examples)
Don't suggest renaming variables (handled by linter)
Don't comment on missing JSDoc (we use Go, not JS)
Don't suggest "consider adding error handling" without specifics
Сила negative examples
По нашим замерам, после добавления секции «Don’t comment about» в REVIEW.md шум в инлайн-комментариях упал на 40%. Negative examples — недооценённый приём.
Метрики качества AI-ревью
Главная метрика, которую трекаем: acceptance rate inline-комментариев.
Acceptance rate | Что значит |
< 30% | AI генерит шум, нужно пересматривать промпты и REVIEW.md |
30–70% | Нормальный рабочий диапазон |
> 70% | Подозрительно высоко, разработчики могут принимать некритично |
Сейчас 47% acceptance rate в среднем по 8 командам. Считаю хорошим результатом. Стартовали с 22% (шум). Дошли до текущих цифр через 4 месяца итераций над промптами и REVIEW.md.
Часть 8. Метрики и ROI: почему DORA недостаточно
J-curve adoption: будьте готовы к падению
DORA в апрельском отчёте 2026 «ROI of AI-Assisted Software Development» ввела важное понятие: J-curve adoption. Это первое, что нужно показывать руководству перед внедрением AI Kit.
J-curve adoption AI Kit: провал в первые 6 месяцев и восстановление на 10–15 месяцев
Фазы:
Старт. Лёгкий рост от первых очевидных use cases.
Падение (3–6 месяцев). Команда учится промптить, накапливаются проблемы.
Восстановление. Команда осваивает паттерны, AI Kit стабилизируется.
Steady state (10–15 месяцев). Устойчивая позитивная динамика.
Что это значит
Бюджетируйте «tuition cost» как инвестицию. По расчётам DORA, типичный first-year ROI может быть отрицательным даже у успешных внедрений. Не показывайте руководству только метрики «AI пишет код быстрее». Этого недостаточно.
Faros в отчёте «The Acceleration Whiplash»:
80% of teams already past 50% AI adoption, and quality metrics have been degrading across the full two-year window.
Многие команды находятся в J-curve, но не понимают этого. Списывают проблемы на «AI плохой», хотя они в инвестиционной фазе.
Почему DORA недостаточно
Самое важное прозрение 2026 года. GetDX в анализе DORA для AI-команд:
DORA metrics inflate under AI assistance deployment frequency and lead time improve on paper while hiding increased review overhead and new categories of defects.
Конкретные искажения, которые мы видели у клиента.
Deployment frequency растёт искусственно. AI генерит больше boilerplate, маленькие коммиты, deployment frequency растёт. Но это не значит ценность для пользователя.
Lead time падает обманчиво. PR создаётся за секунды, но review-overhead растёт быстрее. Идея до working feature не обязательно ускоряется.
Change failure rate скрывает новые виды поломок. AI вносит тонкие баги, которые проходят CI, но падают в проде через неделю.
DX Core 4 framework
Современный подход: DX Core 4 framework, который GetDX формулирует как 4 измерения. Перешли на него после первых двух месяцев:
Измерение | Метрики |
SPEED | DORA delivery + Perceived productivity |
EFFECTIVENESS | Developer Experience Index, Focus time, Interrupt frequency |
QUALITY | CFR (split AI vs human), Tech debt, Rework rate |
IMPACT | Revenue per dev, Customer satisfaction, Time-to-value |
AI-specific метрики, которые трекаем
Метрика | Хорошо | Плохо |
AI suggestion acceptance rate | 30–70% | < 30% или > 70% |
AI vs human PR. Bug rate | Сравнимо или ниже | Выше у AI |
AI Kit version coverage | > 80% репо актуальны | Расхождения |
Mean PR review time | Падает | Растёт |
Developer satisfaction (CSAT) | > 7/10 | < 5/10 |
Active skills usage | > 80% | Dead skills |
Materiality alerts rate | < 5% PR | > 15% (rule rot) |
Что не надо измерять
Olakai в анализе AI ROI tools:
‘Acceptance rate’ is a product metric, not a business metric. A 30% acceptance rate tells you developers kept 30% of suggestions. It says nothing about whether those suggestions shipped faster, reduced bugs, or moved a revenue number.
Антиметрики, которые мы не используем как KPI:
Lines of AI-generated code. Стимулирует объём, не качество.
Individual developer scoring. Токсично, искажает поведение.
Prompts per day. Не значит ничего.
Tokens consumed. Не корреллирует с ценностью.
Результаты после 6 месяцев
Что получили:
Метрика | До AI Kit | После 6 месяцев |
AI suggestion acceptance rate | 22% | 47% |
Mean PR review time | — | −32% |
AI Kit adoption | — | 82% |
Developer CSAT по AI | 5.1/10 | 7.4/10 |
AI-tagged PR bug rate | — | Сравним с human |
Materiality alerts rate | — | 3.2% |
Честно про ROI
Финансовый ROI на 6-м месяце ещё не очевиден. По расчётам DORA это нормально, мы в J-curve. Главное: метрики качества не деградировали, в отличие от тех 80% команд из исследования Faros. В этом и есть ценность guardrails.
Заключение
10 принципов, которые остались после 6 месяцев работы:
AI Kit это продукт, а не документ. У него есть пользователи, владелец, changelog, метрики, governance. Относитесь к нему как к внутреннему продукту.
Архитектура AI-агентов сложнее, чем кажется. Контекстное окно дефицитный ресурс. Skills, subagents, MCP это инструменты управления контекстом.
Иерархия трёх уровней (Enterprise, Project, Personal) фундамент. Не смешивайте уровни. Большинство проблем «каши» возникают именно из-за смешивания.
Skills лучше длинного CLAUDE.md. Грузите процедурное знание on-demand.
Multi-agent ревью это не будущее, а настоящее. Single-agent дают generic-фидбек.
Rule rot это главный враг. Без активного процесса обновления правила гниют за 3–6 месяцев.
AI без guardrails это ускоритель технического долга.
Готовьтесь к J-curve. Первые 6 месяцев это обучение и инвестиции.
Измеряйте больше, чем DORA. DX Core 4 framework плюс сегментация PR по AI involvement.
Начинайте маленьким. Один skill, одна команда, один пилот.
Через год правильно построенного AI Kit у клиента команда, в которой:
Новые сотрудники продуктивны на третий день. Открывают AI и сразу получают контекст компании.
Стандарты компании реально применяются, а не пылятся в wiki.
Ревью проходят быстрее и ловят больше багов.
Каждая команда фокусируется на продуктовой специфике, а не переизобретает велосипед.
Команда перестала бояться, что окажется в статистике Faros по деградации качества.
Та же дисциплина, что для CI/CD, Internal Developer Platform, Service Catalog. AI Kit это следующий слой platform engineering. Та же логика, новые инструменты.
Поделитесь в комментариях своим опытом. Внедряли ли вы централизованный AI Kit в команде? С какими граблями столкнулись? Что бы добавили из своего опыта? Особенно интересен опыт компаний разного размера и стека.
