SDD AI-Native Регламент · Справочник · v2.0

AI-Native SDD · v2.0

SDD на OpenSpec

Регламент разработки через спецификации и AI-агентов. Составлен по практике проектов компании и практикам AI-native SDLC от Anthropic. Выберите роль в шапке — появятся разделы для неё.

Процесс поставки фичи — от задачи до приёмки

Задача
ПМ
→
Требования
Аналитик
→
Гейт 1
Техлид
→
Реализация
Разработчик
→
Ревью и мерж
Техлид, CI
→
Приёмка
QA

01

Регламент

Подход · Ответственность · Репозитории и доступы · Процесс по этапам · Требования · Ревью и CI · Тесты · Внедрение · Альтернативный вариант

02

Справочник

CI-связка · Конфигурации · Стандарт требований · Шаблоны · Jira · Команды

Часто нужно

AI-NATIVE SDD · РЕГЛАМЕНТ · v2.0

Регламент

Разработка через спецификации OpenSpec и агентов Claude Code

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

0Подход на одной странице

0.1Суть

  • Спецификация — задание для агента. Требования пишутся в формате OpenSpec в спек-репозитории. Агент Claude Code реализует их буквально, поэтому качество поставки определяется полнотой и корректностью требований до начала разработки.
  • Аналитик работает по коду. Его агент читает репозитории бизнес-логики, поэтому требования к бэкенду и фронтенду, HTML-прототипы и задачи пишутся сразу в одном изменении, а интеграция бэкенда и фронтенда согласуется до разработки.
  • Техлид отвечает за требования и архитектуру: утверждает или пишет изменение и техническое решение.
  • Разработчик реализует изменение с агентом. Целевой и самый эффективный режим — один разработчик делает и бэкенд, и фронтенд.
  • Каждый PR проходит CI, AI-ревью и security-ревью; одобряет PR техлид, уровень риска задаёт глубину его проверки.
  • CI держит спецификации синхронными с кодом: проверяет связь PR с изменением и архивирует изменение при мерже PR, который закрывает последнюю задачу.
ИнструментНазначение
OpenSpecФормат спецификаций и жизненный цикл изменения: CLI openspec, слэш-команды /opsx:*; пакет @fission-ai/openspec, MIT
Claude CodeАгент: разбор кода, требования, реализация, ревью
GitHub ActionsСвязка репозиториев, проверки PR, архивация
JiraЗадачи и статусы; ключ задачи в имени ветки связывает с ней коммиты, PR и мержи

0.2Процесс

Задача
ПМ
→
Требования
Аналитик
→
Гейт 1
Техлид
→
Реализация
Разработчик
→
Ревью и мерж
Техлид, CI
→
Приёмка
QA

Главная точка управления — Гейт 1: ошибка в требованиях исправляется правкой абзаца до того, как написан код. На ревью PR рутину проверяют CI и агенты, а техлид — рискованный код и архитектуру.

0.3Матрица ответственности

R выполняет A отвечает за результат и утверждает
#ЭтапПМАналитикТехлидРазработчикQADevOps
1Задача в JiraA/R
2Требования и Гейт 1RA
3design.mdA/R
4РеализацияA/R
5Ревью PRA/R
6ПриёмкаA/R
7Релиз, доступы, стендыA/R

Уровень риска PR определяет только глубину проверки техлида («Уровни риска»). Архивацию выполняет CI.

0.4Обязательные правила

  1. На продукт — один спек-репозиторий; репозитории бизнес-логики подключают его как git submodule, репозиторий ядра держит openspec/ у себя («Репозитории и доступы»).
  2. Аналитик и его агент читают репозитории бизнес-логики; доступа к ядру у них нет («Доступы»).
  3. Каждая фича — бизнесовая и техническая — идёт через спецификацию («Когда пишется спецификация»).
  4. Требования уходят на ревью полными; ревью требований — не больше двух итераций («Гейт 1 — ревью требований»).
  5. Ветка называется по ключу задачи Jira: feat/<KEY>-… (справочник: «Связь с Jira»).
  6. PR с кодом ссылается на изменение openspec/changes/<name> или имеет метку no-spec («PR и ревью»).
  7. PR с красным CI не мержится.
  8. Каждый PR проходит AI-ревью и security-ревью автора и одобрение техлида («Уровни риска»).
  9. Каждый сценарий спецификации проверяется до мержа: автотестом, а пока автотестов нет — разработчиком с агентом на локальном стенде («Тестирование»).
  10. Изменение архивирует только CI («Мерж и архивация»).

1Принципы

1.1Принципы

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

  1. Буквальность. Агент реализует то, что написано. Чего нет в требованиях, не будет в коде; неточное требование даст неточный код. Из каждого требования выводится проверка.
  2. Дельта. Изменение описывает только то, что меняется; при архивации CI вливает его в openspec/specs/. Поведение остальной системы агент читает из кода («Текущее состояние системы»).
  3. Один источник на каждый вид знания. Поведение — openspec/specs/ и код; схема API — OpenAPI из кода; термины — GLOSSARY.md; задачи и статусы — Jira. Дублирование запрещено.
  4. Синхронность через CI. Связь кода и спецификаций держат проверки PR и архивация в CI.
  5. Человек отвечает за результат. Агент пишет и проверяет, человек направляет и утверждает.

1.2Когда пишется спецификация

Тип работыСпецификацияАвтор
Новая функциональность; изменение API, событий, вебхуков, бизнес-правил, расчётов, прав доступаПолнаяАналитик
Техническая фича без изменения внешнего поведения: надёжность, производительность, наблюдаемость, хранение данных, CI и инфраструктураПолная, техническаяТехлид или разработчик
Багфикс, где спецификация была неверна или молчалаДельта на затронутые требованияАналитик или разработчик
Багфикс по действующей спецификации, рефакторинг без изменения поведения, обновление зависимостей, документация, back-mergeНет; PR с меткой no-spec—
Продакшен-инцидентФикс сразу; спецификация — в течение 2 рабочих дней, если поведение изменилосьРазработчик

2Репозитории и доступы

2.1Ядро и бизнес-логика

ЯдроБизнес-логика
Что содержитКомпоненты, критичные для безопасности средств и ключей: подпись, хранение ключей, криптографические и сетевые компоненты. Бизнес-правил продукта нетAPI продукта, бизнес-правила, интерфейсы: бэкенд, фронтенды
Где спецификацииopenspec/ в самом репозиторииОбщий спек-репозиторий продукта, подключён как submodule
Кто пишет спецификацииТехлид, архитектор, разработчикАналитик; технические — техлид, разработчик
Доступ аналитика и его агентаНетЧтение

Для требований достаточно репозиториев бизнес-логики: ядро взаимодействует с ними через контракты (очереди сообщений, API), которые описаны в коде бизнес-логики. Внешние системы со своим жизненным циклом ведут спецификации у себя.

2.2Один спек-репозиторий

Все репозитории бизнес-логики продукта используют один спек-репозиторий. Изменение, которое затрагивает бэкенд и фронтенд, — одно изменение с группами задач по репозиториям.

