AI-NATIVE-SDD-REGULATION.MD

AI-Native Delivery — Регламент

Разработка через Spec-Driven Development на OpenSpec

Документ разбит на три файла. Этот — постоянный регламент (Части 0–7): роли, флоу, формат требований, контроль качества. Отдельно — План миграции и Инструменты и справочник.

Часть 0Коротко о подходе

0.1Суть подхода

Мы переводим разработку на модель, в которой спецификация — это исполняемое задание, а не сопроводительный документ. Требования пишутся в структурированном машиночитаемом формате, хранятся в git (в отдельном спек-репозитории, подключённом к кодовому — §5.6), проходят ревью так же, как код, и служат единственным входом для AI-агента, который пишет реализацию.

Формат и жизненный цикл задаёт OpenSpec — open-source CLI (MIT). Сам он код не пишет и агентом не является: он устанавливает в репозиторий набор слэш-команд и навыков для Claude Code (/opsx:propose, /opsx:apply и т. д.), которые ведут агента по стадиям «предложение → спецификация → реализация → архивация». Работает всё это внутри Claude Code — OpenSpec лишь задаёт структуру задания, которую агент выполняет.

0.2Как это работает

Стейкхолдеры формулируют потребность → аналитик описывает её как спецификацию → техлид утверждает спецификацию (Гейт 1) → разработчик реализует её в коде вместе с агентом, отвечая за структуру решения и качество результата → техлид проверяет код (Гейт 2) → QA принимает результат по тем же сценариям, что описаны в спецификации.

Два гейта — единственные места, где процесс может быть остановлен. Гейт 1 — точка управления процессом. Ни одна строка кода не пишется, пока спецификация не утверждена. Расхождение между тем, что задумано, и тем, что реализовано, обнаруживается здесь — до того как написана хоть одна строка кода. Исправление на этом этапе стоит правки абзаца; исправление после того, как код уже написан и прошёл ревью, обходится заметно дороже — вплоть до переписывания модуля в худшем случае.

Полная детализация каждого этапа — Часть 3; полная матрица ролей — Часть 2.

Определяющие свойства процесса:

0.3Кто за что отвечает

За каждый шаг флоу отвечает ровно один человек — роли не пересекаются. Полная матрица ответственности (RACI) по всем 15 шагам флоу — §2.2; подробное описание каждой роли — §2.3.

0.4Что это даёт и какие есть риски

Что это даёт. Инженерно — ошибка «требования ↔ реализация» ловится на ревью спецификации, а не в готовом коде. Экономически — эффект двойной: агент пишет код быстрее человека, и это сокращает время самой реализации; вдобавок расхождение дешевле поймать на спецификации, чем чинить в уже написанном коде, — это сокращает переделки. Управленчески — вместо того, чтобы контроль был размазан по каждому этапу, есть один явный момент, где можно остановить или скорректировать фичу до того, как в неё вложено время разработки, — Гейт 1, с одним явным ответственным (техлидом). Организационно — основная спецификация (openspec/specs/) обновляется в момент, когда код попадает в прод: архивация (§3.7) выполняется сразу при мерже PR с кодом, поэтому между «код задеплоен» и «спецификация актуальна» нет паузы, в которую обновление можно забыть.

Риски и ограничения. Главный риск — избыточная спецификация: превращение процесса в водопад, где на однострочное изменение пишется десять страниц. Это основная задокументированная критика SDD. Закрывается правилом применимости (§1.3) и облегчёнными треками (§3.8): спецификация пишется тогда и только тогда, когда меняется внешне наблюдаемое поведение системы.

Второй риск — ёмкость ревью: агент производит код быстрее, чем человек его читает. Подход не решает эту проблему сам по себе; её решают автоматические гейты, риск-тиринг и лимит размера PR (Часть 7).

0.5Что требуется для запуска

0.6Как мигрируем

Подробный план с ролями, рисками и точками Go/No-Go — План миграции.

0.7Быстрый старт: чек-лист на первую фичу

Аналитик

• Получить доступ на чтение к спек-репозиторию (справочник, §2).
• Прочитать формат требования (§4.2) и таблицу антипаттернов (§4.6) — один раз, до первой спецификации.
• Дождаться инициативы от ПМ (§3.2), пройти Explore вместе с техлидом (§3.3).
• Создать change: /opsx:propose "<описание>" (§3.4).
• Заполнить proposal.md и specs/**/spec.md — по образцу готового примера (справочник, §4) или пустому шаблону (справочник, §5).
• Прогнать openspec validate <change> --strict до нуля ошибок.
• Пройти чек-лист Definition of Ready (§4.5) перед подачей.
• Открыть PR в спек-репозитории → Гейт 1 (§3.5).

Техлид

• Пройти чеклист готовности репозитория (§5.7) — без уровня 0 флоу не начинается.
• Настроить submodule-связь спек-репозитория с кодовым (§5.6) и CLAUDE.md (§5.3).
• Определить обязательные проверки в CI — что должно быть зелёным (§7.6); branch protection настраивает DevOps.
• Участвовать в Explore первой фичи (§3.3): дать ограничения системы, решить, нужны ли спецификация (§1.3) и design.md (§2.3).
• Провести Гейт 1 по чеклисту §7.2.
• Провести Гейт 2 по риск-тиру (§7.4) и чеклисту §7.3.
• Провести ретро пилота и зафиксировать Go/No-Go (план миграции, §3, §5).

Разработчик

• Прочитать proposal.md, specs/, design.md (если есть) целиком до старта (§6.2, шаг 1).
• Уточнить декомпозицию tasks.md (§6.2, шаг 2).
• Запустить реализацию: /opsx:apply <change-name> (§6.2, шаг 3).
• Вести сессию по правилам §6.2 (шаг 4): один change — одна сессия, коммит и проверка после каждой задачи.
• Обеспечить именование тестов по сценариям спецификации (§6.2, шаг 5).
• Пройти самопроверку перед PR (§6.2, шаг 6).
• Открыть PR с кодом в кодовом репозитории → Гейт 2.
• После мержа — openspec archive и обновление submodule (§3.7).

QA

• Проверить приёмопригодность сценариев на ревью спецификации, как Consulted (§2.3).
• Дождаться мержа PR с кодом (Гейт 2 пройден, автопроверки зелёные — §7.6).
• Провести приёмку строго по списку сценариев спецификации (§3.7).
• На каждый дефект — ссылка на нарушенный сценарий (capability/Requirement/Scenario).

Часть 1Принципы

1.1Принцип

Спецификация — единственный источник истины о требуемом поведении системы. Она хранится в репозитории, версионируется вместе с кодом, изменяется тем же pull request'ом и служит прямым входом для реализации.

Из принципа следуют четыре правила, которые определяют всё остальное в этом документе:

1. Правило локальности. Спецификация физически присутствует в рабочем дереве, которое читает агент, — кодовый репозиторий подключает её как git submodule на пути openspec/ (§5.6). Агент по-прежнему работает с одним рабочим деревом, а не переключается между носителями; разделены только права доступа людей — аналитик работает в отдельном спек-репозитории, разработчик и агент видят оба.
2. Правило буквальности. Требование записывается так, чтобы из него однозначно следовала проверка. Если из требования нельзя вывести тест, это не требование, а намерение.
3. Правило дельты. Мы не документируем всю систему. Спецификация пишется только на то, что меняется. Полная картина накапливается сама, по мере изменений.
4. Правило синхронности. Основная спецификация (openspec/specs/) обновляется в момент, когда код попадает в основную ветку: архивация (§3.7) выполняется сразу при мерже PR с кодом — автоматически в CI либо ручной командой сразу после мержа, до перехода к следующей задаче. Между «код в проде» и «спецификация актуальна» нет паузы, в которую обновление можно забыть.

1.2Что такое OpenSpec и чем он не является

OpenSpec — open-source инструмент для spec-driven development (лицензия MIT, npm-пакет @fission-ai/openspec). Состоит из двух половин:

• CLI — команда openspec, которую запускают в терминале. Создаёт структуру, валидирует артефакты, применяет изменения к основным спецификациям, архивирует завершённое.
• Набор навыков и слэш-команд для Claude Code (/opsx:propose, /opsx:apply и т. д.). Устанавливается в репозиторий командой openspec init.

Чем OpenSpec не является:

Риск привязки — низкий. Артефакты OpenSpec — обычные Markdown-файлы в вашем репозитории. При отказе от инструмента остаются все спецификации; теряются только слэш-команды и автоматика слияния дельт в основные спецификации.

1.3Границы применимости: когда спецификация нужна, а когда нет

Это самое важное правило документа. Его нарушение — главный способ провалить внедрение.

Спецификация пишется тогда и только тогда, когда меняется внешне наблюдаемое поведение системы.

Внешне наблюдаемое поведение — это то, на что полагается пользователь, мерчант, смежный сервис или интеграция: контракты API, коды ошибок, переходы состояний, формат событий и вебхуков, правила расчёта, ограничения доступа, гарантии производительности и безопасности.

Проверочный вопрос перед тем, как заводить change: «Может ли реализация полностью измениться без изменения того, что видит потребитель?» Если да — это деталь реализации, ей не место в спецификации.

Симптомы избыточной спецификации (требуют немедленной остановки и пересмотра):

• Спецификация на изменение длиннее, чем сам diff.
• В требованиях фигурируют имена классов, функций, библиотек.
• На однострочное изменение заведено несколько требований.
• Ревьюер говорит «мне проще прочитать код, чем это».

Часть 2Роли и зоны ответственности

2.1Состав ролей

Потребность и ценность фичи формулируют стейкхолдеры — бизнес-заказчики (владелец продукта или направления, руководитель подразделения, внешний партнёр). Они не входят в ежедневный флоу и не участвуют в RACI ниже: ПМ формализует их запрос в инициативу (§3.2) и держит с ними связь до приёмки результата.

