AI-Native SDD · v2.0
SDD на OpenSpec
Регламент разработки через спецификации и AI-агентов. Составлен по практике проектов компании и практикам AI-native SDLC от Anthropic. Выберите роль в шапке — появятся разделы для неё.
Процесс поставки фичи — от задачи до приёмки
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: ошибка в требованиях исправляется правкой абзаца до того, как написан код. На ревью PR рутину проверяют CI и агенты, а техлид — рискованный код и архитектуру.
0.3Матрица ответственности
| # | Этап | ПМ | Аналитик | Техлид | Разработчик | QA | DevOps |
|---|---|---|---|---|---|---|---|
| 1 | Задача в Jira | A/R | |||||
| 2 | Требования и Гейт 1 | R | A | ||||
| 3 | design.md | A/R | |||||
| 4 | Реализация | A/R | |||||
| 5 | Ревью PR | A/R | |||||
| 6 | Приёмка | A/R | |||||
| 7 | Релиз, доступы, стенды | A/R |
Уровень риска PR определяет только глубину проверки техлида («Уровни риска»). Архивацию выполняет CI.
0.4Обязательные правила
- На продукт — один спек-репозиторий; репозитории бизнес-логики подключают его как git submodule, репозиторий ядра держит
openspec/у себя («Репозитории и доступы»). - Аналитик и его агент читают репозитории бизнес-логики; доступа к ядру у них нет («Доступы»).
- Каждая фича — бизнесовая и техническая — идёт через спецификацию («Когда пишется спецификация»).
- Требования уходят на ревью полными; ревью требований — не больше двух итераций («Гейт 1 — ревью требований»).
- Ветка называется по ключу задачи Jira:
feat/<KEY>-…(справочник: «Связь с Jira»). - PR с кодом ссылается на изменение
openspec/changes/<name>или имеет меткуno-spec(«PR и ревью»). - PR с красным CI не мержится.
- Каждый PR проходит AI-ревью и security-ревью автора и одобрение техлида («Уровни риска»).
- Каждый сценарий спецификации проверяется до мержа: автотестом, а пока автотестов нет — разработчиком с агентом на локальном стенде («Тестирование»).
- Изменение архивирует только CI («Мерж и архивация»).
1Принципы
1.1Принципы
Спецификация — единственный источник истины о требуемом поведении системы и прямой вход для агента, который пишет код.
- Буквальность. Агент реализует то, что написано. Чего нет в требованиях, не будет в коде; неточное требование даст неточный код. Из каждого требования выводится проверка.
- Дельта. Изменение описывает только то, что меняется; при архивации CI вливает его в
openspec/specs/. Поведение остальной системы агент читает из кода («Текущее состояние системы»). - Один источник на каждый вид знания. Поведение —
openspec/specs/и код; схема API — OpenAPI из кода; термины —GLOSSARY.md; задачи и статусы — Jira. Дублирование запрещено. - Синхронность через CI. Связь кода и спецификаций держат проверки PR и архивация в CI.
- Человек отвечает за результат. Агент пишет и проверяет, человек направляет и утверждает.
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Текущее состояние системы
У каждого вида знания о текущем состоянии один источник, который обновляется вместе с кодом:
| Что нужно знать | Источник | Почему не расходится с системой |
|---|---|---|
| Требования ко всему, что прошло через SDD | openspec/specs/ | CI вливает дельту при мерже кода |
| Поведение остальной системы: экраны, эндпоинты, статусы, права | Код; агент описывает блок по запросу и называет файлы | Код — фактическое поведение |
| Регрессионные сценарии | Сценарии спецификаций и автотесты по ним | Автотест, разошедшийся с кодом, ломает CI |
| Причины решений | design.md в архиве изменений | Архив не меняется |
Других описаний текущего состояния не ведётся. Исключение — документы для внешнего бизнеса и интеграций: они допускаются в Confluence как копия и обновляются по спецификациям.
2.5Если доступа к коду нет
Если ядро и бизнес-логика ещё в одном репозитории или аналитику по другой причине нельзя дать доступ к коду:
- текущее состояние ведётся в спецификациях: одна capability на блок; каждое изменение блока дописывает его требования в
openspec/specs/; - схема API автоматически копируется из кода в
contracts/спек-репозитория и всегда актуальна для интеграций (справочник: «Копия схемы API в спек-репозитории»); - вопросы, на которые нет ответа в спецификациях и контракте, аналитик задаёт тимлидам в разделе «Открытые вопросы»
proposal.md, и на Гейт 1 изменение уходит с ответами.
Так устроен альтернативный вариант процесса.
3Процесс поставки фичи
3.1Задача в Jira
Задача содержит: проблему — что не работает или чего не хватает и у кого; ожидаемый эффект и критерий успеха; границы — что явно не входит; срочность. Ключ задачи (PROJ-123) используется в имени изменения и веток (справочник: «Связь с Jira»).
3.2Требования, прототипы, задачи
- Ветка
feat/<KEY>-<short>в спек-репозитории; сессия Claude Code с доступом к коду (справочник: «Инструменты по ролям»). - Разбор:
/opsx:explore. Агент описывает текущее поведение затронутых блоков по коду бэкенда и фронтенда и поopenspec/specs/— эндпоинты, статусы, права, экраны. Вопросы к ПМ и техлиду снимаются здесь, до текста требований. - Изменение:
/opsx:proposeсоздаётopenspec/changes/<key>-<name>/. Аналитик доводитproposal.mdи дельты требований для бэкенда и фронтенда по стандарту требований. Контракт между бэкендом и фронтендом — эндпоинты, поля, коды ошибок, права — описывается один раз для обеих сторон.design.mdпишет техлид. - Прототипы: HTML-прототипы экранов — в
prototypes/изменения («Прототипы и дизайн»). - Задачи: агент формирует
tasks.md— группы по репозиториям, способ проверки у каждой задачи, ссылки UI-задач на прототипы, последний раздел «Проверка после развёртывания». - Проверка: аналитик и агент в новой сессии проходят чек-лист перед ревью.
- PR в
developспек-репозитория.
Техническую фичу по тому же процессу описывает техлид или разработчик. Изменение, которое написал техлид, Гейт 1 не проходит.
3.3Гейт 1 — ревью требований
На Гейт 1 уходит только готовое изменение. Качество требований — ответственность аналитика: техлид утверждает решение, а не дописывает требования.
- PR открывается, когда аналитик и агент прошли весь чек-лист перед ревью. Если пункт не выполнен, техлид возвращает PR без разбора — возврат считается итерацией.
- В PR нет черновиков, «TBD», «уточню позже» и открытых вопросов: вопросы к ПМ и техлиду закрыты на разборе, до текста требований.
- Итерация 1 — замечания техлида; аналитик закрывает каждое за один заход исправлением или ответом с причиной. Итерация 2 — финальная проверка и утверждение; новых тем в ней не появляется.
- Третья итерация — признак сырого материала. ПМ, аналитик и техлид разбирают причину, а вывод фиксируют в чек-листе или в
rulesconfig.yaml.
3.4Техническое решение
design.mdв той же ветке: что есть в коде сейчас, цели и не-цели, решения D1, D2… с отвергнутыми альтернативами, риски, порядок выката и откат (справочник: шаблон «design.md»). Нужен лиdesign.md, решает техлид.tasks.mdсверяется с решениями: задачи ссылаются на D, порядок групп указан явно.- Чекбоксы в
tasks.md— только для работы до мержа PR с кодом. Проверки QA и DevOps на стенде — в разделе «Проверка после развёртывания» обычным списком, с исполнителем и подзадачей Jira: они не блокируют архивацию. - Техлид мержит PR в
developспек-репозитория merge-коммитом.
3.5Реализация
- Ветка
feat/<KEY>-…в каждом затронутом кодовом репозитории. Целевой и самый эффективный режим — один разработчик реализует и бэкенд, и фронтенд изменения. - Реализация по циклу «Цикл работы». Перед PR рекомендуется прогнать сценарии на локальном стенде, чтобы агент проверил результат.
- Если требование оказалось неверным или неполным, аналитик правит его через
/opsx:update, и код пишется по исправленной версии. - Выполненные задачи отмечаются
[x]вvendor/openspec-specs/openspec/changes/<name>/tasks.md;scripts/sync-openspec-progress.sh "<сообщение>"коммитит отметки в ветку спек-репозитория с тем же именем, что ветка кода. Ветка пушится, PR вdevelopспек-репозитория мержится merge-коммитом до мержа PR с кодом, который закрывает последнюю задачу.
3.6PR и ревью
PR открывается в develop кодового репозитория; GitHub подставляет в описание шаблон .github/pull_request_template.md (справочник: «Шаблон PR»):
- Ссылка на спецификацию
openspec/changes/<name>— по ней CI проверяет PR (OpenSpec link check) и архивирует изменение при мерже. PR без изменения спецификации получает меткуno-spec. - Доказательство исполнения — фактический вывод проверок; для ручной проверки на стенде — стенд, шаги, результат.
- Риск и откат — уровень риска, что может сломаться, как откатить.
- Чек-лист перед ревью — автор отмечает пункты до запроса ревью.
Ревью — по правилам ревью кода.
3.7Мерж и архивация
- 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 проверяет развёрнутый код по сценариям спецификации — вручную и с агентом через 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 и закрывает находки. Техлид:
- Проверяет в PR доказательства: вывод проверок, ссылку на изменение, отметку о пройденном AI-ревью.
- Читает сам критичный путь (высокий уровень), контракты и миграции.
- Оставляет замечания в 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.md | context в 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 изменение уходит, когда у каждого вопроса есть ответ |
| Контракт API | OpenAPI в коде, спецификация ссылается на него | Копия схемы бэкенда в contracts/ спек-репозитория, обновляется из бэкенда без ручных правок; новые и меняемые эндпоинты — фрагмент contract/openapi.yaml в изменении, проверка Spectral; автор — тимлид бэка, черновик готовит аналитик |
| Схема OpenSpec | spec-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-guidance | AI-ревью и security-ревью (регламент: «Как проводится ревью PR») |
| Разработчик фронтенда, QA | Playwright Test, агенты Playwright, Playwright MCP | Браузерные тесты, проверка UI агентом |
| Разработчик | Figma MCP-сервер — в режиме с дизайнером | Чтение макетов (регламент: «Прототипы и дизайн») |
| ПМ, QA | GitHub (чтение спек-репозитория), Jira | Гейт 1, приёмка, статусы |
| DevOps | GitHub 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, main | pnpm run verify относительно базовой ветки PR (NX_BASE=origin/<base>) |
.github/workflows/validate.yml | Спек | PR, push в main | openspec 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
- Проверка:
openspec context→OpenSpec root: <кодовый-репозиторий>;git submodule status— без-/+перед SHA. - Добавить:
scripts/*-openspec-*.sh,.husky/post-checkout,post-merge,pre-push, workflows из §2,.github/pull_request_template.md, раздел «Specs / OpenSpec» вREADME.md. - В
package.json—prepareсgit submodule update --init --recursive vendor/openspec-specs, чтобыpnpm installподтягивал спецификации. - Клонирование:
git clone --recurse-submodules <url>. - После мержа изменения в спек-репозитории:
bash scripts/update-openspec-specs.shи коммит сдвига указателя (на PR это делает sync check).
Известная особенность. В OpenSpec 1.13.1openspec 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: |
В карточке пользователя SHALL быть действие «Заблокировать» по праву на управление пользователями. … Негативный путь: при отказе SHALL показываться причина, статус не меняется.
- У каждого требования минимум один сценарий и негативный путь (или явное указание, что его нет).
SHALL/MUST— в тексте требования; «желательно», «может», «should» не используются.MODIFIEDкопирует требование целиком: частичная копия теряет сценарии при архивации.- Одно поведение — одно требование; примеры и крайние случаи — в сценариях.
Формат — заголовки, длину текста, ## 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 Commits | feat(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-review | Security-ревью ветки против ветки по умолчанию |
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Глоссарий
| Термин | Значение |
|---|---|
| SDD | Spec-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 в корне репозитория |
| MCP | Model Context Protocol: подключение агента к внешним инструментам (Figma, Playwright) |