<product>-specs                 спек-репозиторий: openspec/specs, openspec/changes, GLOSSARY.md
  ▲ git submodule vendor/openspec-specs, запинен на коммит; openspec/ — симлинк на vendor/openspec-specs/openspec
  ├── <backend>                    бэкенд
  └── <frontend>                   фронтенд

Ядро — openspec/ в своём репозитории

Агент в кодовом репозитории видит спецификации как папку openspec/; слэш-команды /opsx:* работают в спек- и кодовом репозитории одинаково. Подключение — справочник: «Подключение кодового репозитория».

2.3Доступы

РепозиторийАналитикТехлид, архитекторРазработчикПМ, QA
Спек-репозиторийЗаписьЗаписьЗаписьЧтение
Бизнес-логикаЧтениеЗаписьЗапись—
Ядро—ЗаписьЗапись — участники ядра—

Доступы к репозиториям GitHub выдаёт DevOps.

2.4Текущее состояние системы

У каждого вида знания о текущем состоянии один источник, который обновляется вместе с кодом:

Что нужно знатьИсточникПочему не расходится с системой
Требования ко всему, что прошло через SDDopenspec/specs/CI вливает дельту при мерже кода
Поведение остальной системы: экраны, эндпоинты, статусы, праваКод; агент описывает блок по запросу и называет файлыКод — фактическое поведение
Регрессионные сценарииСценарии спецификаций и автотесты по нимАвтотест, разошедшийся с кодом, ломает CI
Причины решенийdesign.md в архиве измененийАрхив не меняется

Других описаний текущего состояния не ведётся. Исключение — документы для внешнего бизнеса и интеграций: они допускаются в Confluence как копия и обновляются по спецификациям.

2.5Если доступа к коду нет

Если ядро и бизнес-логика ещё в одном репозитории или аналитику по другой причине нельзя дать доступ к коду:

  • текущее состояние ведётся в спецификациях: одна capability на блок; каждое изменение блока дописывает его требования в openspec/specs/;
  • схема API автоматически копируется из кода в contracts/ спек-репозитория и всегда актуальна для интеграций (справочник: «Копия схемы API в спек-репозитории»);
  • вопросы, на которые нет ответа в спецификациях и контракте, аналитик задаёт тимлидам в разделе «Открытые вопросы» proposal.md, и на Гейт 1 изменение уходит с ответами.

Так устроен альтернативный вариант процесса.

3Процесс поставки фичи

3.1Задача в Jira

Кто
ПМ
Вход
Запрос стейкхолдера
Выход
Задача в Jira с критерием успеха

Задача содержит: проблему — что не работает или чего не хватает и у кого; ожидаемый эффект и критерий успеха; границы — что явно не входит; срочность. Ключ задачи (PROJ-123) используется в имени изменения и веток (справочник: «Связь с Jira»).

3.2Требования, прототипы, задачи

Кто
Аналитик с агентом
Вход
Задача в Jira
Выход
PR в develop спек-репозитория: proposal.md, specs/, prototypes/, tasks.md, прошедшие чек-лист перед ревью
  1. Ветка feat/<KEY>-<short> в спек-репозитории; сессия Claude Code с доступом к коду (справочник: «Инструменты по ролям»).
  2. Разбор: /opsx:explore. Агент описывает текущее поведение затронутых блоков по коду бэкенда и фронтенда и по openspec/specs/ — эндпоинты, статусы, права, экраны. Вопросы к ПМ и техлиду снимаются здесь, до текста требований.
  3. Изменение: /opsx:propose создаёт openspec/changes/<key>-<name>/. Аналитик доводит proposal.md и дельты требований для бэкенда и фронтенда по стандарту требований. Контракт между бэкендом и фронтендом — эндпоинты, поля, коды ошибок, права — описывается один раз для обеих сторон. design.md пишет техлид.
  4. Прототипы: HTML-прототипы экранов — в prototypes/ изменения («Прототипы и дизайн»).
  5. Задачи: агент формирует tasks.md — группы по репозиториям, способ проверки у каждой задачи, ссылки UI-задач на прототипы, последний раздел «Проверка после развёртывания».
  6. Проверка: аналитик и агент в новой сессии проходят чек-лист перед ревью.
  7. PR в develop спек-репозитория.

Техническую фичу по тому же процессу описывает техлид или разработчик. Изменение, которое написал техлид, Гейт 1 не проходит.

3.3Гейт 1 — ревью требований

Кто
Техлид; аналитик закрывает замечания
Вход
PR требований, прошедший чек-лист перед ревью
Выход
Требования утверждены — не больше 2 итераций

На Гейт 1 уходит только готовое изменение. Качество требований — ответственность аналитика: техлид утверждает решение, а не дописывает требования.

  • PR открывается, когда аналитик и агент прошли весь чек-лист перед ревью. Если пункт не выполнен, техлид возвращает PR без разбора — возврат считается итерацией.
  • В PR нет черновиков, «TBD», «уточню позже» и открытых вопросов: вопросы к ПМ и техлиду закрыты на разборе, до текста требований.
  • Итерация 1 — замечания техлида; аналитик закрывает каждое за один заход исправлением или ответом с причиной. Итерация 2 — финальная проверка и утверждение; новых тем в ней не появляется.
  • Третья итерация — признак сырого материала. ПМ, аналитик и техлид разбирают причину, а вывод фиксируют в чек-листе или в rules config.yaml.

3.4Техническое решение

Кто
Техлид
Вход
Утверждённые требования
Выход
design.md — если техлид решил, что он нужен; финальный tasks.md; PR смержен в develop спек-репозитория — разработка начинается
  • design.md в той же ветке: что есть в коде сейчас, цели и не-цели, решения D1, D2… с отвергнутыми альтернативами, риски, порядок выката и откат (справочник: шаблон «design.md»). Нужен ли design.md, решает техлид.
  • tasks.md сверяется с решениями: задачи ссылаются на D, порядок групп указан явно.
  • Чекбоксы в tasks.md — только для работы до мержа PR с кодом. Проверки QA и DevOps на стенде — в разделе «Проверка после развёртывания» обычным списком, с исполнителем и подзадачей Jira: они не блокируют архивацию.
  • Техлид мержит PR в develop спек-репозитория merge-коммитом.

3.5Реализация

Кто
Разработчик с агентом
Вход
Изменение в develop спек-репозитория
Выход
Код и тесты в ветке; задачи отмечены
  1. Ветка feat/<KEY>-… в каждом затронутом кодовом репозитории. Целевой и самый эффективный режим — один разработчик реализует и бэкенд, и фронтенд изменения.
  2. Реализация по циклу «Цикл работы». Перед PR рекомендуется прогнать сценарии на локальном стенде, чтобы агент проверил результат.
  3. Если требование оказалось неверным или неполным, аналитик правит его через /opsx:update, и код пишется по исправленной версии.
  4. Выполненные задачи отмечаются [x] в vendor/openspec-specs/openspec/changes/<name>/tasks.md; scripts/sync-openspec-progress.sh "<сообщение>" коммитит отметки в ветку спек-репозитория с тем же именем, что ветка кода. Ветка пушится, PR в develop спек-репозитория мержится merge-коммитом до мержа PR с кодом, который закрывает последнюю задачу.

3.6PR и ревью