Над операционными ролями этой таблицы стоит CTO — руководитель инженерной организации компании. Он не входит в RACI одной фичи (Части 2–3 описывают процесс на уровне одной команды и одного репозитория) и не участвует в повседневном флоу. Его роль — точка эскалации и решения, когда вопрос выходит за пределы одной команды или одного репозитория: конфликт между техлидом и аналитиком/ПМ о необходимости спецификации (§7.9), владение разворачиванием подхода за пределы пилотного проекта (план миграции, §4), решения Go/No-Go о переходе между фазами (план миграции, §5).

Платформенную инфраструктуру — CI-платформу, SAST-сканирование, dependency-ботов, настройки репозитория на GitHub (branch protection, CODEOWNERS) — ведёт DevOps. Это внешняя по отношению к флоу фичи функция: DevOps не входит в RACI ниже и обслуживает инфраструктуру централизованно для всех репозиториев, а не в рамках отдельной фичи (инструменты — справочник, §1).

2.2Матрица ответственности (RACI)

Правила чтения матрицы:

• В каждой строке ровно один A. Если непонятно, кто останавливает процесс, — смотрите, у кого A.
• R без A означает: делает руками, но за результат отвечает другой.
• C обязателен до принятия решения. Пропустить C — процессное нарушение, а не ускорение.

2.3Что делает каждая роль

Проектный менеджер

Отвечает: формализует потребность стейкхолдеров в инициативу, держит приоритет, границы и сроки, принимает результат.

Делает:

• Забирает у стейкхолдеров проблему, ожидаемый эффект и ограничения по срокам и бюджету и формулирует инициативу.
• Определяет границы: что входит в фичу и что явно не входит.
• Участвует в Гейте 1 как Consulted — подтверждает, что спецификация описывает ту фичу, которую заказали стейкхолдеры.
• Принимает результат по бизнес-критериям и уведомляет стейкхолдеров.

Не делает: не пишет требования уровня сценариев, не принимает технические решения, не согласовывает архитектуру.

Точка отказа ПМ: инициатива без измеримого критерия успеха. Такая инициатива не переходит на этап 1.

Аналитик

Отвечает: за то, что требования полны, однозначны и проверяемы. Это центральная роль нового процесса.

Делает:

• Ведёт discovery с бизнесом и с техлидом.
• Изучает существующие спецификации в openspec/specs/, чтобы не противоречить действующим требованиям.
• Пишет proposal.md: почему, что меняется, какие способности (capabilities) затрагиваются, на что это влияет.
• Пишет specs/**/spec.md: требования и сценарии в формате §4.2.
• Прогоняет openspec validate <change> --strict до нуля ошибок и предупреждений.
• Заводит PR со спецификацией и проводит его через Гейт 1.
• После реализации подтверждает, что дельта корректно слита в основные спецификации.

Не делает: не выбирает технологии, не проектирует внутреннюю структуру кода, не оценивает трудоёмкость реализации.

Техлид

Отвечает: за архитектурные решения и за планку, через которую проходит всё, что попадает в кодовую базу. Владелец обоих гейтов.

Техлид не диктует детали реализации и не переписывает решения разработчика построчно — его инструменты влияния: утверждение спецификации (Гейт 1), архитектурные ограничения (design.md, когда он нужен) и ревью на Гейте 2 (§7.3). Всё, что не относится к архитектуре, — зона ответственности разработчика.

Делает:

• Участвует в explore: приносит ограничения системы, показывает существующие решения, отсекает нереализуемое.
• Принимает решение о необходимости спецификации (§1.3) и об уровне риска изменения (§7.4).
• Пишет design.md только когда изменение сквозное, затрагивает архитектуру, вводит новую зависимость, меняет модель данных или несёт риски безопасности/производительности/миграции. Для большинства изменений design.md не нужен вовсе — технические решения на уровне кода разработчик принимает сам.
• Проводит Гейт 1 — единственная точка, где процесс поставки требований управляем (§7.2).
• Проектирует автоматические гейты: какие проверки должны быть зелёными, чтобы PR был вообще пригоден к чтению человеком.
• Проводит Гейт 2 — ревью кода с глубиной, определяемой риск-тиром (§7.3, §7.4).
• Владеет CLAUDE.md и политикой изменения его правил.

Не делает: не принимает решения, которые по своей природе принадлежат разработчику (структура функции, выбор внутреннего паттерна в рамках конвенций). При росте объёма его работа смещается от построчного чтения к проектированию проверок и выборочному контролю (§7.7).

Разработчик

Отвечает: за инженерную реализацию — за то, что она соответствует спецификации, технически обоснована и доказана проверками. Это его инженерная зона ответственности: он ведёт агента, отвечает за структуру решения, качество кода и прохождение ревью, а не просто отправляет запрос и проверяет результат.

Делает:

• Читает proposal.md, specs/, design.md (если он есть) до начала работы. Полностью, а не по диагонали.
• Самостоятельно принимает все технические решения на уровне реализации: структуру кода, разбиение на функции и модули, выбор паттернов в рамках существующих конвенций и (если есть) ограничений design.md. Это его решения, а не техлида.
• Уточняет tasks.md: разбивает работу так, чтобы каждая задача имела явный способ проверки.
• Ведёт реализацию с агентом по циклу §6.2 — направляет, проверяет промежуточные результаты, останавливает и перезапускает при отклонении от намеченного решения.
• Пишет тесты, покрывающие каждый сценарий спецификации, с явной привязкой имени теста к имени сценария.
• Прогоняет полный набор локальных проверок до открытия PR.
• Останавливается и формулирует конкретный вопрос, если спецификация неполна, противоречива или расходится с реальностью системы. Не додумывает.

Не делает: не расширяет объём молча, не «улучшает» поведение сверх спецификации, не пишет код по устному согласованию в обход спецификации.

Разработчик не переводит требования в промпт вручную — этот шаг выполняет спецификация. Его вклад — инженерные решения, декомпозиция, проверяемость и контроль качества результата агента.

QA

Отвечает: за приёмку по сценариям.

Делает:

• Участвует в ревью спецификации как Consulted: проверяет, что каждый сценарий приёмопригоден и что покрыты негативные пути.
• Проводит приёмку строго по списку сценариев спецификации.
• Заводит дефект с явной ссылкой на нарушенный сценарий (capability/Requirement/Scenario).

Не делает: не изобретает критерии приёмки в момент тестирования. Если критерия нет в спецификации, это дефект спецификации, а не кода.

2.4Где находится точка управления

Точка управления процессом поставки требований — Гейт 1 (утверждение спецификации). Одна точка, один ответственный (техлид), один явный артефакт (PR со спецификацией), одно бинарное решение (утверждено / возвращено).

Всё, что находится до Гейта 1, — управляемо и дёшево в изменении. Всё, что после, — дорого. Поэтому весь управленческий вес процесса сосредоточен здесь, а не в ревью кода.

Техлид управляет результатом четырьмя рычагами, применяемыми именно в этом порядке:

Рычаги 1 и 2 — превентивные и масштабируемые: их стоимость не растёт с объёмом кода. Рычаг 3 — способ удержать постоянную стоимость контроля при растущем объёме кода (детально — §7.7). Рычаг 4 — снижение вероятности проблемы до её появления.

Если результат подхода расходится с ожиданиями не разово, а систематически — это уже не вопрос одного гейта, а вопрос эскалации (§7.9) и, на масштабе всей миграции, критериев Go/No-Go (план миграции, §5).

Часть 3Сквозной флоу фичи

3.1Карта этапов

3.2Этап 0 — Инициация

Кто: ПМ (A/R), Стейкхолдеры (C).

Стейкхолдеры формулируют потребность; ПМ формализует её в инициативу и заводит задачу в Jira. Обязательный минимум:

• Проблема: что не работает или чего не хватает, у кого.
• Ожидаемый эффект: что изменится и как это будет видно.
• Границы: что явно не входит в эту работу.
• Срочность и её обоснование.

Выход этапа: задача в Jira в статусе, допускающем разбор. Задача без измеримого критерия успеха на разбор не берётся.

3.3Этап 1 — Explore (разбор)

Кто: Аналитик (A/R), Техлид (R), Разработчик (R), ПМ и QA (C).

Цель — снять неопределённость до того, как что-то будет написано. Explore идёт в двух отдельных сессиях с Claude Code: аналитик — в спек-репозитории, читает действующие спецификации и отвечает на вопросы про требования; техлид или разработчик — в кодовом репозитории, читает код, тесты и конфигурацию и отвечает на вопросы про систему. Аналитик не имеет доступа к коду (справочник, §2), поэтому факты о коде ему приносит техлид или разработчик, а не наоборот.

/opsx:explore

Режим explore не пишет код и не создаёт артефакты без явного подтверждения — это исследовательская стадия.

Что должно быть выяснено к концу этапа:

Выход этапа: согласованное понимание объёма и решение техлида о том, нужна ли спецификация и нужен ли design.md.

Типовая длительность: от 30 минут до половины дня. Если разбор занимает больше дня, фича слишком большая — её нужно разделить.

3.4Этап 2 — Спецификация

Кто: Аналитик (A/R) — proposal.md и specs/; Техлид (A/R) — design.md, когда он нужен (§2.3); tasks.md — Разработчик (A/R), Техлид (C).

Аналитик работает в спек-репозитории (не в кодовом — справочник, §2): создаёт change и наполняет артефакты, работая с агентом.

/opsx:propose "автоматический ретрай выплат при временной ошибке провайдера"

Команда создаёт директорию изменения и последовательно строит артефакты в порядке зависимостей. Итоговая структура:

openspec/changes/add-payout-retry/
├── .openspec.yaml        # метаданные этого изменения: используемая схема, дата создания
├── proposal.md           # зачем, что меняется, какие capabilities, на что влияет
├── specs/
│   └── payout-retry/
│       └── spec.md       # ДЕЛЬТА: только то, что добавляется/меняется/удаляется
├── design.md             # техническое решение (условный артефакт)
└── tasks.md              # чеклист реализации

Важно: файлы в changes/<name>/specs/ — это дельта, а не полная спецификация способности. Полные спецификации живут в openspec/specs/ и обновляются автоматически при архивации.

Порядок работы аналитика:

1. Прочитать действующие спецификации затрагиваемых способностей.
2. Заполнить proposal.md, в том числе раздел ## Capabilities — он определяет, какие файлы спецификаций будут созданы или изменены.
3. Написать дельты требований в specs/<capability>/spec.md по формату §4.2.
4. Прогнать валидацию до нуля замечаний:

   openspec validate add-payout-retry --strict

5. Передать техлиду для design.md, если он требуется (§2.3).
6. Согласовать с разработчиком черновую декомпозицию tasks.md — детали разработчик уточняет сам перед стартом реализации (§6.2).

Выход этапа: pull request в спек-репозитории, содержащий только директорию changes/<name>/. Без кода.

Почему спецификация идёт отдельным PR: это делает утверждение требований явным событием с датой, автором и обсуждением, отделяет спор о требованиях от спора о реализации и позволяет начать реализацию с зафиксированной базы.

3.5Этап 3 — ГЕЙТ 1: ревью спецификации

Кто: Техлид (A), Аналитик (R), ПМ и QA (C).

Это главная контрольная точка процесса. Подробный чеклист — §7.2.

Норматив: ревью спецификации проводится в течение одного рабочего дня с момента открытия PR. Спецификация, ожидающая ревью дольше, — организационный дефект, который эскалируется ПМ.

3.6Этап 4 — Реализация

Кто: Разработчик (A/R), Техлид (C).

Реализация ведётся строго по утверждённой спецификации:

/opsx:apply add-payout-retry

Агент читает все артефакты изменения, идёт по задачам tasks.md, отмечает выполненные и останавливается при неясности или расхождении. Детальный порядок работы разработчика — Часть 6.

Жёсткое правило: если в ходе реализации выясняется, что спецификация неверна, неполна или противоречит устройству системы, — работа останавливается, спецификация правится, изменение проходит сокращённое повторное ревью. Реализация «как правильнее» в обход спецификации запрещена: она возвращает нас ровно к той проблеме, ради которой вводится процесс.

Для правки артефактов уже существующего изменения:

/opsx:update add-payout-retry

Выход этапа: pull request с кодом, тестами и отмеченными задачами в tasks.md.

3.7Этап 5 — ГЕЙТ 2 и этап 6 — приёмка

Гейт 2 (Техлид, A/R) — ревью кода. Глубина определяется риск-тиром изменения (§7.4), содержание — чеклистом §7.3. Обязательное предусловие: все автоматические проверки зелёные (§7.6). PR с красным CI на человеческое ревью не выносится.

Приёмка (QA, A/R) — проверка строго по списку сценариев спецификации. Дефект оформляется со ссылкой на нарушенный сценарий.

Архивация (Техлид A, Аналитик и Разработчик R) — сразу после мержа кода, до перехода к следующей задаче:

/opsx:archive add-payout-retry

При архивации дельты сливаются в основные спецификации specs/<capability>/spec.md, а директория изменения переносится в changes/archive/YYYY-MM-DD-<name>/. С этого момента основная спецификация отражает актуальное поведение системы.

Как это ложится на git (спек-репозиторий и кодовый репозиторий разделены, §5.6): у фичи два PR и один служебный коммит. PR №1 — только спецификация, открывается и мержится в спек-репозитории, проходит Гейт 1. Разработчик обновляет указатель submodule в кодовом репозитории на этот коммит и открывает PR №2 — код (плюс обновлённый указатель), в кодовом репозитории, проходит Гейт 2. Сразу после мержа PR №2 разработчик выполняет openspec archive в спек-репозитории (коммит туда, обычно без повторного Гейта — это техническая операция, а не новое требование) и следом обновляет указатель submodule в кодовом репозитории на архивный коммит. Порядок — не на усмотрение: без финального обновления указателя кодовый репозиторий продолжит ссылаться на неархивированную версию specs/, и openspec/specs/ в нём будет отставать от реального состояния.

Выход этапа: фича в продакшене; openspec/specs/ актуален; изменение в архиве.

3.8Облегчённые треки

Не всякая работа проходит полный флоу. Треки выбирает техлид на этапе 1.

Правило одного предложения. Если изменение полностью описывается одним предложением и его diff читается за минуту — спецификация не пишется. Стоимость процесса не должна превышать стоимость работы.

3.9Связь с Jira и Confluence

Процесс не отменяет существующие инструменты, а разграничивает зоны.

Правила связывания:

• Задача в Jira содержит ссылку на PR со спецификацией и на директорию изменения.
• Директория изменения именуется так, чтобы ключ задачи был восстановим: рекомендуется <jira-key>-<kebab-name>, например PAY-1423-add-payout-retry.
• Confluence-страница фичи, если она нужна бизнесу, ссылается на спецификацию, а не дублирует её. Дублирование требований запрещено: два источника истины гарантированно разойдутся.

Что делать с действующими Confluence-требованиями: ничего. Они не переносятся массово. При первом изменении затронутой части системы соответствующие требования появляются в openspec/specs/ как дельта, а страница Confluence помечается ссылкой на спецификацию. Полный перенос — антипаттерн: он дорог и создаёт спецификации на код, который никто не собирается менять.

Часть 4Требования: формат и стандарт качества

4.1Четыре артефакта и их назначение

Разделение жёсткое и не подлежит смешению:

• В spec.md не должно быть имён классов и функций, выбора библиотек, пошаговых инструкций реализации.
• В design.md не должно быть мотивации (она в proposal.md) и требований (они в spec.md).
• Проверочный вопрос для спецификации: если реализацию можно полностью заменить, не изменив того, что видит потребитель, — этому не место в спецификации.

4.2Формат требования

Дельта-спецификация состоит из блоков операций. Допустимы ровно четыре заголовка второго уровня:

Структура требования:

Жёсткие правила формата (проверяются валидатором):

