# Протокол AI-разработки — v2.1 ## Главный принцип ИИ помогает писать код, анализировать и искать ошибки, но **ответственность за решения остаётся у разработчика**. Компания не требует разработки без ошибок. Она требует, чтобы перед выпуском изменения были нормально описаны, проверены, а найденные риски — осознанно разобраны. Если протокол выполнен полностью и честно, а ошибка всё равно попала в бой — это риск компании. --- ## Словарь (читать первым) - **Репозиторий** — хранилище кода проекта с историей всех изменений (на своём сервере — Gitea/GitLab, или облако — GitHub). - **main** — боевая (рабочая) версия проекта. - **Ветка** — рабочая копия: изменения делаются в ней, main не трогается. - **Заявка (PR, Pull Request)** — «прошу влить мои изменения в main»: страница с изменениями и приложенными документами. - **Merge** — вливание изменений из ветки в main после всех проверок. - **Робот (CI)** — автоматика, которая сама проверяет каждую заявку: гоняет тесты, сверяет комплект документов. Это шлагбаум: комплект неполный — merge заблокирован. - **Спека** — подробное ТЗ: цель, сценарии, ограничения, пограничные случаи, критерии «готово». - **AI-ревью** — проверка кода отдельным ИИ, который этот код не писал. - **Агенты-ломатели** — ИИ-агенты, чья задача сломать и опровергнуть решение, а не похвалить. - **Сквозной тест** — автоматическая проверка сценария целиком: «водитель заполнил форму → сделка в Bitrix → начислена выплата». - **Critical / major / minor** — тяжесть проблемы: критичная / серьёзная / мелкая. - **PASS / NEEDS_ACTION** — итог ревью: «чисто» / «есть подтверждённые проблемы, нужен разбор». - **Старшая модель** — самая мощная доступная версия ИИ (какая сейчас — указано в репо скилов). - **Лог сессии** — полная запись переписки разработчика с ИИ. - **Откат / пост-мортем** — возврат прошлой версии / письменный разбор причин сбоя. --- ## Роли - **Разработчик** — выполняет шаги, прикладывает документы, принимает решения по найденным проблемам. - **Робот (CI)** — проверяет каждую заявку, блокирует merge при неполном комплекте. Классы S и M пропускает сам. - **Владелец** — вручную ничего не одобряет. Получает резюме по классу L (право вето 24 часа), раз в месяц участвует в аудите, разбирает инциденты. --- # 1. Сначала определяем класс изменения Перед началом работы разработчик указывает класс задачи в заявке. **S — небольшое изменение.** Исправления, тексты, настройки — без существенного влияния на логику. **M — обычная разработка.** Новая функция или заметное изменение логики в рамках текущей архитектуры. **L — изменение повышенного риска.** Всё, что затрагивает: деньги и платежи; персональные данные; доступы и безопасность; важные интеграции; архитектуру; критичные бизнес-процессы. **Сомневаешься между классами — бери выше.** Занижение класса — нарушение протокола. --- # 2. Как проходит разработка ## Шаг 1. Описать, что хотим сделать Сначала агент изучает проект: memory bank, а там, где банк молчит или устарел, — сам код. Только потом спека. Для **M и L** до начала разработки создаётся спека в `/specs/` (скиллом `spec-grill`): что меняем и зачем; как должно работать; сценарии; ограничения и нестандартные случаи; критерии «готово». Для **S** достаточно нормального описания задачи в заявке. ## Шаг 2. Проверить, что решение подходит проекту Для **M и L** старшая модель сверяет спеку с текущим устройством проекта: нет конфликтов с архитектурой, процессами, интеграциями. Результат — раздел **«Совместимость и решения»** в спеке. Найден конфликт — сначала меняем спеку, потом пишем код. ## Шаг 3. Разработать Вся работа в отдельной ветке, main напрямую не трогаем. - **S** — обычная AI-разработка: одна сессия, один агент. - **M** — по спеке: план → код → тесты. - **L** — по спеке, рекомендованно с параллельными агентами и агентами-ломателями. ## Шаг 4. Проверить тестами Все автотесты проекта проходят — у робота зелёный свет. Новое поведение = новые тесты на него. Для **M и L** главные бизнес-сценарии **обязательно** проверяются целиком, сквозными тестами. ## Шаг 5. Независимое AI-ревью (M и L) Код проверяет отдельный AI-контекст — не тот агент, что писал. - **M** — `/code-review` или утверждённый аналог. - **L** — обязательно `/ultrareview`. Главное правило: **недостаточно сказать «здесь может быть проблема» — покажи, где именно и почему она реальна.** Подтверждение: падающий тест, воспроизводимый сценарий, конкретное место file:line. Не подтверждена — так и помечается. Итог ревью: **PASS** (подтверждённых серьёзных проблем нет) или **NEEDS_ACTION** (есть проблемы, нужен разбор). ## Шаг 6. Разобрать найденные проблемы Решение принимает разработчик, а не ИИ. По каждой подтверждённой critical/major: **Исправил** — и что именно изменено, или **Отклонил** — и почему риск приемлем. Просто проигнорировать нельзя. Пустое «ок» без причины = формальная отписка = нарушение. Подтверждённые critical/major фиксируются в `known-defects.md`. ## Шаг 7. Проверка в бою (M и L) Через 2–3 дня после выпуска: прогнать главные сценарии и новые функции на боевой системе, просмотреть логи ошибок. Итог — отметка в заявке: «работает» или переход к разбору инцидента (раздел 7). --- # 3. Дополнительные правила для класса L 1. Ревью через `/ultrareview` — обязательно. 2. Лог AI-сессии прикладывается к заявке. 3. Изменение сначала выкатывается в тестовую среду; основные сценарии проверяются до боя. 4. Владелец получает короткое резюме: что меняется, зачем, что может сломаться. 5. Пауза **24 часа**. Владелец может остановить выпуск (вето); молчание = согласие. Когда появится второй разработчик, пункты 4–5 заменяются его обязательным ревью. --- # 4. Что контролирует робот (CI) **Для S:** указан класс; работа через ветку; есть описание; тесты зелёные. **Для M дополнительно:** спека; проверка совместимости; тесты нового поведения + сквозные; отчёт AI-ревью; PASS либо полностью разобранный NEEDS_ACTION. **Для L дополнительно:** `/ultrareview`; лог сессии; проверка на тестовой среде; резюме владельцу; выдержанная пауза 24 часа. **Нет обязательного документа или проверки — merge невозможен.** --- # 5. Ответственность Ошибка в бою сама по себе не означает нарушение. **Риск принимает компания, если:** класс выбран правильно; обязательные шаги выполнены; тесты прошли; ревью проведено; проблемы разобраны; решения и причины зафиксированы. Разработчик не наказывается. **Зона ответственности разработчика, если:** шаг пропущен; класс занижен; обязательного документа нет; серьёзное замечание проигнорировано; проверка сделана формально. Оценивается не «допустил ли разработчик ошибку», а **«принял ли он разумные, предусмотренные протоколом меры, чтобы её не допустить»**. «Ответственность» = влияние на оценку, бонус и дальнейшие решения по сотруднику. Размер санкций — отдельный документ компании (с учётом трудового права). Протокол определяет **чья** зона, а не размер наказания. --- # 6. Контроль качества процесса Все ключевые решения остаются в заявке. «Я проверил» и «ИИ сказал, что нормально» доказательствами не считаются. Логи AI-сессий (Claude Code, Codex) хранятся минимум **30 дней** и поднимаются при инциденте или аудите. Раз в месяц — выборочный аудит **5–10 заявок** (владелец + разработчик). Проверяется качество, а не наличие: спека действительно описывает задачу; тесты действительно что-то проверяют; ревью было независимым; причины отклонения замечаний имеют смысл. --- # 7. Если произошёл инцидент **Сначала откатываем → потом разбираемся.** Короткий пост-мортем: что произошло; какое изменение это вызвало; почему проверки не поймали; был ли протокол выполнен; **что изменить, чтобы не повторилось** (правка протокола/скилов/тестов). --- # Инструменты **Наши скилы** (лежат в общем репозитории, там же актуальные привязки): - `spec-grill` — готовит полноценную спеку (Шаг 1); - `ai-review` — запускает нужный движок ревью и формирует стандартный отчёт (Шаг 5); - `memory-bank-update` — обновляет память проекта после изменений. **Движки** (встроенные команды Claude Code, не наши): `/code-review` — обычное ревью (M); `/ultrareview` — усиленное (L). --- # Рекомендуемый стандарт (не влияет на зону ответственности) - Memory bank проекта в репо: `projectbrief / activeContext / progress / systemPatterns / techContext / productContext / specs`. - База знаний экосистемы: реестр проектов, контракты стыков, `known-defects.md`, `project-pitfalls.md`. - Скелет проекта: стек, соглашения по коду. --- # Коротко весь процесс **S:** задача → код → тесты → merge. **M:** спека → проверка совместимости → код → тесты → AI-ревью → разбор замечаний → merge → проверка в бою (2–3 дня). **L:** спека → проверка совместимости → усиленная разработка → тесты → `/ultrareview` → разбор замечаний → тестовая среда → резюме владельцу → 24 часа → merge → проверка в бою (2–3 дня). --- # Чек-листы (скопируй блок своего класса в заявку) **Класс S** - [ ] Класс S указан в заявке - [ ] Работал в ветке, main напрямую не трогал - [ ] Что и зачем изменено — описано в заявке - [ ] Все автотесты проходят **Класс M** - [ ] Класс M указан в заявке - [ ] Агент изучил проект (memory bank / код) до спеки - [ ] Спека в `/specs/` через `spec-grill` - [ ] Совместимость подтверждена старшей моделью — раздел в спеке заполнен - [ ] Работал в ветке - [ ] Новые тесты на новое поведение + сквозные тесты на главные сценарии - [ ] Все автотесты проходят - [ ] AI-ревью отдельным контекстом, отчёт в заявке - [ ] PASS — или NEEDS_ACTION с разбором: каждая critical/major — «исправил / отклонил + почему» - [ ] Подтверждённые critical/major внесены в `known-defects.md` - [ ] Через 2–3 дня после выпуска: сценарии прогнаны в бою, отметка в заявке **Класс L** - [ ] Класс L указан в заявке - [ ] Агент изучил проект (memory bank / код) до спеки - [ ] Спека в `/specs/` через `spec-grill` - [ ] Совместимость подтверждена старшей моделью — раздел в спеке заполнен - [ ] Работал в ветке - [ ] Новые тесты + сквозные тесты на главные сценарии - [ ] Все автотесты проходят - [ ] Ревью движком `/ultrareview`, отчёт в заявке - [ ] PASS — или NEEDS_ACTION с разбором каждой critical/major - [ ] Подтверждённые critical/major внесены в `known-defects.md` - [ ] Лог AI-сессии приложен к заявке - [ ] Выкатка на тестовую среду, сценарии проверены до боя - [ ] Резюме владельцу отправлено - [ ] Пауза 24 часа выдержана, вето не поступило - [ ] Через 2–3 дня после выпуска: сценарии прогнаны в бою, отметка в заявке --- *Внедрение: пилот на одном проекте 4 недели без привязки санкций → правки по результатам → полный запуск с правилами ответственности.* **Правило, которое важнее всего остального:** > ИИ может ошибаться. Разработчик тоже. Задача протокола — не гарантировать отсутствие ошибок, а сделать так, чтобы важные решения были осознанными, проверяемыми и зафиксированными. *v2.1 — добавлены: изучение проекта агентом до спеки; проверка в бою через 2–3 дня после выпуска (M/L).*