Кто
Автор; техлид
Вход
Ветка, прошедшая проверку перед PR («Перед открытием PR»)
Выход
PR одобрен: CI зелёный, находки AI-ревью закрыты, техлид одобрил

PR открывается в develop кодового репозитория; GitHub подставляет в описание шаблон .github/pull_request_template.md (справочник: «Шаблон PR»):

  • Ссылка на спецификацию openspec/changes/<name> — по ней CI проверяет PR (OpenSpec link check) и архивирует изменение при мерже. PR без изменения спецификации получает метку no-spec.
  • Доказательство исполнения — фактический вывод проверок; для ручной проверки на стенде — стенд, шаги, результат.
  • Риск и откат — уровень риска, что может сломаться, как откатить.
  • Чек-лист перед ревью — автор отмечает пункты до запроса ревью.

Ревью — по правилам ревью кода.

3.7Мерж и архивация

Кто
Автор мержит; архивирует CI
Вход
Одобренный PR
Выход
Код в develop; если это последняя задача — изменение в архиве, openspec/specs/ обновлены
  • CI (openspec-archive-sync) архивирует изменение сразу при мерже PR, который закрывает последнюю задачу, в любом из репозиториев, — до приёмки QA. Пока открыты задачи других репозиториев, изменение ждёт.
  • Архивация идёт в ту ветку спек-репозитория, в которую смержен PR: дельты вливаются в openspec/specs/, изменение переносится в changes/archive/YYYY-MM-DD-<name>/, указатель submodule в кодовом репозитории обновляется.
  • Если архивация не прошла (нет ссылки, сбой job) — ручной запуск: Actions → OpenSpec Archive Sync → Run workflow, имя изменения и ветка.

3.8Приёмка и дефекты

Кто
QA
Вход
Код развёрнут на стенде
Выход
Принято или заведены дефекты

QA проверяет развёрнутый код по сценариям спецификации — вручную и с агентом через Playwright MCP — и выполняет «Проверку после развёртывания». Сценарии, покрытые автотестами, вручную не повторяются. Изменение к этому моменту уже в архиве, поэтому дефект исправляется так:

ДефектКак исправляется
Код расходится со сценарием спецификацииБаг в Jira со ссылкой на сценарий (capability / Requirement / Scenario); PR с исправлением и меткой no-spec
Спецификация неверна или молчитНовое изменение-дельта на затронутые требования («Когда пишется спецификация»), затем PR с исправлением
Код откатан revert-ом после архивацииИзменение-дельта, которое возвращает требования к прежнему состоянию

4Требования

4.1Артефакты изменения

openspec/changes/<key>-<name>/
├── .openspec.yaml                 # схема и дата создания
├── proposal.md                    # зачем и что меняется; ссылка на Jira
├── specs/<capability>/spec.md      # дельта требований
├── prototypes/*.html              # прототипы экранов
├── design.md                      # техническое решение: D1, D2…
└── tasks.md                       # задачи по репозиториям + «Проверка после развёртывания»
АртефактОтвечает на вопросАвтор
proposal.mdЗачем и что меняется, какие capabilities, на что влияет, что вне рамок, BREAKING или нетАналитик
specs/<capability>/spec.mdЧто система должна делать: контракт поведения бэкенда и фронтендаАналитик
prototypes/*.htmlКак выглядят экраны и их состоянияАналитик
tasks.mdЧто сделать, в каком репозитории, в каком порядке, как проверитьАналитик с агентом; утверждает техлид
design.mdКак это реализуется: решения и альтернативыТехлид, при необходимости

В spec.md нет имён классов, функций, библиотек и таблиц — это design.md. В design.md нет мотивации и требований — они в proposal.md и spec.md. Стандарт и шаблоны — в справочнике: стандарт требований, шаблоны артефактов.

4.2Прототипы и дизайн

Основной режим — HTML-прототипы в спецификации. Аналитик делает прототипы экранов с агентом в openspec/changes/<name>/prototypes/. Прототип проходит Гейт 1 вместе с требованиями и служит референсом для разработчика и агента.

  • Прототип показывает флоу и состояния: данные, пусто, загрузка, ошибка, нет прав, крайние значения.
  • Поведение задают сценарии спецификации; прототип — референс экрана; реализация — на компонентах проекта.
  • Задача на UI в tasks.md ссылается на свой прототип.

Режим с дизайнером — если дизайнер внешний или продукт требует детального согласования дизайна с бизнесом. Дизайн делает дизайнер в Figma, прототипы аналитика служат примером флоу. Спецификация ссылается на фреймы Figma, агент разработчика читает их через Figma MCP-сервер. Описание экранов в этом режиме — ui.md альтернативного варианта («Дополнительные артефакты изменения»).

4.3Чек-лист перед ревью требований

Стандарт качества изменения. За него отвечает аналитик: перед PR он проходит список сам, затем агент в новой сессии проверяет изменение по тому же списку и по коду. Изменение, не прошедшее хотя бы один пункт, на ревью не отправляется.

5Работа разработчика

5.1Цикл работы

#ШагПравило
1Прочитать изменениеproposal.md, specs/, design.md, tasks.md, прототипы — целиком, до запуска агента; вопросы — аналитику до старта
2Проверить задачи своего репозиторияКаждая задача — один заход и явный способ проверки; каждый сценарий покрыт задачей
3Запустить реализацию/opsx:apply <change> в кодовом репозитории
4Тесты по сценариямАгент пишет тесты по сценариям спецификации; имя теста — требование и сценарий (пример ниже)
5Вести сессиюОдно изменение — одна сессия; проверка pnpm run verify и коммит после каждой задачи; новая сессия при длинном контексте
6Требовать доказательствоАгент показывает вывод тестов, сборки, линта; «Готово» — только с зелёной проверкой
7Отметить задачи[x] в tasks.md через scripts/sync-openspec-progress.sh («Реализация»)
describe('Requirement: Блокировка пользователя', () => {
  it('Scenario: Администратор блокирует пользователя', async () => { /* ... */ });
  it('Scenario: Нет права на блокировку', async () => { /* ... */ });
});

5.2Перед открытием PR

6Ревью кода и CI

6.1Модель контроля

Ревью — набор слоёв проверок: рутину ловят агенты и CI, рискованный код и архитектуру проверяет техлид. Модель повторяет практику Anthropic (How the Claude Code team does code review, How Anthropic secures its AI-native SDLC).

СлойЧто происходитКто
До PRТесты, сборка, линт; /code-review и /security-review в сессии автораАвтор и агент
CIПроверки PR (справочник: «Связка репозиториев и CI»); красный CI — мержа нетCI
Ревью PRПроверка доказательств и рискованного кодаТехлид

AI-ревью и security-ревью выполняет автор в локальной сессии Claude Code, в CI их нет. PR одобряет техлид.

6.2Уровни риска

Уровень определяется по содержанию изменения. CI ставит метку tier-1/tier-2/tier-3 по путям и размеру diff; техлид поднимает уровень вручную. Автор запускает /code-review high для высокого уровня и /code-review medium для обычного.