1. Сценарий — ровно четыре решётки (####). Три решётки или маркированный список валидатор молча не засчитает как сценарий.
2. У каждого требования минимум один сценарий. Требование без сценария — ошибка валидации.
3. Нормативные слова — SHALL / MUST, в теле требования, а не в заголовке. Слова «should», «may», «желательно» в требованиях не используются: они не проверяемы.
4. Для новой способности дельта начинается с раздела ## Purpose длиной не менее 50 символов. Для существующей способности ## Purpose в дельте не пишется.
5. При MODIFIED требование копируется целиком из основной спецификации и правится. Частичное копирование приводит к потере сценариев при архивации.

Совместимость с EARS. Формат совместим с нотацией EARS (Easy Approach to Requirements Syntax, Mavin, Wilkinson, Harwood, Novak, IEEE RE'09) — общепринятым способом писать однозначные требования. Соответствие шаблонов:

Специальный синтаксис EARS учить не нужно: достаточно писать сценарии в форме WHEN/THEN и следить, чтобы каждое требование имело чёткое условие и чёткий наблюдаемый результат.

4.3Контракты интерфейсов

Расхождение по интерфейсам — самый дорогой класс расхождений, потому что его последствия видны потребителям. Поэтому контракт фиксируется в спецификации явно.

Обязательно фиксируется в спецификации:

Не фиксируется в спецификации: внутренние DTO, структура таблиц, имена очередей, выбор библиотек, внутренние интерфейсы модулей. Это design.md.

Практика для API-контракта. Если в проекте есть машиночитаемая схема API (OpenAPI), спецификация ссылается на неё, а изменение схемы входит в тот же pull request. Схема — исполняемая часть контракта; спецификация — та часть, которую схема выразить не может: правила, инварианты, условия переходов.

4.4Нефункциональные требования

Нефункциональное требование записывается тем же способом, что и функциональное, но с измеримым порогом. Формулировки без числа не принимаются.

Общесистемные нефункциональные требования (единые для всех сервисов) выносятся в отдельную способность, например openspec/specs/platform-nfr/spec.md, и не повторяются в каждом изменении.

4.5Definition of Ready для спецификации

Спецификация выносится на Гейт 1 только при выполнении всех пунктов. Проверяет аналитик перед открытием PR. По-хорошему первые пункты (валидатор, наличие сценариев, отсутствие упоминаний реализации) стоит автоматизировать CI-проверкой на PR в спек-репозитории, а не держать на памяти аналитика — так же, как автоматические гейты в Части 7.

• openspec validate <change> --strict завершается без ошибок и предупреждений.
• Раздел ## Why объясняет проблему, а не решение.
• Раздел ## Capabilities перечисляет все затрагиваемые способности; для каждой существует файл дельты.
• Каждое требование содержит SHALL или MUST в теле.
• Каждое требование имеет минимум один сценарий.
• Для каждого требования есть сценарий негативного пути или явно указано, что его нет.
• Описаны граничные значения: пустое, максимальное, нулевое, повтор, параллельный вызов.
• Описано поведение при недоступности внешних зависимостей.
• Изменения контрактов зафиксированы явно; ломающие изменения помечены BREAKING.
• Нефункциональные требования содержат числовые пороги.
• Нет упоминаний классов, функций, библиотек и таблиц.
• Нет противоречий с действующими спецификациями затрагиваемых способностей.
• Термины соответствуют глоссарию проекта; синонимы не используются.
• Объём соразмерен изменению (см. §1.3).

4.6Антипаттерны требований

Полный провалидированный пример всех четырёх артефактов на сквозной фиче — справочник, §4.

Часть 5Подготовка репозиториев

5.1Зачем это нужно

Подготовка кодовой базы — не опциональный шаг, а условие получения эффекта. Исследование DORA по AI-ассистированной разработке формулирует это так: AI является усилителем — он увеличивает и сильные, и слабые стороны организации. На здоровой кодовой базе с быстрой обратной связью агент даёт кратный выигрыш; на кодовой базе без надёжных проверок он с той же скоростью производит правдоподобный неверный код.

Практический смысл подготовки — дать агенту две вещи, которых у него нет по умолчанию:

1. Проверку, которую он может запустить сам. Без неё единственный доступный агенту сигнал завершения — «выглядит готовым».
2. Контекст ровно в том объёме, который нужен. Контекстное окно — конечный ресурс с убывающей отдачей. Задача — не «дать больше», а «дать самое существенное».

5.2Уровень 0 — обязательный минимум

Без этого уровня переход на подход не начинается. Проверяется на чистой машине.

Рекомендуемая конвенция для монорепозитория на pnpm: единая точка входа в проверку на корневом уровне, например скрипт verify, объединяющий сборку, линт, типизацию и тесты, чтобы и человек, и агент, и CI использовали одну и ту же команду. Разные команды у человека и у CI — источник расхождений.

5.3Уровень 1 — инструкции для агента

CLAUDE.md — корневой файл инструкций, который Claude Code читает автоматически. Это основной носитель правил проекта.

Что должно быть в корневом файле инструкций

Держите его коротким — ориентир около 100–200 строк. Длинный файл вытесняет из контекста то, ради чего агент вызван.

Ниже — не готовый файл, а шаблон структуры: разделы и плейсхолдеры <...> заполняются содержимым конкретного репозитория.

# <Название проекта>

## Что это
Одно-два предложения: назначение системы и её доменная область.

## Структура
- `apps/*` — сервисы, по одному на бизнес-домен
- `packages/*` — переиспользуемые пакеты
- `openspec/specs/` — действующие требования к поведению (источник истины)
- `openspec/changes/` — изменения в работе

## Команды
- Установка: `<команда>`
- Полная проверка: `<команда>`
- Тесты одного сервиса: `<команда>`
- Запуск локально: `<команда>`

## Обязательные правила
- Перед завершением задачи прогнать полную проверку. Красный статус — работа не завершена.
- Не менять публичные контракты API и событий без соответствующего изменения в `openspec/`.
- Не добавлять новые зависимости без явного согласования.
- Не отключать и не помечать как пропускаемые существующие тесты.
- Коммиты — по Conventional Commits.

## Конвенции кода
- <язык, версия, стиль, обработка ошибок, логирование>
- <как устроены слои и что откуда можно импортировать>

## Термины
- <5–15 доменных терминов с однозначными определениями>

## Чего не делать
- <перечень известных ловушек этого репозитория>

Вложенные файлы инструкций

В монорепозитории корневой файл описывает общее, а специфика сервиса — в файле рядом с сервисом (apps/<service>/CLAUDE.md).

Глоссарий — отдельно и обязательно

Единый глоссарий доменных терминов — самый дешёвый способ убрать целый класс расхождений. Синонимы в требованиях агент интерпретирует как разные сущности. Глоссарий ведётся в репозитории и на него ссылаются и спецификации, и инструкции.

5.4Уровень 2 — управление контекстом

Принцип: качество контекста определяется не объёмом, а долей существенного. Каждый лишний файл в контексте — это вытесненный полезный.

5.5Уровень 3 — автоматика и интеграции

5.6Установка OpenSpec в репозиторий

Топология: спек-репозиторий и кодовый репозиторий

Спецификации и код живут в двух разных репозиториях, а не в разделах одного. Причина — контроль доступа: ни git, ни GitHub не разделяют права на чтение по пути внутри одного репозитория, только по репозиторию целиком. Единственный способ дать аналитику доступ к требованиям и не дать доступ к коду — физически развести их по репозиториям (рабочее место аналитика — справочник, §2).

Механика связи — git submodule: кодовый репозиторий подключает спек-репозиторий на пути openspec/.

# один раз, при подключении спек-репозитория к кодовому
cd <кодовый-репозиторий>
git submodule add <url-спек-репозитория> openspec
git commit -m "chore: подключить спек-репозиторий как submodule"

# при каждом клоне кодового репозитория
git clone --recurse-submodules <url-кодового-репозитория>

# обновить submodule на последний мерженый коммит спек-репозитория
git submodule update --remote openspec

Команды openspec и слэш-команды Claude Code (/opsx:*) работают без изменений: агент и разработчик видят содержимое спек-репозитория как обычную папку openspec/ в рабочем дереве кодового репозитория. Разница только в правах доступа людей: спек-репозиторий — аналитик, техлид, разработчики на запись, ПМ и QA на чтение (для участия в Гейте 1 и приёмки — §3.5, §3.7); кодовый репозиторий — техлид и разработчики, без аналитика.

Установка

Требуется Node.js 20.19.0 или новее.

# установка CLI
npm install -g @fission-ai/openspec@latest

# инициализация — выполняется в корне спек-репозитория, не кодового
cd <спек-репозиторий>
openspec init

openspec init спросит, для каких ассистентов настроить команды, и создаст в корне спек-репозитория:

config.yaml                   # схема воркфлоу и проектный контекст
specs/                        # действующие спецификации (источник истины)
changes/
└── archive/                  # архив завершённых изменений

.claude/skills/openspec-*/    # навыки для Claude Code
.claude/commands/opsx/        # слэш-команды для Claude Code

После git submodule add этот же набор виден в кодовом репозитории на пути openspec/config.yaml, openspec/specs/ и так далее.

Обратите внимание: openspec init не создаёт и не перезаписывает ваш CLAUDE.md — его содержимое остаётся за вами.

Проектный контекст задаётся в openspec/config.yaml и подставляется агенту при создании артефактов:

schema: spec-driven

context: |
  Стек: TypeScript, NestJS, pnpm-монорепозиторий, PostgreSQL, Redis.
  Домен: платёжный шлюз (платежи, выплаты, кошельки, вебхуки мерчантам).
  Соглашения: Conventional Commits; публичные контракты фиксируются в OpenAPI.
  Спецификации пишутся на русском языке.

rules:
  proposal:
    - Раздел Why не длиннее пяти предложений
    - Всегда явно указывать, является ли изменение ломающим
  specs:
    - Каждое требование обязано иметь сценарий негативного пути
    - Нефункциональные требования обязаны содержать числовой порог
  tasks:
    - Каждая задача содержит способ проверки в своём тексте

Раздел rules — рабочий инструмент техлида: им планка требований задаётся один раз и применяется автоматически ко всем изменениям, вместо повторения одних и тех же замечаний на ревью.

Обновление команд и навыков после выхода новой версии CLI:

openspec update

Телеметрия. OpenSpec по умолчанию отправляет анонимную статистику использования (имя команды и версия). Отключается одним из способов:

openspec config set telemetry.enabled false
# либо переменными окружения OPENSPEC_TELEMETRY=0 или DO_NOT_TRACK=1

Для корпоративного использования отключение телеметрии рекомендуется закрепить в настройках репозитория.

5.7Чеклист готовности репозитория

Заполняется до старта Фазы 1. Порог допуска — 80 % пунктов, при этом все пункты уровня 0 обязательны.

Уровень 0 — обязательно

• Установка с чистого клона — одна команда
• Полная проверка — одна команда, ненулевой код возврата при ошибке
• Полная проверка на изменённом коде укладывается в минуты
• Нестабильных тестов нет либо они изолированы и не блокируют
• Секретов в репозитории нет
• Обязательные проверки (сборка, линт, тесты) подключены в CI и видны в каждом PR

Уровень 1 — инструкции

• Есть CLAUDE.md
• Файл короткий, содержит команды, правила и структуру
• Есть глоссарий доменных терминов
• Для сервисов со своей спецификой есть вложенные файлы инструкций
• Описано, чего агенту делать нельзя

Уровень 2 — контекст

• Сгенерированные артефакты исключены из чтения агентом
• Настроен инструмент навигации по коду
• Мёртвый код удалён из активных директорий
• Публичные контракты описаны машиночитаемо (OpenAPI/схемы событий)

Уровень 3 — процесс

• OpenSpec установлен, openspec/config.yaml заполнен проектным контекстом
• Настроены rules для артефактов
• Валидация спецификаций включена в CI
• Телеметрия настроена согласно политике компании
• Назначен владелец файлов инструкций

Часть 6Реализация: как работает разработчик

6.1Принцип

Спецификация — задание. Тесты — приёмка. Агент — исполнитель. Разработчик — тот, кто отвечает за результат.

Разработчик не является оператором генератора кода. Он отвечает за то, что реализация соответствует спецификации и что это доказано. Всё, что не доказано проверкой, считается несделанным.

6.2Цикл работы

Шаг 1. Прочитать спецификацию целиком

До запуска агента. Полностью: proposal.md, все файлы specs/, design.md, tasks.md. Это 10–15 минут, которые окупаются полностью.

По ходу чтения отметить:

• Что непонятно или допускает два толкования.
• Где спецификация расходится с известным вам устройством системы.
• Какие сценарии потребуют нетривиальных тестов.

Если непонятного больше двух пунктов — не начинать. Сформулировать конкретные вопросы и вернуть их автору спецификации — аналитику. Техлида привлекать точечно, только если вопрос касается архитектурного решения, а не формулировки требования (§2.3). Стоимость вопроса до начала работы — минуты; после — переделка.

Шаг 2. Уточнить декомпозицию

tasks.md уже создан агентом на этапе Спецификации вместе с аналитиком (§3.4) — здесь разработчик его проверяет и дорабатывает, а не пишет с нуля. Проверить tasks.md:

• Каждая задача завершается за один заход.
• Каждая задача содержит явный способ проверки.
• Порядок соответствует зависимостям.
• Каждый сценарий спецификации покрыт хотя бы одной задачей.

Правки в декомпозицию вносить до старта.

Шаг 3. Запустить реализацию

/opsx:apply <change-name>

Агент читает все артефакты изменения, идёт по задачам и отмечает выполненные.

Шаг 4. Вести сессию

Шаг 5. Обеспечить прослеживаемость сценариев

Каждый сценарий спецификации должен иметь соответствующий тест, и связь должна быть видна без объяснений.

Конвенция именования: имя теста содержит имя требования и имя сценария.

describe('Requirement: Ограниченное расписание ретраев', () => {
  it('Scenario: Успех со второй попытки', async () => { /* ... */ });
  it('Scenario: Все повторы исчерпаны', async () => { /* ... */ });
});

Это даёт три вещи: ревьюер видит покрытие сценариев за секунды; при падении теста сразу понятно, какое требование нарушено; проверить полноту покрытия можно поиском по именам.

Шаг 6. Самопроверка перед PR

Обязательный чеклист. PR, открытый без его выполнения, возвращается без рассмотрения.

• Полная проверка проекта зелёная локально
• Каждый сценарий спецификации имеет тест с соответствующим именем
• Негативные сценарии реализованы, а не только успешный путь
• Нефункциональные требования выполнены и проверены
• Изменения публичных контрактов соответствуют спецификации дословно
• Все задачи в tasks.md отмечены выполненными
• В diff нет ничего, что не следует из спецификации и задач
• Новых зависимостей нет, либо они согласованы
• Комментарии-заглушки, отладочный вывод и закомментированный код удалены
• Diff прочитан целиком собственными глазами

Пункт «в diff нет ничего лишнего» — ключевой. Типичное поведение агента — попутно «улучшить» соседний код. Это расширяет объём ревью, увеличивает риск и не имеет отношения к задаче. Лишнее удаляется до открытия PR.

6.3Что делать при расхождении

Общее правило: любое расхождение фиксируется в артефактах, а не разрешается в голове разработчика. Иначе спецификация перестаёт соответствовать системе и весь подход теряет смысл.

Часть 7Контроль качества и управление результатом

Ревью — не построчный поиск случайных ошибок, а система проверок, спроектированная так, чтобы дефицитное внимание человека тратилось только там, где оно незаменимо.

Чек-листы этой Части не рассчитаны на то, что их будут держать в голове или сверяться с документом на каждый PR — так они не проживут и месяца под давлением сроков. Они рассчитаны на то, чтобы стать шаблоном PR в GitHub (.github/pull_request_template.md) и обязательными статус-проверками в CI (§7.6): тогда чек-лист не требует дисциплины, он просто есть на экране в момент, когда PR открывается.

7.1Двухгейтовая модель контроля

Процесс управляется ровно в двух точках, и они устроены по-разному.

Гейт 1 дешевле и мощнее Гейта 2: он останавливает неверную работу до того, как она написана. Поэтому планка Гейта 1 (§7.2) — первый и самый дешёвый из четырёх рычагов техлида (§2.4). Всё в этой Части описывает, как эти два гейта работают на практике и что происходит, когда одного ревью недостаточно.

7.2Гейт 1: на что смотрит техлид

Definition of Ready (§4.5) — то, что аналитик проверяет сам перед подачей. Гейт 1 — это суждение техлида поверх пройденного DoR; проверяются вещи, которые нельзя свести к чеклисту.

• DoR (§4.5) пройден полностью — иначе ревью не начинается, спецификация возвращается без содержательного разбора.
• Это вообще нужно делать: соответствует ли объём инициативе ПМ, нет ли более простого решения той же проблемы.
• Решение о необходимости спецификации (§1.3) принято верно: не переусложнено для мелкого изменения, не занижено для изменения контракта.
• Спецификация не противоречит уже действующим требованиям затрагиваемых способностей и не дублирует их.
• Каждый сценарий проверяем: по формулировке понятно, каким тестом он будет закрыт.
• Декомпозиция в tasks.md реалистична: ни одна задача не скрывает в себе отдельную спецификацию.
• Для сквозных изменений design.md действительно отвечает на вопрос «почему так», а не пересказывает proposal.md другими словами.
• Предварительно виден риск-тир будущей реализации (§7.4) — это определяет, насколько тщательным будет Гейт 2.

Результат фиксируется по таблице исходов §3.5. Возврат с замечаниями — рабочий, ожидаемый исход, а не отказ довериться аналитику: цель гейта — поймать расхождение здесь, а не после реализации.

7.3Гейт 2: ревью кода агента

Ревью агентного PR отличается от ревью человеческого не по глубине, а по тому, с чего оно начинается: с проверки, что PR вообще годен к чтению.

Проход 0 — вход в очередь (автоматический)

PR, не прошедший проход 0, не выносится на ревью человека — CI возвращает его автору.

• Объём укладывается в лимит тира (§7.4, §7.5) либо помечен исключением с обоснованием от человека.
• У PR одна цель: фикс, фича, рефакторинг, документация или тесты — не смесь.
• Есть заявление о намерении: что делается, почему так, что сознательно не сделано, что вне охвата.
• Указана ссылка на спецификацию или задачу (путь к openspec/changes/<name>/ или ключ Jira).
• Приложено доказательство исполнения: не «тесты проходят», а фактический вывод команды или тестов.
• Все автоматические проверки зелёные (§7.6).
• Проведено предревью агентом в свежем контексте, не писавшим этот код; замечания закрыты или явно отклонены с причиной.
• Указано происхождение: какая модель, по какой спецификации; подтверждено отсутствие флагов обхода разрешений.

Проход 1 — каждый PR, любой тир

Намерение и охват

• Это вообще нужно делать, и делает ли diff ровно то, что заявлено в намерении — без побочного «заодно улучшить» соседний код.
• Не изменено и не удалено существующее поведение, которое задача не просила менять.

Тесты

• Не удалены, не пропущены и не ослаблены существующие тесты.
• Каждый новый тест реально падает, если сломать проверяемое поведение (не мок вместо поведения), и на каждый сценарий есть негативный тест.

Слабые места агентной реализации

• Граничные значения (пусто, ноль, максимум, повтор, параллельный вызов) и ошибки не проглатываются широким catch.
• Новое разделяемое состояние проверено на гонки; миграции данных обратимы.

Зависимости и переиспользование

• Каждая новая зависимость названа и обоснована; дифф лок-файла прочитан, а не пролистан.
• В репозитории не появилась вторая реализация уже существующей функциональности без причины.

Готовность к продакшну

• В коде, тестах, фикстурах и логах нет секретов, ключей и реальных данных клиентов; значения по умолчанию безопасны.
• Изменение откатывается одним действием либо скрыто за флагом; отказ будет виден в существующих дашбордах и алёртах.
• Если изменение касается агента, инструмента, MCP или хука — соблюдены правила §7.8 (Правило двух, отсутствие флагов обхода разрешений).

Проход 2 — дополнительно для Тира 1 и Тира 2

• Построчное чтение критичного пути (авторизация, деньги, персональные данные, миграции, криптография) — без исключений.
• Сверка покрытия: каждый сценарий спецификации имеет именованный тест (конвенция §6.2, шаг 5); сценарий без теста — блокирующее замечание.
• Для изменённой бизнес-логики зафиксированы инварианты и есть хотя бы один негативный тест на каждый.
• Запущен второй, независимо устроенный AI-ревьюер — как дополнительный сенсор, а не как вердикт.
• Человеком зафиксирована дельта модели угроз: какую новую возможность получает потенциальный злоумышленник.
• На PR указан именованный владелец, к которому обращаются в случае инцидента.

Дисциплина ревьюера

Ориентир по темпу: если ревью идёт быстрее 500 строк в час — это не ревью, а подпись; при такой скорости PR стоит разбить или отложить до момента, когда на него есть время. Дальше — три правила, которые реально стоит соблюдать:

• Ответ в течение одного рабочего дня; если глубокое ревью сегодня невозможно — сообщить об этом сегодня же.
• Критерий одобрения — «определённо улучшает общее состояние кода», а не «идеально». Необязательные замечания помечаются как Nit: и не блокируют мерж.
• Каждое замечание ревью, поймавшее реальный дефект, в течение спринта превращается в правило (CLAUDE.md, скилл, линт-правило) или проверку (тест, CI-чек). Замечание, не изменившее контур проверок, — дефект, который будет оплачен повторно.

7.4Риск-тиринг изменений

Тир назначается по цене ошибки, а не по тому, кто автор — человек или агент. Авторство меняет требуемые доказательства, а не тир.

Шаг 1 — назначить тир по старшему совпавшему признаку

Тир 1 · критический Пишет агент под особо точной постановкой задачи; обязательно построчное ревью человеком без исключений и без сэмплирования. Для узкого класса случаев внутри Тира 1 (шаг 3 ниже) — пишет человек. Любое из:

• Логика аутентификации, авторизации, сессий, изоляции между мерчантами/тенантами.
• Движение денег: платежи, выплаты, балансы, реестры, ценообразование, возвраты, комиссии.
• Криптография, управление ключами, хранение и ротация секретов.
• Необратимые операции с данными: разрушающая миграция, удаление, бэкфилл поверх продакшн-данных.
• Новый способ обработки регулируемых данных (персональные данные, платёжные реквизиты, финансовая отчётность).
• Изменение модели прав агента, инструмента, MCP-сервера, скилла или хука.
• Изменение самого CI/CD, релизного процесса или гейтов деплоя.
• Изменение публичного контракта API или протокола, потребляемого внешними сторонами.
• Радиус поражения — «все мерчанты» или «все пользователи».

Тир 2 · высокий Пишет агент; построчно ревьюирует поимённо назначенный человек. Любое из:

• Основная бизнес-логика на клиентском пути.
• Общие библиотеки или внутренние фреймворки, используемые тремя и более сервисами.
• Обратимые изменения схемы данных; логика конкурентности, очередей, ретраев, идемпотентности, rate limiting.
• Границы интеграции со сторонним провайдером; добавление новой runtime-зависимости.
• Diff (без учёта тестов, §7.5) превышает 600 строк или 12 файлов, либо тесты были удалены/ослаблены в рамках PR, либо изменение — повторная подача после отката или инцидента.

Тир 3 · стандартный Пишет и ревьюирует агент; предревью агентом обязательно; человек проверяет обычной глубиной. Сюда попадает всё, что не относится к Тиру 1 или Тиру 2. Внутри тира одно исключение: изменения без влияния на прод-поведение (документация, форматирование, dev-тулинг, ≤ 100 строк, полностью покрыто существующими автопроверками) не требуют персонального ревью каждого PR — человек выборочно сэмплирует не менее 1 из 10 таких PR в неделю.

Тир не стоит назначать вручную на глаз при каждом PR — это ровно то место, где диалог с документом расходится с реальным поведением команды под дедлайном. Признаки Тира 1–2 привязаны к путям в репозитории (payments/, auth/, .github/workflows/ и т. д.) и к размеру diff — оба параметра CI видит сам. Бот-лейбл с предложенным тиром на PR снимает тир-классификацию с человека почти полностью; техлид вручную корректирует только неочевидные случаи.

Шаг 2 — обязательные контроли по тирам

Шаг 3 — когда обычного делегирования агенту недостаточно

Обычный цикл (§6.2) — агент реализует по спецификации, разработчик проверяет — рассчитан на случаи, где требование можно сформулировать точно, а результат проверить тестом. Для части изменений этого мало: нужны не отказ от агента, а кратно более точная постановка задачи и построчное ревью без сэмплирования, — это верно, если хотя бы одно:

1. Критерий приёмки невозможно сформулировать настолько точно, чтобы его протестировать. Если тест-провал написать нельзя, результат нельзя доказать — разработчик формулирует и проверяет эту часть особенно тщательно.
2. Изменение — это решение, а не реализация: выбор модели данных, контракта API, гарантии консистентности, зависимости, архитектурной границы. Решение принимает и фиксирует разработчик; агент реализует уже принятое решение, а не предлагает своё.
3. Правильный ответ зависит от недокументированного институционального контекста: прошлый инцидент, обязательство перед клиентом, регуляторная трактовка, ещё не оформленный отказ от поддержки. Этот контекст нужно явно выгрузить в задачу — агент не восстановит то, чего не было написано.
4. Задача — дверь в одну сторону: публичный API, который нельзя отозвать, необратимая миграция, схема, на которой построятся другие команды. Построчное ревью здесь обязательно, без исключений по тиру.
5. Уже отклонены две попытки агента. Два проваленных исправления означают, что неверен контекст задачи, а не код: разработчик переформулирует её с максимальной точностью и фиксирует вывод как новое правило.
6. Радиус поражения превышает возможность отката в рамках SLA на инцидент.

Когда не хватает и этого. В узком классе случаев — там, где тонко неверный ответ выглядит валидным и не будет пойман никаким ревью (предикаты авторизации, арифметика реестра, выбор параметров криптографии), — разработчик пишет эту часть сам. Это исключение, а не типовой режим: для остальных перечисленных выше случаев достаточно резко повысить точность постановки задачи и глубину собственного ревью, оставаясь в обычном цикле с агентом.

7.5Политика размера PR

Ограничение размера — самый дешёвый из всех контролей: он предотвращает проблему, а не находит её.

• Целевой диапазон: 200–600 изменённых строк, ≤ 8 файлов. Это объём, который ревьюер способен прочитать вдумчиво за 30–60 минут.
• Жёсткий предел: 900 строк или 15 файлов. Выше — PR автоматически помечается как избыточный, поднимается на один риск-тир и требует подписанного человеком исключения с объяснением, почему его нельзя разбить.
• Абсолютный потолок: 2000 строк. Выше бот помечает PR предупреждающей меткой и комментарием с требованием разбить его на последовательность связанных PR. На период миграции это предупреждение, а не автозакрытие — переход на автоматическое закрытие на потолке решается техлидом отдельно, после того как команда обкатает процесс.
• Строки в сгенерированных, вендорных, лок-файлах и тестах не входят в подсчёт — тесты не должны быть причиной, по которой PR упирается в лимит. Диф лок-файлов и тестов при этом остаётся обязательным пунктом ревью.
• Лимит применяется в трёх точках, а не в одной: в инструкциях агенту на этапе декомпозиции (tasks.md формируется так, чтобы каждая задача укладывалась в один поставляемый PR); на открытии PR; как проверка в CI на каждом PR (технически блокирует мерж там, где включён branch protection — см. §7.6).
• Разбиение крупного изменения на последовательность зависимых PR (stacked PRs) и разработка за feature-флагами — рекомендуемая практика снижения размера единицы ревью. Это не отменяет лимит, а даёт способ его соблюдать без сокращения объёма работы.

7.6Автоматические гейты в CI

Автоматические проверки — второй рычаг техлида (§2.4): они определяют, что вообще допускается к чтению человеком. Ручное ревью начинается только после того, как эти проверки зелёные.

Обязательный минимум:

• Обязательные статус-проверки: сборка, типизация, линт, модульные и интеграционные тесты, порог покрытия.
• Валидация спецификаций (openspec validate --strict) для любого PR, содержащего openspec/changes/.
• Статический анализ безопасности (SAST) и сканирование секретов.
• Проверка политики зависимостей и лицензий; блокировка постинсталл-скриптов новых пакетов.
• Проверка архитектурных границ (запрещённые импорты между модулями), если такая граница определена.

Пока DevOps не включил branch protection: сброс устаревших одобрений при новом push, обязательное разрешение всех обсуждений перед мержем, запрет обхода правил веткозащиты вплоть до администраторов — это единственная мера, которая делает мерж без ревью технически невозможным, а не просто нежелательным. Без неё все пункты выше запускаются и видны в PR, но не блокируют мерж технически — это компенсируется процессной дисциплиной: красный статус проверки — блокирующее замечание на Гейте 2 (проход 0, §7.3), а не техническое препятствие.

Принцип проектирования проверок: каждая проверка относится к одной из двух категорий — guide (направляющая, действует до того, как агент напишет код: инструкции, шаблоны, ограничения прав) или sensor (проверяющая, действует после: тест, линт, сканер). Sensor должен быть достаточно быстрым и дешёвым, чтобы запускаться на каждое изменение. Задача техлида — проектировать эту систему проверок целиком, а не заменять её собственным построчным чтением.

Где выполняются агентные проверки. Предревью в свежем контексте (§7.3, проход 0) и второй независимый AI-ревьюер (§7.4) требуют суждения, а не сравнения с образцом, но остаются автоматической проверкой: неинтерактивный запуск Claude Code отдельным job'ом в CI на каждое открытие и обновление PR, в сессии без памяти о написанном коде. Находки публикуются как комментарии на PR до начала ревью человеком — это техническая реализация предревью и второго AI-ревьюера, а не замена самих Гейтов 1 и 2.

Правило двух (§7.8) распространяется и на этот job: агент читает недоверенный diff и публикует комментарий — уже два свойства из трёх, поэтому доступ к остальному репозиторию и секретам ограничивается минимально необходимым для чтения кода и публикации результата.

7.7Масштабирование контроля при росте объёма кода

Агент производит код быстрее, чем человек успевает его прочитать, и разрыв растёт вместе с объёмом — более способная модель его не закроет. «Больше ревьюеров» не масштабируется: их число растёт медленнее объёма кода. «Строже ревью каждого PR» не снижает число дефектов — только откладывает поставку. Рабочий ответ — последовательное применение четырёх рычагов техлида (§2.4) в порядке их стоимости:

1. Планка Гейта 1 (§7.2) остаётся первой линией независимо от объёма. Её стоимость не растёт с объёмом реализации, потому что она применяется к спецификации, а не к коду.
2. Автоматические гейты (§7.6) берут на себя всё, что можно проверить механически. Каждое ручное замечание, повторившееся дважды, переводится в правило или проверку (§7.3) — это единственный способ, которым ёмкость ревью растёт быстрее объёма кода.
3. Риск-тиринг (§7.4) перераспределяет оставшееся внимание туда, где ошибка дорога. При росте объёма доля PR Тира 3 растёт быстрее доли Тира 1–2 — это ожидаемо и означает, что система работает, а не что контроль ослаб.
4. Правила агентной работы (§7.8) снижают вероятность дефекта на входе, до того как он вообще станет предметом ревью.

Роль техлида смещается вместе с объёмом — от построчного чтения к проектированию: какие сенсоры нужны, где границы тиров, что фиксируется в правилах для агента. Техлид, который продолжает читать всё построчно при растущем объёме, становится узким местом, а не гарантом качества.

Сигналы разбалансировки: время PR в ревью растёт быстрее числа PR в неделю; доля PR, смерженных без содержательного ревью, растёт; число инцидентов на PR растёт быстрее числа PR. Любой из них — повод пересмотреть тиры и автоматические проверки, а не требовать от техлида читать быстрее.

7.8Безопасность агентной разработки

Агент, работающий в репозитории, одновременно способен читать приватные данные (код, секреты, историю), обрабатывать недоверенный контент (текст задачи, содержимое веб-страниц, вывод внешних инструментов) и совершать внешние действия (коммит, PR, сетевой запрос). Сочетание всех трёх свойств в одной сессии — открытая поверхность для атаки через внедрение инструкций в обрабатываемый текст.

Правило двух: в рамках одной сессии агента допускается не более двух из трёх свойств — обработка недоверенного ввода; доступ к чувствительным данным или системам; изменение состояния или внешняя коммуникация (коммит, PR, сетевой запрос, отправка сообщения).

Если задаче по своей природе требуются все три свойства без возможности начать новую сессию со свежим контекстом, она не выполняется агентом автономно — обязательно подтверждение человеком на каждом внешнем действии.

Обязательные технические меры:

• Флаг обхода разрешений Claude Code (--dangerously-skip-permissions) запрещён в любом окружении с реальными учётными данными — в CI, на серверах, в скриптах. Его присутствие в файлах репозитория (workflow, скрипты, конфигурация) обнаруживается обычной проверкой содержимого на PR и блокирует мерж. Использование флага в локальной сессии разработчика технически не проверяется — это его зона контроля; вместо сканирования разработчик подтверждает его отсутствие пунктом в шаблоне PR, как и происхождение реализации (§7.3, проход 0).
• Пока права агента не разграничены инфраструктурно (например, через MCP-серверы с минимальными правами, §5.5), соблюдение правила двух — обязанность разработчика: перед стартом сессии он явно проверяет, какие из трёх свойств она затрагивает, и не запускает сессию, в которой сходятся все три. Когда развести невозможно, это не смягчает требование — каждое внешнее действие подтверждается человеком вручную, как описано выше.
• Недоверенный текст (содержимое задачи, результат веб-запроса, пользовательский ввод) никогда не передаётся агенту без явно обозначенной границы, отделяющей его от инструкций.
• Секреты и учётные данные хранятся вне зоны чтения агента по умолчанию; доступ к ним — по явному исключению, а не потому что агент технически может дотянуться до файла.
• Учётные записи и токены для облачных сервисов (включая CI-инфраструктуру) не хранятся в открытом виде в файлах конфигурации репозитория — только через переменные окружения или менеджер секретов CI.

Что это не отменяет: ответственность за проверку предлагаемых изменений перед одобрением остаётся на человеке при любом уровне автоматизации разрешений. Ни один инструмент защиты от внедрения инструкций не даёт полной гарантии — это довод в пользу Правила двух и минимизации прав, а не аргумент против агентной разработки.

Ориентир для классификации рисков: для случаев, где агент обрабатывает контент, инструменты или внешние подключения, применяется актуальная редакция OWASP Top 10 for LLM Applications — готовый, регулярно обновляемый чеклист классов риска.

7.9Эскалация

Общий принцип эскалации: любое разногласие разрешается на уровне артефакта (спецификация, правило, автоматическая проверка), а не устным решением в моменте. Устное решение, не зафиксированное в артефакте, будет расходиться с системой при следующем похожем случае.

AI-NATIVE-SDD-REFERENCE.MD

Инструменты и справочник

Дочерний документ регламента. Ссылки без пометки — разделы этого файла; ссылки «регламент, §X» — основной документ.

§1Инструменты по ролям

Вне этого списка — предмет отдельной оценки в пилоте, не рекомендация этого документа: отдельные AI-ревьюеры pull request'ов (регламент, §7.3), MCP-серверы сверх минимально необходимых.

Специфичные для подхода команды у разработчика и техлида — это не отдельный инструмент, а две группы команд поверх обычного git/GitHub: слэш-команды и CLI OpenSpec (§6 этого документа) и команды git submodule для связи спек-репозитория с кодовым (регламент, §5.6). Всё остальное в их рабочем месте — обычный стек разработки, ничего дополнительного не требуется.

Пример конфигурации: агентные проверки в CI

Механизм — официальный anthropics/claude-code-action (GitHub Action), настраиваемый один раз в .github/workflows/.

Триггеры:

Пример workflow (предревью на каждый PR):

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Что настраивается:

• Секрет ANTHROPIC_API_KEY (или CLAUDE_CODE_OAUTH_TOKEN для подписки) в настройках репозитория.
• Права workflow — только contents: read, pull-requests: read, issues: read; без прав на запись в код или деплой (согласуется с Правилом двух, регламент §7.8).
• --allowedTools — какие действия агенту разрешены сверх чтения; здесь только публикация inline-комментария.
• Второй, независимый AI-ревьюер для Тира 1–2 (регламент, §7.4) — второй такой job в том же файле, с другим prompt или --model.

Вне CI: тот же агент запускается неинтерактивно локально или в любом другом пайплайне командой claude -p "<промпт>" --output-format json.

Пример конфигурации: бот-лейбл риск-тира

Из признаков Тира 1–2 (регламент, §7.4, шаг 1) механически проверяются только два: путь изменённых файлов и размер diff. Остальные признаки (изменение контракта API, новая бизнес-логика и т. п.) требуют суждения — бот их не видит, тир по ним поднимает техлид вручную.

name: Risk Tier Label
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  tier:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const files = await github.paginate(github.rest.pulls.listFiles, {
              owner: context.repo.owner, repo: context.repo.repo, pull_number: pr.number
            });
            const paths = files.map(f => f.filename);
            const isTestFile = f => /(^|\/)(tests?|__tests__|spec)\//i.test(f) || /\.(test|spec)\.[jt]sx?$/i.test(f);

            const tier1Paths = [/^payments\//, /^auth\//, /^\.github\/workflows\//];
            const isTier1 = paths.some(f => tier1Paths.some(p => p.test(f)));
            const changedLines = files
              .filter(f => !isTestFile(f.filename))
              .reduce((sum, f) => sum + f.additions + f.deletions, 0);
            const isTier2 = changedLines > 600 || paths.length > 12;

            const tier = isTier1 ? 'tier-1' : (isTier2 ? 'tier-2' : 'tier-3');
            await github.rest.issues.addLabels({
              owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, labels: [tier]
            });

Что настраивается:

• Список путей Тира 1 (tier1Paths) — под конкретный репозиторий, из признаков §7.4, шаг 1.
• Пороги Тира 2 — те же числа, что в §7.4 (диф без тестов больше 600 строк или 12 файлов).
• Метка tier-N — сигнал техлиду для глубины ревью (§7.3, §7.4), а не техническое ограничение: сама по себе она не блокирует мерж, только маркирует PR.

Пример конфигурации: контроль размера PR

name: PR Size Gate
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  size:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: write
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const files = await github.paginate(github.rest.pulls.listFiles, {
              owner: context.repo.owner, repo: context.repo.repo, pull_number: pr.number
            });
            const isTestFile = f => /(^|\/)(tests?|__tests__|spec)\//i.test(f) || /\.(test|spec)\.[jt]sx?$/i.test(f);
            const changed = files
              .filter(f => !isTestFile(f.filename))
              .reduce((sum, f) => sum + f.additions + f.deletions, 0);

            if (changed > 2000) {
              await github.rest.issues.createComment({
                owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number,
                body: 'PR превышает абсолютный потолок в 2000 строк без учёта тестов (регламент, §7.5). Разбейте изменение на последовательность связанных PR. На период миграции это предупреждение — PR не закрывается автоматически.'
              });
              await github.rest.issues.addLabels({
                owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, labels: ['oversized-ceiling']
              });
            } else if (changed > 900 || pr.changed_files > 15) {
              await github.rest.issues.addLabels({
                owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, labels: ['oversized']
              });
            }

Что настраивается:

• Пороги — те же числа, что в §7.5 (целевой диапазон 200–600 строк, жёсткий предел 900 строк/15 файлов, абсолютный потолок 2000 строк; тесты, сгенерированные, вендорные и лок-файлы не учитываются).
• Метка oversized — сигнал техлиду поднять PR на риск-тир и потребовать подписанное исключение (§7.5); дальнейшее действие — вручную.
• Автозакрытие на абсолютном потолке отключено на период миграции: вместо него бот ставит метку oversized-ceiling и оставляет комментарий. Возврат к автозакрытию — решение техлида после того, как процесс обкатан.

§2Рабочее место аналитика

Аналитик не пишет код и не устанавливает инструменты разработчика. У его работы два разных режима: агентная работа с Claude Code на этапах Explore и Спецификация (регламент, §3.3, §3.4) и обычное редактирование Markdown-файлов через Pull Request.

Доступ — только к спек-репозиторию (регламент, §5.6), не к кодовому. Это снимает риск утечки кода через скомпрометированную или избыточно широкую учётную запись. Доступа на чтение к спек-репозиторию достаточно — полноценная разработческая учётная запись не требуется.

Агентная работа: Claude Code on the web

Этапы 1 и 2 (§3.3 Explore, §3.4 Спецификация) выполняются в сессии агента — аналитик запускает /opsx:explore и /opsx:propose "<описание>" в браузере, через Claude Code on the web (claude.ai/code), тем же GitHub-аккаунтом, что и веб-редактор.

• GitHub-аккаунт аналитика авторизуется через Claude GitHub App.
• Сессия выполняется в изолированной облачной среде.
• Доступные репозитории в сессии — те же, что и у GitHub-аккаунта (§5.6).
• В сессии доступны просмотр diff, инлайн-комментарии к черновику и создание PR.

Редактирование текста без агента

Для правок уже существующего change (доработка после Гейта 1, правка формулировки) агент не обязателен — подходит обычный текстовый редактор:

GitHub Desktop и полноценный VS Code в рабочее место аналитика не входят — оба требуют отдельно установленного редактора для правки текста.

§3Что оценивать в пилоте

• Достаточно ли аналитику GitHub веб-редактора для точечных правок или типичный change с самого начала требует github.dev.
• Даёт ли AI-ревьюер pull request'ов измеримое сокращение времени ревью Гейта 2 без роста пропущенных дефектов — если нет, не подключается на постоянной основе.

§4Полный пример change

Пример ниже проверен реальным прогоном openspec validate --strict на версии 1.12.0 и корректно сливается в основную спецификацию при архивации. Используйте его как эталон формата.

proposal.md

## Why

Выплаты, упавшие из-за временной недоступности провайдера, помечаются как
`FAILED` и требуют ручной переотправки поддержкой. Это около 30 ручных
переотправок в неделю и задержка расчётов с мерчантами.

## What Changes

- Автоматический ретрай выплат, упавших с временной ошибкой провайдера.
- Новое состояние `RETRY_SCHEDULED` в жизненном цикле выплаты.
- Новое событие `payout.retry_scheduled`, позволяющее мерчанту отличить
  временный отказ от окончательного.
- **BREAKING** `payout.failed` больше не отправляется при первой временной
  ошибке — только после исчерпания ретраев.

## Capabilities

### New Capabilities
- `payout-retry`: автоматическая переотправка выплат, упавших с временной
  ошибкой провайдера.

### Modified Capabilities
- `payout-webhooks`: изменение условий отправки событий при временном отказе.

## Impact

- `apps/payout-service`: машина состояний, планировщик, классификация ошибок.
- `packages/common`: перечисление статусов выплаты.
- Публичный контракт вебхуков, документация для мерчантов.

specs/payout-retry/spec.md

ADDED Requirements

design.md

## Context

Отправка выплаты — синхронный вызов адаптера провайдера. В `apps/payout-service`
нет инфраструктуры планирования; сервис уже использует очередь на Redis
для входящих запросов. Мотивация — см. proposal.md, раздел Why.

## Goals / Non-Goals

**Goals:**
- Повторять отправку, не удерживая воркер между попытками.
- Сохранить гарантию ровно одного перевода.

**Non-Goals:**
- Повтор выплат, упавших на валидации до обращения к провайдеру.
- Переключение между провайдерами при отказе.

## Decisions

- Отложенная задача в очереди на каждую попытку вместо таймера в процессе:
  сервис работает в нескольких репликах, таймеры теряются при рестарте.
  Рассмотренная альтернатива — периодический обход строк в состоянии
  `RETRY_SCHEDULED` — отклонена из-за постоянной нагрузки на базу.
- Классификация ошибок в адаптере провайдера, а не в машине состояний:
  новый провайдер добавляет своё отображение ошибок, не трогая общую логику.

## Risks / Trade-offs

- Провайдер принял выплату, но ответил таймаутом → возможен повтор.
  Митигация: требование идемпотентности делает повтор безопасным.
- Задержки 1/5/25 минут увеличивают худший срок расчёта примерно на 31 минуту.
  Митигация: событие `payout.retry_scheduled` даёт мерчанту точный статус.

## Migration Plan

Выкатывается под флагом `payout.retry.enabled`, включается сначала для
внутренних мерчантов, затем для всех через неделю без инцидентов.
Выключение флага возвращает прежнее поведение без миграции данных.

tasks.md

## 1. Модель предметной области

- [ ] 1.1 Добавить `RETRY_SCHEDULED` в перечисление статусов выплаты
      и убедиться, что юнит-тесты машины состояний принимают новые переходы
- [ ] 1.2 Добавить счётчик попыток и время следующей попытки в сущность
      выплаты и убедиться, что миграция применяется на чистой базе

## 2. Логика повторов

- [ ] 2.1 Реализовать классификацию временных и окончательных ошибок
      в адаптере провайдера и убедиться, что оба сценария требования
      о классификации проходят
- [ ] 2.2 Планировать отложенные задачи на 1/5/25 минут и убедиться,
      что сценарии требования об ограниченном расписании проходят
- [ ] 2.3 Переиспользовать исходный ключ идемпотентности во всех повторах
      и убедиться, что сценарий идемпотентности проходит на песочнице провайдера

## 3. Контракт

- [ ] 3.1 Отправлять `payout.retry_scheduled` и не отправлять `payout.failed`
      до исчерпания повторов; убедиться, что контрактные тесты вебхуков проходят
- [ ] 3.2 Обновить документацию вебхуков для мерчантов и убедиться,
      что опубликованная схема совпадает с отправляемым payload

Обратите внимание на формат задач: каждая задача содержит способ проверки прямо в тексте. Это не украшение — агент использует эту формулировку как критерий завершения задачи, а разработчик и ревьюер как критерий приёмки.

§5Шаблоны артефактов (пустые, для копирования)

proposal.md

## Why

<!-- Проблема, которую решает изменение. Почему сейчас. -->

## What Changes

<!-- Что именно меняется. Конкретно про новые/изменённые/удалённые способности. -->

## Capabilities

### New Capabilities
<!-- Новые способности. kebab-case. Каждая создаёт specs/<capability-path>/spec.md -->
- `<capability-path>`: <краткое описание>

### Modified Capabilities
<!-- Существующие способности, у которых меняются ТРЕБОВАНИЯ, а не только реализация.
     Пусто, если требования не меняются. Change без единой затронутой способности
     помечается skip_specs: true — не изобретайте требование ради валидации. -->
- `<existing-capability-path>`: <что меняется в требовании>

## Impact

<!-- Затронутый код, API, зависимости, системы -->

specs/<capability>/spec.md

## Purpose
<!-- Только для новой способности: 1-2 предложения, что она делает. Для существующей — удалить раздел. -->

## ADDED Requirements

### Requirement: <!-- имя требования -->
<!-- текст требования, с SHALL/MUST -->

#### Scenario: <!-- имя сценария -->
- **WHEN** <!-- условие -->
- **THEN** <!-- ожидаемый результат -->

design.md

## Context

<!-- Текущее состояние и ограничения. Не повторять мотивацию из proposal.md -->

## Goals / Non-Goals

**Goals:**
<!-- Чего достигает это решение -->

**Non-Goals:**
<!-- Что явно вне охвата -->

## Decisions

<!-- Ключевые решения, обоснование, рассмотренные альтернативы -->

## Risks / Trade-offs

<!-- Известные риски и компромиссы -->

tasks.md

## 1. <!-- Название группы задач -->

- [ ] 1.1 <!-- Описание задачи, включая способ проверки -->
- [ ] 1.2 <!-- Описание задачи -->

## 2. <!-- Название группы задач -->

- [ ] 2.1 <!-- Описание задачи -->

§6Справочник команд OpenSpec

Слэш-команды жизненного цикла (используются в регламенте):

Ключевые команды CLI:

Важно: отдельной команды openspec diff не существует — используется show --diff. Полный список команд и флагов — openspec --help; версия и точный набор команд могут измениться между релизами — сверяйте с --help установленной версии.

§7Глоссарий

AI-NATIVE-SDD-MIGRATION-PLAN.MD

План миграции

Дочерний документ регламента. Ссылки без пометки — разделы этого файла; ссылки «регламент, §X» — основной документ.

Переход происходит фазами с явным критерием на входе в каждую и явным критерием выхода. Ни одна фаза не форсируется административно — переход к следующей случается тогда, когда предыдущая доказала себя, а не по календарю.

§1Принципы

1. Пилот — не показательное выступление. Он проводится на реальной фиче с ощутимой ценностью для бизнеса, а не на синтетической задаче. Это сознательный компромисс: реальная фича даёт более высокий риск, но и единственно убедительное доказательство для остальной команды.
2. Практика не вводится директивно поверх незрелой инфраструктуры. Обязательное использование агентов и спецификаций до прохождения чеклиста готовности (регламент, §5.7) даёт результат «инструмент замедляет, а не ускоряет» (регламент, §5.1) и риск инцидента при недостаточном контроле прав агента (регламент, §7.8).
3. Расширение измеряется устойчивым добровольным использованием, а не процентом отчитавшихся о внедрении. Практика, которая держится только на личном давлении лидера пилота, не готова к масштабированию — это симптом, а не успех.
4. Confluence и Jira не отменяются одномоментно. Массовый перенос существующих требований — антипаттерн (регламент, §3.9); миграция идёт срезами, привязанными к активной работе (§7).
5. Каждая фаза даёт входной критерий следующей. Переход раньше срока без выполнения критерия входа переносит нерешённые проблемы фазы 0 или 1 на больший масштаб, где их дороже исправлять.

§2Фаза 0 — Подготовка (неделя 1)

Что происходит: репозиторий приводится к уровню «готов к агентам» (регламент, Часть 5): устанавливается OpenSpec, пишутся файлы инструкций для агентов, настраиваются обязательные автоматические проверки на ветке по умолчанию.

Роли: Техлид (A/R) — владелец подготовки; CTO (I) — уведомляется о готовности.

Артефакт на выходе: чеклист (регламент, §5.7), пройденный на ≥ 80 %, при этом все пункты уровня 0 выполнены без исключений.

Критерий входа в Фазу 1: чеклист пройден; выбраны пилотная команда и пилотная фича (см. §3).

§3Фаза 1 — Пилот (недели 2–3)

Что происходит: одна фича проходит полный флоу (регламент, §3.1–§3.9) от инициативы до архивации.

Роли: 1 ПМ, 1 аналитик, 1 техлид, 1–2 разработчика, QA — полный состав ролей (регламент, Часть 2). Роли работают в пилоте так же, как в RACI (регламент, §2.2): ПМ инициирует фичу и принимает результат по бизнес-критериям, участвует в Гейте 1 как Consulted; QA проводит приёмку по сценариям спецификации. CTO — Informed, подключается к разбору результатов на выходе фазы.

Артефакт на выходе: фича в продакшене; спецификация не разошлась с реализацией к моменту архивации; проведено ретро с участием всех ролей пилота.

Критерий входа в Фазу 2 — таблица Go/No-Go, §5.

§4Фаза 2 — Команда (недели 4–7)

Все новые фичи одного проекта проходят через флоу; ранее начатые задачи доигрываются по-прежнему, без принудительного перевода в середине работы. Работает вся команда проекта в штатных ролях (регламент, Часть 2).

Артефакт на выходе: ≥ 80 % новых изменений имеют утверждённую спецификацию до начала работы.

Сопротивление на этой фазе не всегда «страх нового процесса» — часть команды воспринимает смещение роли (от «пишу код» к «ставлю задачу, проверяю, оркестрирую агента») как смену профессиональной идентичности. Разговор с командой — про смещение объекта работы на проектирование и проверку, а не про обещание меньшей рутины при той же ответственности за результат.

Разворачивание на остальные репозитории компании — решение CTO и отдельный процесс за пределами этого документа, который описывает переход одного проекта.

§5Критерии Go/No-Go

Переход к следующей фазе — решение CTO по итогам разбора с техлидом пилота, зафиксированное явно, а не молчаливое продолжение по календарю.

§6Риски миграции и митигации

§7Что делать с существующим массивом Confluence и Jira

Правило по умолчанию — ничего не переносить массово (регламент, §3.9). Ниже — как это работает на практике при живой миграции.

Переносится срезами, привязанными к активной работе:

• Новые и активно дорабатываемые фичи с самого начала описываются в openspec/specs/, а не в Confluence.
• Уже стабильные, не меняющиеся части системы не трогаются, пока в них не понадобится реальное изменение.

Переносится в первую очередь, при первой возможности, независимо от активности:

• Architecture decision records (ADR) — независимо от возраста: в них зафиксирована причина решения.
• Документация к сервисам, которые прямо сейчас находятся в активной разработке.

Не переносится и остаётся в архиве Confluence:

• Страницы без активности за последний значительный период, без владельца, без входящих ссылок.
• Требования к коду, который не планируется менять в обозримом горизонте.

На каждый перенесённый раздел назначается владелец и фиксируется договорённость: при следующем значимом изменении затронутого кода обновляется спецификация в репозитории, а соответствующая страница Confluence, если она нужна для бизнес-контекста, помечается ссылкой на спецификацию, а не дублирует её (регламент, §3.9).

Jira не заменяется. Она остаётся системой учёта задач, приоритетов и сроков; меняется только то, что именно в ней перестаёт жить, — детальные требования к поведению системы переезжают в спецификацию, а задача в Jira ссылается на неё.