УровеньПризнакиРевью техлида
Высокий
tier-1
Критичные пути проекта: авторизация и права, движение денег, ключи и секреты, персональные данные; миграции БД; CI и настройки агента; публичные контрактыЧитает критичный путь построчно
Обычный
tier-2, tier-3
Остальные измененияПроверяет доказательства и ключевые места
  • PR с меткой oversized разбивается или согласуется с техлидом; с oversized-ceiling — разбивается.
  • Новые коммиты после одобрения ревьюятся повторно.
  • Критичные пути проект задаёт в risk-tier-label.yml.

6.3Как проводится ревью PR

Автор до PR запускает /code-review на уровне риска и /security-review и закрывает находки. Техлид:

  1. Проверяет в PR доказательства: вывод проверок, ссылку на изменение, отметку о пройденном AI-ревью.
  2. Читает сам критичный путь (высокий уровень), контракты и миграции.
  3. Оставляет замечания в PR; мерж — после закрытия блокирующих.

Повторное AI-ревью техлид запускает по желанию — например, для PR высокого риска или большого diff:

gh pr checkout 1234          # ветка PR локально
claude
> /code-review high 1234
> /security-review            # diff ветки против develop

/code-review high запускает несколько агентов и расходует заметно больше лимита подписки, поэтому уровень выбирается по риску.

6.4Замкнутый цикл

Время техлида уходит на требования, архитектуру, PR высокого риска и развитие проверок. Повторяющиеся проблемы фиксируются в правилах и проверках:

СигналКуда фиксируется
Повторяющееся замечание ревью кодаCLAUDE.md, линт-правило или тест
Повторяющееся замечание к требованиямrules в openspec/config.yaml
Класс уязвимости.claude/claude-security-guidance.md («Подготовка кодового репозитория»)
Инцидент или откатНовая проверка в слое, который должен был поймать проблему
Гейт 1 стабильно требует третьей итерации; растёт время ожидания ревью или число откатовПересмотр правил, уровней риска или проверок CI

7Тестирование

  • Каждый сценарий спецификации проверяется до мержа: автотестом, а пока автотестов нет — разработчиком с агентом на локальном стенде.
  • Тесты по сценариям пишет агент в ходе /opsx:apply; имя теста — требование и сценарий.
  • Перед PR рекомендуется прогнать сценарии на локальном стенде, чтобы агент проверил результат: API — запросами, UI — в браузере через Playwright MCP.
  • QA проверяет на стенде по сценариям спецификации — вручную и с агентом — и переводит пункты регрессионного чек-листа в автотесты.
  • Нестабильный тест исправляется или отключается со ссылкой на задачу Jira.

Целевое состояние — автотесты и браузерные тесты на все сценарии («Автотесты и Playwright»).

8Внедрение в проект

8.1Что берётся как есть и что адаптируется

Берётся как естьАдаптируется проектом
Деление на ядро и бизнес-логику, доступыСостав репозиториев ядра и бизнес-логики
Один спек-репозиторий, submodule vendor/openspec-specs и симлинк openspec/Какой репозиторий своим релизом продвигает main спек-репозитория
Структура изменения, правила config.yaml, GLOSSARY.mdcontext в config.yaml, термины
Процесс поставки, Гейт 1 с двумя итерациями, чек-лист перед ревью требований—
Шаблон PR, ссылка на изменение, метка no-spec, проверки OpenSpecИмена веток и релизный процесс
PR Checks, AI-ревью и security-ревью каждого PR, уровни рискаКритичные пути, команда verify
Тесты по Requirement/ScenarioТестовые фреймворки, стенды
Ключ Jira в имени веткиСхема статусов, каналы оповещений

Если рекомендуемый вариант не подходит команде или релизному процессу, проект берёт альтернативный вариант целиком или его отдельные элементы («Альтернативный вариант»).

8.2Чек-лист внедрения

#ШагКто
1Разделить репозитории на ядро и бизнес-логикуТехлид
2Выдать доступы («Доступы»)DevOps
3Создать спек-репозиторий продукта: openspec init --tools claude, openspec/config.yaml, CLAUDE.md, GLOSSARY.md, workflow validate.yml (справочник: «config.yaml спек-репозитория»)Техлид
4В спек-репозитории разрешить мерж PR только merge-коммитомDevOps
5Подключить к спек-репозиторию каждый репозиторий бизнес-логики (справочник: «Связка репозиториев и CI», «Подключение кодового репозитория»)Техлид или разработчик
6Секреты, переменные и метки для workflows (справочник: «Связка репозиториев и CI»)DevOps
7Подготовить каждый кодовый репозиторий к работе агента («Подготовка кодового репозитория»)Техлид или разработчик
8Связь Jira с GitHub по ключу в имени ветки, если её нетDevOps
9Отключить телеметрию OpenSpec: openspec config set telemetry.enabled false или OPENSPEC_TELEMETRY=0Каждый участник

8.3Подготовка кодового репозитория

Репозиторий готов к работе агента, когда агент сам ставит окружение, одной командой прогоняет все проверки и видит результат.

.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(pnpm run verify)",
      "Bash(pnpm --filter:*)"
    ],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  },
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

Плагин security-guidance проверяет изменения агента на уязвимости по ходу сессии и сообщает о находках агенту; /security-review автор запускает перед PR («Как проводится ревью PR»). Обе проверки идут локально в Claude Code.

9Альтернативный вариант

Части 0–8 описывают рекомендуемый вариант. Альтернативный вариант проект выбирает, если рекомендуемый не подходит его команде или релизному процессу.

9.1Когда применяется

  • У авторов спецификаций — аналитиков, дизайнера, QA — нет доступа к коду.
  • Продукт выпускается версиями: релизный срез, rc-сборка на stage, формальная приёмка QA, единый тег для всех репозиториев.
  • Дизайн ведёт дизайнер в Figma.
  • Репозиториями руководят разные тимлиды, у QA — отдельный репозиторий e2e-тестов.

9.2Отличия от рекомендуемого варианта

РешениеРекомендуемый вариантАльтернативный вариант
Источник фактов для аналитикаКод репозиториев бизнес-логики через агентаopenspec/specs/ — подтверждённое поведение; contracts/ — копия Swagger бэкенда; архив изменений. Чего там нет, записывается в раздел «Открытые вопросы» proposal.md: адресат (тимлид бэка, тимлид фронта, ПМ), допущение, ответ. На Гейт 1 изменение уходит, когда у каждого вопроса есть ответ
Контракт APIOpenAPI в коде, спецификация ссылается на негоКопия схемы бэкенда в contracts/ спек-репозитория, обновляется из бэкенда без ручных правок; новые и меняемые эндпоинты — фрагмент contract/openapi.yaml в изменении, проверка Spectral; автор — тимлид бэка, черновик готовит аналитик
Схема OpenSpecspec-drivenСвоя схема с дополнительными артефактами («Дополнительные артефакты изменения») и проектными проверками (npm run check)
Дизайн и прототипыHTML-прототипы аналитикаФреймы Figma в ui.md с состояниями и data-testid; HTML-прототип собирает скилл после ответов на все вопросы, в CSS продукта из docs/design/
Гейт 1ТехлидОдобрения ролей по затронутым репозиториям: QA — всегда, бэкенд — тимлид и техлид бэка, фронтенд — тимлид фронта, процесс и основные спецификации — CTO. Workflow считает одобрения текущего коммита и ставит статус «Gate 1»
design.mdВ спек-репозитории, техлидВ кодовом репозитории: docs/changes/<change>/design.md и план. Для изменений высокого и среднего риска — отдельный design PR до кода
Реализация/opsx:apply, отметки задач разработчикомСкилл apply плагина компании; /opsx:apply и /opsx:sync отключены заглушками. Расхождение со спецификацией — скилл spec-gap, решение за тимлидом. Сабмодуль спецификаций в кодовом репозитории — только чтение; задачи отмечает тимлид репозитория со ссылкой на смерженный PR
ТестыАгент разработчика пишет тесты по сценариямtest-plan.md до кода распределяет каждый сценарий по уровню и репозиторию; e2e — QA в отдельном репозитории на Playwright; скрипты проверяют связь «сценарий → тест» и наличие data-testid в коде фронта
АрхивацияCI при мерже PR, закрывающего последнюю задачуПосле приёмки QA на rc-сборке: QA добавляет acceptance.md с результатом «принято», затем /opsx:archive в спек-репозитории; PR архивации красный без приёмки или с неотмеченными задачами
JiraЗадача и ключ в имени веткиЗадача-родитель — изменение; работа каждого репозитория — подзадача; ключ подзадачи — в ветке, коммитах и заголовке PR, а также в заголовке группы tasks.md
Релизdev → stage → prod по релизному процессу проектаСрез develop → main раз в две недели, rc-тег на stage, регрессия и приёмка, единый тег vX.Y.Z для всех репозиториев
Метрики процесса—npm run report: доля PR по изменениям, PR без одобрения, доля no-spec, время Гейта 1, правки спецификации после мержа

Остальное совпадает с рекомендуемым вариантом: стандарт требований, чек-лист перед ревью, AI-ревью и security-ревью, проверки CI. Уровень риска указывается в meta.yaml изменения по правилам config.yaml.

9.3Дополнительные артефакты изменения

АртефактЧто в нёмАвтор
meta.yamlКлюч Jira, уровень риска, BREAKING — в строгом формате для CI и метрикАналитик
ui.mdФреймы Figma, состояния экранов, таблица data-testid или «UI не меняется.»Дизайнер
contract/openapi.yamlФрагмент OpenAPI 3 только для новых и меняемых эндпоинтовТимлид бэка
journeys.mdПуть каждого актора по шагам со ссылками на требования; минимум один сценарий с отказомАналитик и QA
test-plan.mdКаждый сценарий спецификации и пользовательский сценарий → уровень тестов и репозиторийQA
acceptance.mdИтог приёмки на rc-сборке: результат, сборка, проверенные сценарии, дефектыQA

9.4Элементы для рекомендуемого варианта

Отдельные элементы альтернативного варианта проект подключает и в рекомендуемом:

  • раздел «Открытые вопросы» в proposal.md с адресатом, допущением и ответом — все ответы записаны до Гейта 1;
  • journeys.md и test-plan.md, когда QA нужны пользовательские сценарии и план тестов до кода;
  • таблица data-testid для экранов — стабильные селекторы для браузерных тестов;
  • CSS продукта в спек-репозитории — прототипы выглядят как продукт;
  • проверка связи «сценарий → тест» скриптом перед PR;
  • отчёт по метрикам процесса.

10В проработке

Направления, по которым принят курс; на практике ещё не проверены.

10.1Маркетплейс скиллов компании

Общий маркетплейс плагинов Claude Code в GitHub: проекты подключают одни и те же скиллы, и подход одинаков во всех проектах. В альтернативном варианте так уже работает плагин компании со скиллами apply, spec-gap, spec-update, qa-tests.

  • Репозиторий маркетплейса содержит каталог .claude-plugin/marketplace.json и плагины; скилл плагина лежит в skills/<name>/SKILL.md и вызывается как /<плагин>:<скилл>.
  • Проект подключает маркетплейс и плагины в .claude/settings.json, который коммитится:
    {
      "extraKnownMarketplaces": {
        "company": { "source": { "source": "github", "repo": "<org>/<marketplace-repo>" } }
      },
      "enabledPlugins": { "opsx@company": true }
    }
  • Для приватного репозитория маркетплейса у каждого участника — доступ на чтение.
  • Плагин раздаёт то, что исполняет Claude Code: скиллы и хуки. Схема OpenSpec, config.yaml и CI раздаются шаблоном спек-репозитория.
  • Кандидаты в первый плагин: /opsx:ask — ответы по проекту с цитатами из спецификаций, решений и кода, без записи (скилл ask плагина opsx; имена скиллов плагина не совпадают с командами OpenSpec); скилл критических проверок («Скилл критических проверок»); генерация сценариев для тестов («Автотесты и Playwright»).

10.2Скилл критических проверок

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

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

Основа — .claude/claude-security-guidance.md («Подготовка кодового репозитория») и rules OpenSpec; распространение — через маркетплейс («Маркетплейс скиллов компании»).

10.3Автотесты и Playwright

Целевое состояние тестирования — автотесты на все сценарии спецификации в verify и CI.

  • Фронтенд: Playwright Test против собранного приложения с подменённым API; селекторы — по ролям и подписям или data-testid.
  • Playwright MCP для всей команды — в .mcp.json репозитория: claude mcp add --scope project playwright -- npx @playwright/mcp@latest.
  • Регрессионный прогон всех тестов на релизном PR и сквозной прогон после деплоя на dev.
  • Генерация тестов из сценариев: вместе с требованиями агент создаёт план браузерных тестов, агенты Playwright (npx playwright init-agents --loop=claude: planner, generator, healer) превращают его в тесты и чинят упавшие. Формат плана — в проработке.

10.4Развитие схемы OpenSpec

Из ревью документа «OpenSpec: кастомизация company-харнесса» к проработке приняты:

  • Реестр сквозных решений openspec/adr/ — для решений, которые переживают одно изменение; решения уровня изменения остаются в design.md. Принятое решение не редактируется, а заменяется новым со ссылкой supersedes.
  • Лог бизнес-решений openspec/decisions/BD-NNNN-*.md: контекст, решение, обоснование, влияние, триггер пересмотра; ключ Jira или out-of-band; ведут ПМ и аналитик.
  • Общая схема компании на основе схемы альтернативного варианта («Дополнительные артефакты изменения»): openspec schema fork, опциональные артефакты подключаются по проекту.

AI-NATIVE SDD · СПРАВОЧНИК · v2.0

Справочник

Конфигурации, стандарт требований и шаблоны. Ссылки «регламент: …» ведут в основной документ.

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

РольИнструментДля чего
АналитикClaude Code в спек-репозитории с --add-dir к репозиториям бизнес-логики; OpenSpec CLIРазбор по коду, требования, прототипы, validate (регламент: «Доступы»)
АналитикВеб-редактор GitHub, github.devТочечная правка без агента
Техлид, разработчикClaude Code, OpenSpec CLI, ghРеализация, отметки задач, ревью PR локально
Автор PR, техлид/code-review, /security-review, плагин security-guidanceAI-ревью и security-ревью (регламент: «Как проводится ревью PR»)
Разработчик фронтенда, QAPlaywright Test, агенты Playwright, Playwright MCPБраузерные тесты, проверка UI агентом
РазработчикFigma MCP-сервер — в режиме с дизайнеромЧтение макетов (регламент: «Прототипы и дизайн»)
ПМ, QAGitHub (чтение спек-репозитория), JiraГейт 1, приёмка, статусы
DevOpsGitHub Actions, секреты, стендыCI, доступы, релизы

Версия OpenSpec закреплена в CI (сейчас 1.13.1) и обновляется одновременно во всех репозиториях вместе с openspec update.

§2Связка репозиториев и CI

Аналитик     PR требований → develop спек-репозитория
               CI: Validate specs
Техлид       design.md, tasks.md → мерж в develop
Разработчик  ветка feat/<KEY>-… в кодовом репозитории
             pre-push: бамп vendor/openspec-specs до спек-develop
             PR в develop
               CI: PR Checks, link check, sync check, size gate, risk tier
             отметки [x] → одноимённая ветка спек-репозитория → PR в спек-develop
Мерж PR      CI: archive sync — все задачи [x]?
               да  → openspec archive в спек-develop → бамп указателя в develop кода
               нет → ждём PR остальных репозиториев
Релиз        бэкенд develop → main: спек-main догоняет запиненный коммит
             фронтенд: проверка, что запиненный коммит есть в спек-develop или main
ФайлРепозиторийТриггерЧто делает
pr-checks.ymlКодовыеPR в develop, mainpnpm run verify относительно базовой ветки PR (NX_BASE=origin/<base>)
.github/workflows/validate.ymlСпекPR, push в mainopenspec validate --all --strict
openspec-link-check.ymlКодовыеPR в developСсылка openspec/changes/<name> на изменение из спек-develop или метка no-spec
openspec-sync-check.ymlКодовыеPR в develop, mainУказатель не отстаёт от спек-ветки; автофикс коммитом в ветку PR
openspec-archive-sync.ymlКодовыеМерж PR, push в main, ручной запускАрхивация при закрытых задачах, продвижение спек-main, бамп указателя, оповещение о сбое
pr-size-gate.yml + .github/scripts/pr-diff-stats.jsКодовыеPR в developМетки размера без учёта тестов
risk-tier-label.ymlКодовыеPR в developМетки tier-1/2/3 по путям и размеру
Сканирование секретов, SonarQubeКодовыеПо проектуГде включены
.husky/post-checkout, post-mergeКодовыеЛокальноgit submodule update --init
.husky/pre-pushКодовыеЛокально, feature-веткиБамп указателя до спек-develop
scripts/update-openspec-specs.shКодовыеВручнуюБамп указателя, отчёт о расхождении команд и скиллов OpenSpec
scripts/sync-openspec-progress.shКодовыеВручнуюКоммит отметок задач в одноимённую ветку спек-репозитория

Условие архивации — фрагмент openspec-archive-sync.yml:

PROGRESS=$(openspec list --json | jq -r --arg c "$CHANGE" \
  '.changes[] | select(.name == $c) | "\(.completedTasks) \(.totalTasks)"')
read -r DONE TOTAL <<< "$PROGRESS"
if [ "$DONE" -lt "$TOTAL" ]; then
  echo "::notice::'$CHANGE' is not archived yet: $((TOTAL - DONE)) of $TOTAL task(s) are not marked [x]"
  exit 0
fi
openspec archive "$CHANGE" --yes
git commit -q -m "chore: archive ${CHANGE}" && git push origin "HEAD:$TARGET"

Нужно в каждом кодовом репозитории: секрет SPECS_REPO_DEPLOY_KEY — SSH-ключ с записью в спек-репозиторий; секрет BOT_TOKEN, переменные CHAT_ID, CHAT_THREAD_ID — оповещения; переменная OPENSPEC_VERSION — по желанию; метки no-spec, tier-1, tier-2, tier-3, oversized, oversized-ceiling.

§3Подключение кодового репозитория

cd <кодовый-репозиторий>
openspec init --tools claude
rm -rf openspec

git submodule add https://github.com/<org>/<Product>-Specs.git vendor/openspec-specs
ln -s vendor/openspec-specs/openspec openspec
git add .gitmodules vendor/openspec-specs openspec .claude
  1. Проверка: openspec context → OpenSpec root: <кодовый-репозиторий>; git submodule status — без -/+ перед SHA.
  2. Добавить: scripts/*-openspec-*.sh, .husky/post-checkout, post-merge, pre-push, workflows из §2, .github/pull_request_template.md, раздел «Specs / OpenSpec» в README.md.
  3. В package.json — prepare с git submodule update --init --recursive vendor/openspec-specs, чтобы pnpm install подтягивал спецификации.
  4. Клонирование: git clone --recurse-submodules <url>.
  5. После мержа изменения в спек-репозитории: bash scripts/update-openspec-specs.sh и коммит сдвига указателя (на PR это делает sync check).
Известная особенность. В OpenSpec 1.13.1 openspec archive, запущенный через симлинк openspec/, падает на изменениях с двумя и более capabilities (исправлено в 1.14.2). Архивация идёт только через CI, который запускает её прямо в спек-репозитории.

§4config.yaml спек-репозитория

context подставляется агенту при работе с любым артефактом, rules — при создании артефакта своего типа, operations — при реализации и архивации. Пример (operations сокращены):

schema: spec-driven

context: |
  Проект: <продукт> — <назначение> (<стек бэкенда>).
  Сервисы (apps/ бэкенда): <список>.
  Домен: <основные сущности и процессы>.
  Термины — по GLOSSARY.md в этом репозитории.
  Фронтенды — отдельные репозитории (<стек>), работают через публичный API: <список>.
  Одно изменение может охватывать бэкенд и фронтенд; в tasks.md у каждой группы задач
  указан репозиторий, а изменение архивируется при мерже PR, закрывающего последнюю задачу.
  Спецификации пишутся на русском языке.
  Публичные контракты (HTTP-эндпоинты, вебхуки, события) фиксируются в спецификации
  явно. При наличии OpenAPI-схемы в коде спецификация ссылается на неё, а не дублирует.

rules:
  proposal:
    - "Раздел Why не длиннее пяти предложений и объясняет проблему, а не решение"
    - "Явно указывать, является ли изменение ломающим (пометка BREAKING), если меняются публичные контракты"
  specs:
    - "Каждое требование обязано иметь сценарий негативного пути или явное указание, что его нет"
    - "Нефункциональные требования обязаны содержать числовой порог, а не формулировку вида «быстро»/«надёжно»"
    - "Термины соответствуют GLOSSARY.md; синонимы одного и того же понятия не используются"
    - "Не упоминать имена классов, функций, библиотек, структур таблиц — это design.md"
  tasks:
    - "Каждая задача содержит явный способ проверки в своём тексте"
    - "Чекбоксы — только для работы, выполняемой до мержа PR: изменение архивируется автоматически при мерже и не архивируется, пока есть неотмеченные задачи"
    - "Проверки после развёртывания, выполняемые не разработчиком (QA, DevOps, стенд, совместный релиз), — в последнем разделе «Проверка после развёртывания» обычным списком без чекбоксов, с исполнителем и ключом подзадачи Jira"
  design:
    - "Не создавать design.md по умолчанию: всегда спросить пользователя, нужен ли он для этого изменения, и создавать только при явном согласии"

operations:
  apply:
    guidance:
      - "Каждый сценарий спецификации должен иметь тест, названный по конвенции Requirement/Scenario"
  archive:
    guidance:
      - "Перед архивацией сверить, что реализация не разошлась со спецификацией; расхождение — повод вернуть на доработку, а не молча заархивировать"

Репозиторий ядра использует тот же файл в своём openspec/config.yaml с контекстом «спецификации лежат в этом же репозитории рядом с кодом».

§5Стандарт требований

Формат требований к продукту. Перед ревью изменение проверяется по чек-листу (регламент: «Чек-лист перед ревью требований»).

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

Заголовок дельтыНазначениеОбязательно
ADDED ## ADDED RequirementsНовые требования—
MODIFIED ## MODIFIED RequirementsИзменение существующихПолный текст требования со всеми сохраняемыми сценариями
REMOVED ## REMOVED RequirementsУдаление**Reason** и **Migration**
RENAMED ## RENAMED RequirementsПереименованиеFROM: / TO:
Requirement: Блокировка пользователя

В карточке пользователя SHALL быть действие «Заблокировать» по праву на управление пользователями. … Негативный путь: при отказе SHALL показываться причина, статус не меняется.

Scenario: Нет права на блокировку
WHENкарточку открывает пользователь без права на управление пользователями
THENдействия «Заблокировать» нет
  1. У каждого требования минимум один сценарий и негативный путь (или явное указание, что его нет).
  2. SHALL / MUST — в тексте требования; «желательно», «может», «should» не используются.
  3. MODIFIED копирует требование целиком: частичная копия теряет сценарии при архивации.
  4. Одно поведение — одно требование; примеры и крайние случаи — в сценариях.

Формат — заголовки, длину текста, ## Purpose — проверяет openspec validate --strict. Правила проекта сверх валидатора задаются в rules файла openspec/config.yaml, и агент применяет их автоматически («config.yaml спек-репозитория»).

Контракты и OpenAPI

ЧтоКак записывается в спецификации
HTTP-эндпоинтМетод, путь, обязательные поля, права, коды успеха и ошибок
Событие, вебхукИмя, обязательные поля, условия и порядок отправки
Переходы состоянийВсе допустимые переходы и условия, включая терминальные
ИдемпотентностьКлюч, окно действия, поведение при повторе
Обратная совместимостьЛомающее изменение помечается BREAKING в proposal.md

Схема полей — в OpenAPI из кода; спецификация ссылается на неё и задаёт то, что схема не выражает: правила, инварианты, условия.

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

Требования к скорости, нагрузке и надёжности записываются с числовым порогом.

ПлохоХорошо
«Список обновляется быстро»«Новая запись SHALL появляться в списке не позже чем через 10 с после создания»
«Не дублировать»«Повторный запрос с тем же ключом идемпотентности SHALL возвращать результат исходной операции»
«Учесть гонки»«Из двух одновременных запросов на одно списание SHALL исполняться ровно один, второй получает 409»

Антипаттерны

АнтипаттернПримерРезультат в коде
Неизмеримость«Быстро», «удобно»Агент выбирает порог сам
Подразумеваемый контекст«Как в выплатах»Агент додумывает
Только успешный путьНет ошибок и отказовОшибки обрабатываются как получится
Предписание реализации«Очередь Redis с TTL 60 с»Спецификация устаревает при рефакторинге; место — design.md
Разрыв фронтенда и бэкендаЭкран показывает поле, которого нет в APIИнтеграция ломается после реализации
Синонимы«Платёж», «транзакция», «операция» об одномАгент считает их разными сущностями
ПротиворечиеВ одном месте 3 попытки, в другом 5Агент молча выбирает одно

§6Шаблоны артефактов

proposal.md

# Proposal

Jira: [`<KEY>`](<url>) <название>.

## Why
<!-- Проблема и почему сейчас; не длиннее пяти предложений -->

## What Changes
<!-- Что меняется для бэкенда и фронтенда; BREAKING или нет; вне рамок -->

## Capabilities
### New Capabilities
- `<capability>`: <что покрывает>
### Modified Capabilities
- `<capability>`: <что меняется в требованиях>

## Impact
<!-- API, сервисы, фронтенд, инфраструктура, документация (GLOSSARY.md) -->

specs/<capability>/spec.md

# Spec Delta

## Purpose
<!-- Только для новой capability, от 50 символов -->

## ADDED Requirements

### Requirement: <имя>
<!-- Поведение с SHALL/MUST. Негативный путь: … -->

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

design.md

# Design

## Context
Мотивация — `proposal.md`. Требования — `specs/…`.
Что есть в коде сейчас: <!-- факты из кода, на которые опирается решение -->

## Goals / Non-Goals

## Decisions
### D1. <решение>
<!-- Что и почему. *Альтернатива* — …: причина. Отклонена. -->

## Risks / Trade-offs
- [<риск>] → <митигация>

## Migration Plan
<!-- Порядок выката; откат одним действием -->

tasks.md

# Tasks

Jira: [`<KEY>`](<url>). Подход — `design.md`. Группы 1–N — `<репозиторий>`, M — `<репозиторий>`.
Порядок: <зависимости групп>.

## 1. <группа> (<репозиторий>) (D1, D2)

- [ ] 1.1 <задача> — проверка: <тест Requirement/Scenario или команда>

## Проверка после развёртывания

- QA (подзадача Jira): <стенд, сценарий, ожидаемый результат>
- DevOps (подзадача Jira): <переменные, публикация>

§7Шаблон PR

.github/pull_request_template.md кодового репозитория. GitHub подставляет его в описание каждого нового PR; автор заполняет разделы и отмечает чек-лист до запроса ревью. Строку openspec/changes/<name> читает CI: OpenSpec link check проверяет, что изменение есть в спек-develop, OpenSpec archive sync архивирует его при мерже.

## Что делается и почему

<!-- Заявление о намерении: что делается, что сознательно не сделано, что вне охвата. -->

## Ссылка на спецификацию

openspec/changes/<name>

<!--
Замените <name> на имя изменения из спек-репозитория (develop) — по этой ссылке
изменение архивируется автоматически при мерже, а проверка «OpenSpec link check» не даст
смержить PR без неё. Если у PR нет изменения спецификации (мелкий фикс, CI, зависимости,
back-merge) — удалите строку выше и поставьте на PR метку no-spec.
-->

## Доказательство исполнения

<!-- Фактический вывод pnpm run verify — не просто "тесты проходят". Ручная проверка
на стенде: стенд, шаги, результат (скриншот или запись). -->

## Риск и откат

<!-- Уровень риска (метка tier-N), что может сломаться, как откатить одним действием. -->

## Чек-лист перед ревью

- [ ] `pnpm run verify` зелёный локально
- [ ] `/code-review` и `/security-review` пройдены, находки исправлены или отклонены с причиной
- [ ] У PR одна цель — фикс, фича, рефакторинг, документация или тесты, не смесь
- [ ] Не изменено и не удалено существующее поведение, которое задача не просила менять
- [ ] Не удалены, не пропущены и не ослаблены существующие тесты
- [ ] Каждый сценарий спецификации имеет тест с именем, ссылающимся на этот сценарий
- [ ] Новых зависимостей нет либо они согласованы
- [ ] В diff нет ничего, что не следует из спецификации и задач
- [ ] Diff прочитан целиком собственными глазами

## Происхождение

<!-- Какая модель, по какой спецификации; подтверждение отсутствия флагов обхода
разрешений (--dangerously-skip-permissions). -->

§8CLAUDE.md кодового репозитория

Корневой файл инструкций — короткий, 100–200 строк; специфика сервиса — во вложенном apps/<service>/CLAUDE.md.

# <Проект>

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

## Структура
- `apps/*`, `packages/*` — …
- `openspec/` — симлинк на `vendor/openspec-specs/openspec` (спек-репозиторий).
  Читать можно; писать через `/opsx:*` — только когда явно просят работать со спецификацией.

## Команды
- Установка: `pnpm install`
- Проверка: `pnpm run verify` — та же команда, что в CI (PR Checks); красный статус = задача не завершена
- Тесты одного сервиса: `pnpm --filter <package> test`
- Локальный стенд: `<команда>`

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

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

## Термины
- `vendor/openspec-specs/GLOSSARY.md`

## Чего не делать
- Не архивировать изменения вручную — архивирует CI.
- Не запускать Claude Code с `--dangerously-skip-permissions` в сессиях с реальными учётными данными.

§9Связь с Jira

Ключ задачи в имени ветки связывает с задачей коммиты, PR и мержи этой ветки: они попадают в Jira автоматически, статусы двигает автоматизация Jira.

ГдеПравилоПример
Ветки кода и спецификацийfeat/<KEY> или feat/<KEY>-<short>; одно имя во всех репозиториях измененияfeat/PROJ-123, feat/PROJ-123-user-blocking
Имя изменения<key>-<kebab-name>proj-123-user-blocking
proposal.md, tasks.mdПервая строка — ссылка на задачуJira: [PROJ-123](<jira>/browse/PROJ-123)
КоммитыConventional Commitsfeat(users): add user blocking
Проверки после развёртыванияПодзадачи Jira на QA и DevOpsПодзадача в PROJ-123

§10Команды

КомандаНазначение
/opsx:exploreРазбор задачи по коду и спецификациям, без создания артефактов
/opsx:propose "<описание>"Создать изменение и артефакты
/opsx:update <change>Править артефакты изменения согласованно
/opsx:apply <change>Реализовать задачи tasks.md
/opsx:syncСлить дельты в основные спецификации без архивации
openspec validate <change> --strictПроверка изменения до нуля ошибок и предупреждений
openspec validate --all --strictПроверка всех изменений и спецификаций
openspec list, openspec list --specsАктивные изменения, спецификации
openspec show <change> --diffИзменение требований в виде diff
openspec status --change <change>Готовность артефактов изменения
openspec contextКакой openspec/ видит CLI в текущем репозитории
claude --add-dir <путь> …, /add-dirДоступ агента к соседним репозиториям
/code-review [low|medium|high] [pr#]AI-ревью текущего diff или PR
/security-reviewSecurity-ревью ветки против ветки по умолчанию
gh pr checkout <pr#>Ветка PR локально для ревью
bash scripts/update-openspec-specs.shБамп указателя submodule
scripts/sync-openspec-progress.sh "<msg>"Коммит отметок задач в одноимённую ветку спек-репозитория
claude mcp add --scope project playwright -- npx @playwright/mcp@latestБраузер для агента; пишет .mcp.json
npx playwright init-agents --loop=claudeАгенты Playwright: planner, generator, healer

Архивация — только CI; ручной запуск — Actions → OpenSpec Archive Sync → Run workflow.

§11Копия схемы API в спек-репозитории

Для проекта, где у аналитика нет доступа к коду (регламент: «Если доступа к коду нет», «Альтернативный вариант»). Схема API бэкенда лежит в спек-репозитории в contracts/<api>/:

  • файлы не редактируются вручную — источник истины остаётся в бэкенде;
  • contracts/README.md фиксирует источник (репозиторий, ветку, коммит), способ обновления и известные расхождения схемы с реальным поведением;
  • спецификации и фрагменты контракта в изменениях ссылаются на пути в contracts/, не копируя существующие эндпоинты.

Обновление — workflow бэкенда при каждом push в develop; в main спек-репозитория копия попадает вместе с релизом бэкенда. Скрипт openapi:export — проектный: собирает схему без запуска сервиса. Шаблон для адаптации:

name: OpenAPI Sync
on:
  push:
    branches: [develop]
concurrency:
  group: openapi-sync
  cancel-in-progress: false
jobs:
  openapi:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc
      - run: corepack enable && pnpm install --frozen-lockfile
      - run: pnpm run openapi:export        # пишет openapi.json
      - name: Push to spec repo
        env:
          DEPLOY_KEY: ${{ secrets.SPECS_REPO_DEPLOY_KEY }}
        run: |
          set -euo pipefail
          install -m 700 -d ~/.ssh
          printf '%s\n' "$DEPLOY_KEY" > ~/.ssh/specs_deploy_key
          chmod 600 ~/.ssh/specs_deploy_key
          ssh-keyscan -t ed25519,rsa github.com >> ~/.ssh/known_hosts
          export GIT_SSH_COMMAND="ssh -i $HOME/.ssh/specs_deploy_key -o IdentitiesOnly=yes"
          git clone --depth 1 --branch develop git@github.com:<org>/<Product>-Specs.git specs
          mkdir -p specs/contracts/gateway
          cp openapi.json specs/contracts/gateway/openapi.json
          cd specs
          git add contracts
          if git diff --cached --quiet; then exit 0; fi
          git -c user.name=openapi-sync -c user.email=actions@github.com \
            commit -m "chore(contracts): sync gateway from ${GITHUB_SHA::7}"
          git push origin HEAD:develop

Если push отклонён из-за параллельной записи в develop спек-репозитория, job перезапускается.

§12Глоссарий

ТерминЗначение
SDDSpec-Driven Development: разработка, в которой спецификация — задание для реализации
Спек-репозиторийРепозиторий спецификаций продукта, общий для репозиториев бизнес-логики
ЯдроРепозитории компонентов, критичных для безопасности средств и ключей; без бизнес-правил продукта
Бизнес-логикаРепозитории API продукта, бизнес-правил и интерфейсов
CapabilityОбласть поведения системы; файл openspec/specs/<capability>/spec.md
Изменение (change)Папка openspec/changes/<name>/ с артефактами одной фичи до архивации
ДельтаФайл changes/<name>/specs/…/spec.md: добавляемые, изменяемые, удаляемые требования
Requirement / ScenarioТребование с SHALL/MUST и его проверяемый пример WHEN/THEN
Гейт 1Ревью требований техлидом до начала разработки, не больше двух итераций
Уровень рискаВысокий или обычный; задаёт глубину ревью техлида (tier-1…tier-3)
no-specМетка PR без изменения спецификации
CLAUDE.mdФайл инструкций для Claude Code в корне репозитория
MCPModel Context Protocol: подключение агента к внешним инструментам (Figma, Playwright)