Compare commits

..
6 Commits
17 changed files with 992 additions and 290 deletions
+231 -24
View File
@@ -1,29 +1,236 @@
# Схема OpenSpec `use-case-driven` # Общие инструменты для OpenSpec и Codex
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на Репозиторий содержит три переиспользуемых артефакта:
базовой `spec-driven`. Она задаёт формат артефактов change и спецификаций
поведения; подробные правила схемы находятся в
[README схемы](openspec/schemas/use-case-driven/README.md).
## Чем отличается от `spec-driven` | Артефакт | Назначение | Где находится |
|---|---|---|
| Схема OpenSpec `use-case-driven` | Русскоязычные спецификации поведения и workflow `proposal → specs / design → tasks → apply` | [`openspec/schemas/use-case-driven/`](openspec/schemas/use-case-driven/) |
| Заготовки `AGENTS.md` и `config.yaml` с контекстом проекта | Правила OpenSpec и Git для агента, параметры проекта и навигация по постоянным документам | [`examples/project-bootstrap/`](examples/project-bootstrap/) |
| Скилл Codex `task-tracker` | Одна задача на change: привязка, метка приложения, синхронизация, учёт времени, archive и коммит | [`skills/task-tracker/SKILL.md`](skills/task-tracker/SKILL.md) |
- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`. Схема и скилл хранятся и развиваются здесь. Подключайте их символическими
Здесь используются сценарии использования без Gherkin: полные или ссылками из пользовательских каталогов; обновление клона обновляет общий
сокращённые, связанные с функциональными требованиями. источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте:
- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`. они содержат настройки конкретного приложения.
Подробные правила, устойчивые контракты и обязательные ограничения
фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`.
- Master-спецификация явно описывает `Purpose`, `Границы` ответственности
capability и полный набор `Requirements`. Delta-спецификации меняют требования
стандартными операциями OpenSpec.
- Инструкции и пояснительный текст ориентированы на русский язык; технические
идентификаторы и синтаксис OpenSpec сохраняются.
## Статус ## 1. Схема `use-case-driven`
Схема находится в стадии доработки. Описаны ещё не все типы функциональных В отличие от базовой `spec-driven`, схема описывает поведение полными или
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного сокращёнными use cases без Gherkin. Один `Requirement` задаёт завершённую
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует, функцию с одним `Scenario`; локальные `FR` фиксируют подробные правила,
что при подготовке спецификации будут выявлены все применимые требования — в устойчивые контракты и ограничения. HTTP-контракт находится в `CONTRACT`.
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно Master specs описывают `Purpose`, границы capability и требования; delta specs
учитывать при анализе изменения. используют стандартные операции OpenSpec. Технический синтаксис сохраняется,
пояснения пишутся по-русски. Подробности — в [README схемы](openspec/schemas/use-case-driven/README.md).
На macOS/Linux пользовательские схемы находятся в
`${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows —
в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан.
## 2. Заготовки проектных инструкций и конфигурации
После `openspec init` перенесите в прикладной проект нужные части
[`examples/project-bootstrap/`](examples/project-bootstrap/):
- [`AGENTS.md`](examples/project-bootstrap/AGENTS.md) — навигация по контексту,
правила OpenSpec, Git-процесс и вызовы `task-tracker` в жизненном цикле change;
- [`openspec/config.yaml`](examples/project-bootstrap/openspec/config.yaml) —
выбор схемы и начальный контекст OpenSpec;
- `openspec/context/` — индекс контекста, правила ADR и шаблон решения.
Объедините заготовки с существующими файлами, сохраняя применимые инструкции
и настройки проекта. В шаблоне `AGENTS.md` задан двухэтапный Git-процесс:
первый PR содержит только планирование OpenSpec, второй — реализацию после
слияния первого PR и явной команды владельца. Для существующего проекта
объедините эти правила с его настройками целевой ветки и ревью. Заполните
в проектном `AGENTS.md`:
```markdown
## Task Management
Для всех OpenSpec Changes используй скилл `task-tracker`.
Task tracker configuration:
- Project key: <KEY>
- Application label: <APP-NAME>
Lifecycle:
- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или
change, используй эту задачу и не создавай новую.
- При создании change без переданного ID создай или привяжи задачу после содержательного proposal.
- При существенном изменении change синхронизируй существующую задачу.
- После каждого рабочего сеанса Apply синхронизируй фактическое время.
- Перед archive выполни финальную синхронизацию; после успешной архивации
закрой задачу и закоммить изменения change. Начинай сообщение коммита с ключа
связанной задачи, затем кратко опиши изменения по-русски: `CON-27 Правка тестов`.
При ошибке archive задачу не закрывай.
- При повторном запросе возобнови незавершённую синхронизацию по существующей
связи, включая архивные changes.
Все операции управления задачами выполняй через скилл `task-tracker`.
```
`Project key` — ключ проекта в трекере, `Application label` — имя приложения,
которым маркируется каждая задача. Без обоих значений скилл не создаёт задачу.
Заполните эти значения для каждого прикладного проекта в его `AGENTS.md`.
Типовая заготовка хранится только в `examples/project-bootstrap/AGENTS.md`.
В `openspec/config.yaml` укажите `schema: use-case-driven` и дополните
предметный контекст и правила OpenSpec. Правила внешнего трекера в этот файл
не добавляются. Локальный [`openspec/config.yaml`](openspec/config.yaml)
описывает настройки самого репозитория; переносимая заготовка находится
в `examples/project-bootstrap/`.
## 3. Скилл `task-tracker`
Скилл создаёт или привязывает одну верхнеуровневую
задачу на change либо использует явно переданный ID, сохраняет метку приложения,
обновляет содержательное описание без копирования `tasks.md`, учитывает время
от Explore и коммитит изменения после успешной архивации и синхронизации задачи.
Границы компонентов:
| Компонент | Ответственность |
|---|---|
| Проектный `AGENTS.md` | Когда вызывать скилл, ключ проекта и метка приложения |
| `task-tracker` | Логические операции, связь с change и правила провайдера |
| OpenSpec | Спецификации, Change, Apply и Archive |
| MCP | Технический доступ к внешнему трекеру |
Текущая реализация использует YouTrack MCP; настройте его доступность в Codex.
Выбор поля `Labels` или YouTrack-тега, синхронизация статусов и учёт времени описаны
[в едином SKILL.md](skills/task-tracker/SKILL.md).
Для смены трекера меняйте только скилл. Перенос существующих
задач требует явного соответствия ID, чтобы не потерять историю связи.
### Связь, сохраняющаяся после archive
Источник связи — `task-tracker.yaml` внутри каталога change:
```text
openspec/changes/<change-id>/task-tracker.yaml
↓ openspec archive
openspec/changes/archive/<archive-name>/task-tracker.yaml
```
Archive переносит весь каталог, включая файл связи. После успешного переноса
закройте YouTrack-задачу и зафиксируйте относящиеся к change изменения
Git-коммитом с сообщением в формате «ключ связанной задачи + краткое описание
изменений по-русски», например `CON-27 Правка тестов`. Исходный `change_id`,
непрозрачный `task_id`, URL и снимок проектных параметров остаются в файле.
Не пытайтесь восстанавливать ID только из архивного имени: change сам может
начинаться с даты. Сохраняйте файл в Git вместе с change и архивом.
Формат и правила восстановления — в
[`SKILL.md`](skills/task-tracker/SKILL.md).
Запись содержит незавершённую операцию и журнал уже учтённого времени.
После ошибки MCP скилл проверяет внешнее состояние перед повтором. При
неизвестном результате создания или записи времени автоматический повтор
запрещён до сверки. Если задача не закрылась после archive, связь и pending
остаются в архиве для следующей сессии.
Это агентный workflow: самостоятельный запуск `openspec archive` вне Codex
переносит файл, но не вызывает скилл, не синхронизирует задачу и не создаёт
коммит. Для последующей
синхронизации попросите Codex использовать `$task-tracker` для архивного change.
При одновременной работе нескольких агентов требуется согласовать операции:
файл связи не является распределённой блокировкой.
## Подключение из домашней директории
### macOS и Linux
Замените `/path/to/openspec-schema` на абсолютный путь к своему клону:
```sh
tooling_repo="/path/to/openspec-schema"
schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas"
skills_dir="$HOME/.agents/skills"
mkdir -p "$schemas_dir" "$skills_dir"
ln -s "$tooling_repo/openspec/schemas/use-case-driven" \
"$schemas_dir/use-case-driven"
ln -s "$tooling_repo/skills/task-tracker" "$skills_dir/task-tracker"
```
Codex обнаруживает пользовательские скиллы в `~/.agents/skills` и поддерживает
ссылки на каталоги скиллов. Если новый скилл не появился, перезапустите Codex.
См. [официальную документацию о скиллах](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
### Windows PowerShell
Junction позволяет использовать исходные каталоги без копирования:
```powershell
$toolingRepo = 'D:\path\to\openspec-schema'
$schemasDir = if ($env:XDG_DATA_HOME) {
Join-Path $env:XDG_DATA_HOME 'openspec\schemas'
} else {
Join-Path $env:LOCALAPPDATA 'openspec\schemas'
}
$skillsDir = Join-Path $HOME '.agents\skills'
New-Item -ItemType Directory -Force -Path $schemasDir, $skillsDir
New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') `
-Target (Join-Path $toolingRepo 'openspec\schemas\use-case-driven')
New-Item -ItemType Junction -Path (Join-Path $skillsDir 'task-tracker') `
-Target (Join-Path $toolingRepo 'skills\task-tracker')
```
Команды предполагают, что пути назначения ещё свободны. Если схема уже
подключена, создайте только ссылку на скилл. Перед заменой существующей
папки/ссылки проверьте её содержимое и источник.
Проверьте схему из каталога прикладного проекта:
```sh
openspec schema which use-case-driven
openspec schema validate use-case-driven
```
Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex.
Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`.
Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над
пользовательской. Кроме того, схема ссылается на вспомогательные файлы
относительно проекта (`validate_format.py`, `patterns/`). Для доступа к ним
создайте в проекте ссылку `openspec/schemas/use-case-driven` на ту же общую
схему либо адаптируйте пути инструкций. Пользовательская ссылка сама
эти проектные пути не создаёт.
## Переход со старой интеграции
В прикладных проектах перенесите ключ и метку из старого `context` в
`AGENTS.md`, добавьте lifecycle из заготовки и подключите скилл. Удалите
старые инструкции трекера из `config.yaml`, включая
`operations.archive.guidance`; остальные контекст и правила сохраните.
Если схема скопирована в проект вместо ссылки, обновите также её копию.
Существующие ID/URL в proposal сохраняйте до проверенной привязки.
Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после
проверки задачи. Архивным changes без однозначной связи новую задачу
автоматически не создаёт.
## Проверки и ограничения
```sh
openspec schema validate use-case-driven
python3 -m unittest discover -s tests -v
```
Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI
во временных каталогах и проверяют сохранение связи и журнала при успешном
archive, отказе валидации и конфликте архива. Они не обращаются к трекеру;
без CLI пропускаются. Frontmatter скилла можно отдельно проверить
`scripts/quick_validate.py` из установленного `skill-creator`.
Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие
конфигурации описаны в скилле. Их внешнее выполнение требует доступного
провайдера; инструктивный скилл не даёт программных гарантий исполнения.
Для сквозной проверки используйте согласованный тестовый проект, не создавайте
тестовые задачи в рабочем проекте без согласования.
Схема продолжает развиваться: не все типы FR и форматы контрактов имеют
подробные паттерны, например FR `[UI]`. Применимые требования безопасности,
аудита и ролевой модели нужно явно учитывать при анализе изменения.
+75
View File
@@ -0,0 +1,75 @@
# Инструкции для Codex
## Навигация по контексту
- Начинай с `openspec/context/index.md`, затем читай только документы,
относящиеся к текущей задаче.
- Перед архитектурными изменениями изучай применимые ADR со статусом `Accepted`.
- Не дублируй в проектном контексте функциональные требования из
`openspec/specs/`.
- Поддерживай индекс в актуальном состоянии, когда состав документов меняется.
## OpenSpec
- Для изменений используй workflow OpenSpec Change и Apply.
- При подготовке каждого change оценивай влияние на постоянный контекст проекта
и необходимость создать или обновить ADR и другие документы.
- Если документы контекста нужно изменить, добавляй проверяемые задачи в
`tasks.md` и выполняй их в рамках Apply.
- Если change добавляет, удаляет или переименовывает документы контекста,
обновляй `openspec/context/index.md`.
- Не принимай Proposed ADR самостоятельно. При конфликте запроса с принятым ADR
явно сообщи о нём и запроси решение владельца.
## Git-процесс OpenSpec Change
- Для каждой задачи используй одну feature-ветку от целевой ветки репозитория:
`feature/<task-code>-<task-name>`. Код бери из связанной задачи, имя —
короткий ASCII slug в нижнем регистре с дефисами. Не переименовывай уже
используемую ветку вслед за переименованием задачи.
- Используй эту ветку для двух последовательных PR в одну целевую ветку.
Обычный push разрешён только в feature-ветку; прямой push в целевую ветку,
force push и изменение чужих веток запрещены.
- Первый PR содержит только артефакты планирования OpenSpec: proposal, delta
specs либо отметку `skip_specs: true`, design, tasks и связанные метаданные.
Не начинай и не публикуй реализацию до ручного слияния первого PR и
отдельной команды владельца.
- После открытия первого PR остановись. Владелец отдельно ревьюит и вручную
сливает его, сохраняя feature-ветку. Одобрение или слияние сами по себе
не разрешают продолжать: дождись явной команды владельца в этом чате.
- После команды проверь в Git, что первый PR действительно слит в целевую
ветку. Если он ещё не слит, сообщи об этом и жди. После подтверждения
обнови ту же feature-ветку из целевой и продолжай реализацию в ней.
- Второй PR содержит реализацию, применимые проверки, документацию и
обновлённые задачи OpenSpec; добавь ссылку на задачу и первый PR. Для него
требуется отдельное актуальное ревью и успешные обязательные проверки.
Оба PR вручную сливает владелец.
- После запроса правок продолжай только по явной команде владельца. Закрытый
без слияния PR останавливает процесс до отдельного решения владельца.
Автоматическое слияние и продолжение по событиям Git не используются.
## Task Management
Для всех OpenSpec Changes используй скилл `task-tracker`.
Task tracker configuration:
- Project key: <KEY>
- Application label: <APP-NAME>
Lifecycle:
- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или
change, используй эту задачу как контекст; новую задачу не создавай.
- При создании change без переданного ID создай или привяжи задачу после
содержательного proposal.
- При существенном изменении change синхронизируй существующую задачу.
- После каждого рабочего сеанса Apply синхронизируй фактическое время.
- Перед archive выполни финальную синхронизацию; после успешной архивации
закрой связанную задачу и создай коммит с изменениями change. Начинай сообщение
коммита с ключа связанной задачи, затем кратко опиши изменения по-русски:
`CON-27 Правка тестов`. При ошибке archive задачу не закрывай и коммит не создавай.
- При повторном запросе или незавершённой синхронизации возобнови работу
с существующей связью, включая архивные changes.
Все операции управления задачами выполняй через скилл `task-tracker`.
+59
View File
@@ -0,0 +1,59 @@
# Заготовки контекста проекта
Этот каталог содержит стартовые файлы для проекта, использующего схему
OpenSpec `use-case-driven`. Схема не устанавливает их автоматически. Скопируйте
`AGENTS.md` и каталог `openspec/context/` в проект с сохранением относительной
структуры и адаптируйте их к его устройству. Этот README служит инструкцией для
комплекта и не предназначен для копирования поверх README проекта.
В комплект входят:
- `AGENTS.md` — навигация по контексту, правила OpenSpec и Git-процесс
с двумя PR, вызовы `task-tracker`;
- `openspec/config.yaml` — выбор схемы и начальный контекст OpenSpec;
- `openspec/context/index.md` — карта постоянных документов проекта;
- `openspec/context/adr/README.md` — правила ведения ADR;
- `openspec/context/adr/ADR-template.md` — заготовка нового решения.
После копирования проверьте и настройте пути в индексе. Добавляйте туда
проектные документы по мере появления; не дублируйте в Context функциональные
требования из `openspec/specs/`. Перед архитектурными изменениями читайте
применимые принятые ADR.
Git-процесс из `AGENTS.md` использует одну feature-ветку для двух PR:
сначала PR с планированием OpenSpec, затем после ручного слияния и явной
команды владельца — PR с реализацией. При переносе шаблона в существующий
проект объедините этот раздел с проектными правилами ветвления и защиты
целевой ветки.
`ADR-template.md` соответствует
`openspec/schemas/use-case-driven/templates/adr.md` в этом репозитории. При
изменении исходного шаблона обновляйте его копию здесь.
После `openspec init` объедините заготовку `openspec/config.yaml` с конфигурацией
проекта, сохранив существующие настройки. Выберите `schema: use-case-driven`
и дополните предметный контекст. Настройки задач заполняйте в `AGENTS.md`:
```markdown
Task tracker configuration:
- Project key: <KEY>
- Application label: <APP-NAME>
```
Укажите ключ проекта и имя приложения, которым маркируется каждая задача. Скилл
сохраняет его в строковое поле `Labels`, если оно есть в проекте, иначе — как
точный тег YouTrack. Если
пользователь начинает Explore/Propose с переданным ID задачи, используйте эту
задачу и не создавайте новую.
Подключите общий скилл `task-tracker` по
[инструкции корневого README](../../README.md#подключение-из-домашней-директории).
Создание или привязка, содержательные обновления, учёт времени, закрытие задачи
и коммит после успешного archive выполняются по Lifecycle из `AGENTS.md`.
Сообщение коммита начинайте с ключа связанной задачи, затем кратко описывайте
изменения по-русски: `CON-27 Правка тестов`. Эти правила не нужно
добавлять в схему или `config.yaml`. Запуск OpenSpec CLI вне Codex не вызывает
скилл; для завершения внешней синхронизации обратитесь к агенту.
Заготовка не содержит готовых решений или описания бизнес-домена. ADR создаются
в проекте только для конкретных долгосрочных архитектурных решений.
@@ -0,0 +1,5 @@
schema: use-case-driven
# Дополните предметной областью и ограничениями конкретного проекта.
context: |
Постоянный контекст проекта: openspec/context/index.md.
@@ -0,0 +1,36 @@
---
status: Proposed
date: YYYY-MM-DD
decision-makers:
- <имя или роль владельца решения>
supersedes: []
superseded-by:
---
# ADR-<номер>: <Краткое название решения>
## Контекст и проблема
Какую проблему нужно решить и какие ограничения важны для выбора?
## Факторы решения
- <Требование или ограничение, влияющее на решение>
## Рассмотренные варианты
- **<Вариант>** — преимущества и недостатки.
## Решение
Какой вариант выбран и почему? Заполняется при принятии ADR; до этого раздел
может содержать предлагаемое решение.
## Последствия
- Положительные: <результаты и преимущества>.
- Отрицательные или компромиссы: <цена решения, ограничения, риски>.
## Связанные решения
- <ID и ссылка на связанные ADR, если есть>
@@ -0,0 +1,24 @@
# Архитектурные решения
Храни принятые и исторические решения в этом каталоге. Создавай ADR для
долгосрочных архитектурных решений, которые влияют на будущую разработку;
не создавай ADR для каждого change или временной детали реализации.
## Именование и статусы
- Имя файла: `ADR-<номер>-<краткое-описание>.md`, например
`ADR-0001-use-postgresql.md`.
- Используй четырёхзначную последовательную нумерацию. Следующий номер на
единицу больше максимального; номера не переиспользуются.
- Используй статусы `Proposed`, `Accepted`, `Rejected` и `Superseded`.
- ADR становится действующим только после явного принятия владельцем решения.
- Отклонённые и заменённые ADR сохраняй как историю.
Перед архитектурным изменением читай применимые ADR со статусом `Accepted`.
При пересмотре принятого решения создай новый ADR, укажи заменяемый ID в
`supersedes`, а в прежнем ADR — новый ID в `superseded-by`. Не меняй принятое
решение задним числом.
Новый ADR создавай из `ADR-template.md` как задачу OpenSpec Change. Добавь в
`tasks.md` отдельную задачу на его создание со статусом `Proposed`; не принимай
решение самостоятельно.
@@ -0,0 +1,17 @@
# Индекс проектного контекста
Используй этот файл как карту постоянных знаний проекта. Сначала определи по
задаче нужные документы и загружай их выборочно. Обновляй индекс при добавлении,
удалении или переименовании документов.
| Путь | Назначение | Когда читать |
| --- | --- | --- |
| `../../README.md` | Обзор проекта и инструкции по запуску | При знакомстве с проектом или изменении его назначения |
| `../../AGENTS.md` | Правила работы Codex и навигации по контексту | В начале работы над задачей |
| `adr/README.md` | Правила оформления, принятия и замены ADR | При подготовке или пересмотре ADR |
| `adr/ADR-template.md` | Заготовка нового архитектурного решения | При создании ADR |
| `adr/ADR-[0-9][0-9][0-9][0-9]-*.md` | Архитектурные решения проекта | Перед архитектурными изменениями — читай только применимые принятые решения |
Добавляй сюда другие документы постоянного контекста с кратким назначением и
условием чтения. Не переноси сюда функциональные требования: актуальные
требования находятся в `../specs/`, а планы изменений — в `../changes/`.
-8
View File
@@ -1,13 +1,5 @@
schema: use-case-driven schema: use-case-driven
context: |
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
Proposed; не помечай решение Accepted без явного принятия владельцем решения.
rules: rules:
tasks: tasks:
- >- - >-
+31 -5
View File
@@ -5,12 +5,20 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему. с явно указанной `schema: spec-driven` продолжают использовать свою схему.
## Git-процесс проекта
Схема задаёт порядок и формат OpenSpec-артефактов. Правила веток, двух
последовательных PR, ручного слияния и явной команды продолжения находятся
в [шаблоне проектных инструкций](../../../examples/project-bootstrap/AGENTS.md).
При подключении схемы включите правила из этого шаблона в проектный
`AGENTS.md` и согласуйте имя целевой ветки с настройками репозитория.
## Уровни спецификации ## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности. - Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - Scenario — один из двух форматов Use case: полный или сокращённый. Формат определяется сложностью сценария, независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- FR — подробные правила и контракты сообщений за пределами Scenario; - FR — подробные правила и контракты сообщений за пределами Scenario;
контракт HTTP endpoint размещается в завершающем CONTRACT. контракт HTTP endpoint размещается в завершающем CONTRACT.
@@ -68,8 +76,11 @@ Markdown-рендерер автоматически создаёт якоря
## Форматы Use case ## Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания. - Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий.
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case. - Сокращённый Use case используй для простых коротких требований. Рассматривай их как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
- Выбирай формат по сложности: не используй полный Use case для простых требований, а сокращённый — для объёмных многошаговых сценариев. Правило действует и для HTTP endpoint.
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращённый Use case содержит только Основной поток; каждый шаг ссылается на FR.
```text ```text
#### Scenario: Сокращенный use case: описание функции #### Scenario: Сокращенный use case: описание функции
@@ -106,8 +117,8 @@ FR задаёт тексты, дальнейшие действия и связ
## HTTP-контракт в Requirement ## HTTP-контракт в Requirement
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный Каждый endpoint оформляется отдельным Requirement. Формат Use case выбирается
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце по сложности сценария; сложные правила шагов выносятся в FR. После всех FR, в конце
Requirement, размещается раздел CONTRACT с подразделами Request и Response. Requirement, размещается раздел CONTRACT с подразделами Request и Response.
В Request указываются один HTTP-метод и путь, тело и query-параметры. В В Request указываются один HTTP-метод и путь, тело и query-параметры. В
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
@@ -151,6 +162,21 @@ Scenario в таких операциях не создаётся. В delta со
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
Форматирование спецификации само по себе не реализует этот контракт в приложении. Форматирование спецификации само по себе не реализует этот контракт в приложении.
## Постоянный контекст проекта
Для начальной настройки проекта можно скопировать заготовки из
[`examples/project-bootstrap/`](../../../examples/project-bootstrap/):
`AGENTS.md`, `openspec/context/index.md` и инструкции с шаблоном ADR. Они не
устанавливаются вместе с пользовательской ссылкой на схему и должны быть
адаптированы к структуре конкретного проекта.
При подготовке каждого change оценивай влияние на постоянный контекст в разделе
`Project Context` файла `proposal.md`. Если индекс контекста существует, изучай
релевантные документы выборочно. В design сверяй необходимость ADR и других
документов; задачи на их создание или обновление, включая актуализацию индекса,
добавляй в `tasks.md`. Выполняй эти задачи в рамках OpenSpec Apply. Не переноси
функциональные требования из Specs в Context.
## Архитектурные решения (ADR) ## Архитектурные решения (ADR)
Храни ADR проекта в `openspec/context/adr/` и называй файлы Храни ADR проекта в `openspec/context/adr/` и называй файлы
@@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич
## HTTP endpoint ## HTTP endpoint
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
правила обработки указываются в FR, а контракт помещается в самом конце по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
Requirement: Requirement:
```markdown ```markdown
+169 -245
View File
@@ -10,72 +10,58 @@ artifacts:
description: Начальный документ предложения, описывающий изменение description: Начальный документ предложения, описывающий изменение
template: proposal.md template: proposal.md
instruction: | instruction: |
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
OpenSpec и технические идентификаторы, названия API, файлов, идентификаторы, названия API, файлов, инструментов, команды и коды не переводи.
инструментов, команд и коды без перевода.
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение. Объясни, ПОЧЕМУ требуется изменение. Объём — 1–2 страницы; детали
реализации относятся к design.md.
Разделы: Разделы:
- **Why**: 1–2 предложения о проблеме или возможности. Какую проблему - **Why**: 1–2 предложения о проблеме или возможности и причинах изменения сейчас.
решает изменение? Почему его нужно сделать сейчас? - **What Changes**: Точный список новых возможностей, изменений и удалений;
- **What Changes**: Список изменений. Точно опиши новые возможности, несовместимые изменения помечай **BREAKING**.
изменения и удаления. Помечай несовместимые изменения как **BREAKING**. - **Capabilities**: Создаваемые или изменяемые спецификации отдельных
- **Capabilities**: Укажи, какие спецификации будут созданы или изменены: бизнес-функций или понятных результатов. Сохраняй полный иерархический
Capability представляет отдельную бизнес-функцию или понятный результат; путь, например `domain/capability-name`.
сохраняй полный иерархический путь, например `domain/capability-name`. Короткий читаемый префикс Requirement для новой capability: первые три буквы однословного
Для новой capability сформируй короткий читаемый префикс Requirement: сегмента или первые буквы частей сегмента с дефисами; верхний регистр,
для однословного сегмента используй первые три буквы, для сегмента с точки и порядок сегментов (`domain/capability-name` → `DOM.CN`).
дефисами — первые буквы его частей. Приводи сокращения к верхнему Проверь уникальность префикса по Requirement ID основных спецификаций;
регистру, разделяй сегменты кода точкой и сохраняй их порядок: при совпадении удлиняй сокращения новых сегментов до уникальности. Существующие префиксы
`domain/capability-name` → `DOM.CN`. не меняй, включая переименование capability.
Перед назначением проверь уникальность префикса по Requirement ID в - **New Capabilities**: Перечисли новые capabilities; для каждой создай
основных спецификациях проекта. Если префикс занят, удлиняй сокращения `specs/<capability-path>/spec.md`; новые сегменты пиши в `kebab-case`,
новых сегментов до уникальности; уже используемые префиксы не меняй. следуя структуре проекта.
Сохраняй префикс при переименовании capability. - **Modified Capabilities**: Укажи существующие capabilities только при
- **New Capabilities**: Перечисли добавляемые capabilities. Для каждой изменении описанного поведения, а не деталей реализации. Создай delta
создай `specs/<capability-path>/spec.md`. Используй `kebab-case` для spec по точному существующему пути внутри `openspec/specs/`; если
новых сегментов пути (например, `user-auth` или `identity/user-auth`) требования не меняются, оставь список пустым.
и следуй принятой в проекте структуре спецификаций. - **Impact**: Затронутые код, API, зависимости и системы.
- **Modified Capabilities**: Перечисли существующие capabilities, чьи - **Project Context**: Создаваемые или обновляемые постоянные документы,
REQUIREMENTS меняются. Добавляй сюда capability только при изменении включая решение о необходимости ADR. Отсутствие изменений укажи явно.
поведения, описанного в спецификации, а не только деталей реализации.
Для каждой создай delta spec по точному существующему пути внутри
`openspec/specs/`. Оставь список пустым, если требования не меняются.
- **Impact**: Затронутые участки кода, API, зависимости и системы.
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs. Перед заполнением Capabilities изучи существующие specs:
Перед его заполнением изучи существующие спецификации: выполни 1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes.
`openspec list --specs`, чтобы получить список capabilities проекта. 2. Для подходящих вариантов — `openspec show "<spec-id>" --type spec --json --no-scenarios`:
Для подходящих вариантов выполни `openspec show "<spec-id>" --type spec --json --no-scenarios`. обзор назначения и требований без загрузки целых спецификаций.
Команда вернёт назначение capability и тексты требований, не загружая 3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком,
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам включая сценарии: `openspec show "<spec-id>" --type spec`.
только для зарегистрированного отдельного хранилища и сохраняй Добавляй `--store "<id>"` к этим командам только для зарегистрированного
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя, отдельного хранилища. Сохраняй `--type spec`, чтобы избежать неоднозначности
без этого параметра возникнет неоднозначность при выборе. Команда при одинаковых именах change и spec. Используй точный путь существующей
`openspec list` без `--specs` показывает активные изменения (`changes`), capability, не создавай похожее имя. Каждой перечисленной capability
а не спецификации, поэтому не отражает уже описанное в проекте поведение. соответствует файл спецификации.
Используй точный путь
существующей capability, не создавай похожее имя.
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
описано и что нужно изменить, прочитай каждую подходящую спецификацию
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
(с тем же правилом для `--store`). Для каждой перечисленной capability
потребуется соответствующий файл спецификации.
В каждом изменении (`change`) должна быть указана хотя бы одна новая или Change должен содержать новую/изменяемую capability либо `skip_specs: true`
изменяемая capability либо явный отказ от спецификаций: `openspec validate` в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta.
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не `skip_specs: true` допустим только без изменения описанного поведения
задано `skip_specs: true`. (чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки.
Используй `skip_specs: true` только когда поведение, описываемое
спецификациями, не меняется (например, при чистом рефакторинге, изменении
инструментов или документации). Не добавляй требование только ради
прохождения проверки.
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на Для Project Context прочитай существующий `openspec/context/index.md` и
способе реализации: детали реализации относятся к design.md. относящиеся к change документы из него. Не копируй функциональные требования
Specs в Context. Отсутствующий индекс включай в scope только при введении
постоянных документов контекста или принятии проектом этой навигационной модели.
Этот документ задаёт основу: на нём строятся specs, design и tasks.
requires: [] requires: []
- id: specs - id: specs
@@ -83,141 +69,113 @@ artifacts:
description: Подробные спецификации изменения description: Подробные спецификации изменения
template: spec.md template: spec.md
instruction: | instruction: |
Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные Пиши пояснения по-русски; обязательные заголовки OpenSpec, идентификаторы,
заголовки OpenSpec, идентификаторы, названия API и коды без перевода. названия API и коды не переводи.
Создай спецификации наблюдаемого поведения и устойчивых контрактов. Описывай наблюдаемое поведение и устойчивые контракты в формате без Gherkin.
Правила ниже применяются к основным спецификациям и к полным блокам Правила применяются к основным specs и полным блокам ADDED/MODIFIED в delta.
ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin.
Иерархия и границы: Иерархия и границы:
- Capability описывает отдельную бизнес-функцию или понятный результат. - Capability — отдельная бизнес-функция или понятный результат; сохраняй
- Сохраняй полный иерархический путь, например domain/capability-name. полный иерархический путь, например domain/capability-name.
- Основная спецификация содержит раздел ## Границы между Purpose и - Основная спецификация содержит раздел ## Границы между Purpose и
Requirements. Кратко укажи, за что отвечает capability, что входит в её Requirements: кратко укажи ответственность, область, исключения и владельцев
область и что находится за её пределами или относится к другой capability соседних обязанностей — другие capabilities или приложения. Не дублируй
либо приложению. Не дублируй Requirements и FR. Requirements и FR; сведения об ответственности допустимы без задания поведения.
- Один Requirement описывает одну завершённую техническую функцию. - Requirement — одна завершённая техническая функция, стабильный ID вида
- Не дроби один процесс на Requirements для чтения, валидации и записи. AREA.CAP-01 и ровно один Scenario. Не дроби процесс на чтение, валидацию и запись.
- Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario. - Префикс — сокращения сегментов пути capability через точки; проверяй
- Префикс Requirement состоит из сокращений сегментов пути capability, уникальность по ID основных specs. Номер уникален внутри capability;
разделённых точками; его уникальность проверяется по ID в основных
спецификациях. Номер Requirement уникален внутри capability. Существующие
унаследованные Requirements могут сохранять прежние ID. унаследованные Requirements могут сохранять прежние ID.
- Заголовки OpenSpec: ### Requirement: и #### Scenario:. - Заголовки OpenSpec: ### Requirement: и #### Scenario:.
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат. - Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
- В Requirements и FR включай только сведения, меняющие наблюдаемое - В Requirements и FR оставляй только наблюдаемое поведение, устойчивые
поведение, устойчивый контракт или обязательное техническое ограничение. контракты и обязательные технические ограничения. Удаляй повторы и
Удаляй повторы, пояснения и формулировки, которые не меняют поведение и пояснения, не влияющие на поведение и не снимающие неоднозначность контракта.
не снимают неоднозначность контракта. В ## Границы оставляй краткие
сведения об ответственности и владении, необходимые для понимания
области capability, даже если они сами по себе не задают поведение.
Scenario: Scenario:
- Поддерживаются два формата сценария использования: полный и - Выбирай формат по сложности сценария, независимо от типа FR и части системы
сокращённый. Автор выбирает формат по ситуации, независимо от типа FR (процесс, БД, API, UI и другие).
и описываемой части системы: процесса выполнения, БД, API, UI и других. - Полный Use case используй для крупных многошаговых сценариев с большим
- Полный сценарий использования содержит разделы Участники, Предусловия, количеством последовательных действий, а не для простых коротких требований.
- Сокращённый Use case используй для простых коротких требований, а не для
объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты
на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
- Полный сценарий содержит разделы Участники, Предусловия,
Основной поток, Альтернативы и ошибки, Результат, Коды завершения — Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
в таком порядке. в таком порядке.
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`; - Сокращённый сценарий содержит только `##### Основной поток`, без других
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на FR.
участников, предусловий, альтернатив и ошибок, результата или кодов - В обычном сценарии Назначение опционально: добавляй только сведения,
завершения и не задаёт отдельные ветвления во время выполнения. которых нет в заголовке. Контекст отсутствует.
- В обычном сценарии Назначение опционально; добавляй только если оно
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем». - Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
- Шаг сценария выполнения может назвать действие, конечную точку API или - В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR.
способ записи и сослаться на FR. - Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария
- Каждую конечную точку HTTP описывай в отдельном Requirement с полным выбирай по его сложности.
сценарием использования. Сложные правила шагов выноси в FR со ссылками из сценария.
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
- Основной поток и альтернативы обычного сценария включают коды - Основной поток и альтернативы обычного сценария включают коды
завершения, если они определены для этой функции. завершения, если они определены для этой функции.
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты - Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
сообщений и дальнейшая логика располагаются за пределами Scenario. сообщений и дальнейшая логика располагаются за пределами Scenario.
- Единственная таблица Scenario — Коды завершения с колонками - Единственная таблица Scenario — Коды завершения с колонками
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE. Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
- Код сам сообщает смысл итога; дополнительный этап или свободный текст - Код сам сообщает смысл итога без дополнительного этапа или свободного текста.
не должен требоваться для понимания кода. События промежуточных шагов Промежуточные события не являются кодами завершения; не создавай код для каждой диагностики.
не являются кодами завершения. Не создавай код для каждой диагностики. - Каждый код ссылается на локальные FR с дальнейшей логикой, текстом или правилами результата.
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
логику, текст или применимые правила результата.
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков - Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
содержательного текста без адресов Markdown-ссылок. содержательного текста без адресов Markdown-ссылок.
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT. - Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
Функциональные требования: Функциональные требования:
- После Scenario, на уровне ####, идёт раздел Функциональные требования. - После Scenario идёт `#### Функциональные требования` с заголовками
- Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее. `##### <requirement-id>.FR-NN [метка]: <название>`; метка опциональна.
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN. Локальная нумерация начинается с FR-01 в каждом Requirement.
Номер начинается с FR-01 в каждом Requirement. - FR — отдельное понятное правило или связанный контракт;
- FR содержит отдельное понятное правило или связанный контракт; не дроби не дроби связную логику на множество атомарных FR.
связную логику на множество атомарных FR. - FR без метки — логика, правила или последовательность шагов.
- Обычный FR без метки описывает логику, правила или последовательность Метки [DB], [API], [UI] ставь сразу после ID; они не входят в ID и не меняют slug.
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API] - [DB] — структура БД; для таблицы следуй
или [UI]; метка не входит в ID и не меняет slug ссылки.
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
контракт сообщения или технического лога. Контракт конечной точки HTTP
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
UI; детальный паттерн будет добавлен отдельно.
- Для FR [DB] с таблицей БД следуй паттерну
`openspec/schemas/use-case-driven/patterns/database-table.md`. `openspec/schemas/use-case-driven/patterns/database-table.md`.
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну - [API] — контракт сообщения или технического лога; сериализуемое сообщение
`openspec/schemas/use-case-driven/patterns/message-contract.md`. оформляй по `openspec/schemas/use-case-driven/patterns/message-contract.md`.
- Контракт конечной точки HTTP не оформляй отдельными FR. После раздела - [UI] — требования к UI; детальный паттерн будет добавлен отдельно.
Функциональные требования добавляй завершающий раздел CONTRACT с - HTTP-контракт размещай после Функциональных требований в завершающем
подразделами Request и Response в таком порядке. В Request указывай CONTRACT, не в отдельных FR. Подразделы — Request, затем Response.
один HTTP-метод и путь; для отсутствующего тела явно отмечай это. В Request указывай один HTTP-метод и путь, явно отмечай отсутствие тела.
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md. Таблицы тела запроса и ответа оформляй по message-contract.md.
- В таблице Response раздела CONTRACT укажи для каждого поля источник - В response-таблицах для каждого поля укажи источник или правило формирования:
значения или правило его формирования в последней колонке. в последней колонке CONTRACT и в «Формирование значения» для FR [API].
- В таблице ответа контракта FR [API] укажи для каждого поля источник - Не добавляй HTML-якоря <a id="..."></a>; используй Markdown-якоря заголовков.
значения или правило его формирования в колонке «Формирование значения». - Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка,
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
якоря из заголовков Requirement и FR.
- Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его
заголовка, например
[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID
используется и для ссылки внутри Requirement, и для ссылки на другой
Requirement.
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
- Сохраняй существующие ID. При изменении FR сохраняй его номер; - Сохраняй существующие ID. При изменении FR сохраняй его номер;
новые FR добавляй в конец. Порядок первого документа последовательный. новые FR добавляй в конец. Порядок первого документа последовательный.
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие - Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия,
сообщения/действия, если это часть контракта. Параметры сообщений если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода.
являются данными, а не скрытым значением кода. - При отличии смыслового кода от текущего поведения явно опиши в FR соответствие
- Если смысловой код спецификации отличается от текущего поведения системы, и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением.
явно опиши соответствие и статус реализации в FR. Не утверждай,
что новый код или текст уже возвращается приложением.
Работа с OpenSpec: Работа с OpenSpec:
- Создай specs/<capability-path>/spec.md для каждой capability из proposal. - Создай specs/<capability-path>/spec.md для каждой capability из proposal.
- Основная спецификация следует краткой схеме templates/main-spec.md; это формат- - Основная spec: Purpose, ## Границы и полный актуальный набор Requirements.
ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы Ориентир формата — templates/main-spec.md, не генерируемый артефакт.
и полный актуальный набор Requirements.
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements, - Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements. ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
- Для новой capability delta-спецификация начинается с ## Purpose - Для новой capability начинай delta с ## Purpose (не менее 50 знаков);
(не менее 50 знаков). Для существующей capability Purpose в delta не добавляй. для существующей Purpose не добавляй.
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR. - MODIFIED содержит полный Requirement: ID, один Scenario и все FR;
Его заголовок должен совпадать с заголовком соответствующего Requirement заголовок совпадает с соответствующим Requirement основной spec.
в основной спецификации.
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO. - В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
Это операции над требованиями, не сценарии технических функций. Это операции над требованиями, не сценарии технических функций.
- При копировании блоков в delta сохраняй ID Requirements, номера и - В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками.
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в Для ссылок на неизменённый Requirement основной spec проверяй delta
неизменённый Requirement основной спецификации, проверяй delta с с `--base <master-spec>`.
`--base <master-spec>`. - Без изменения поведения (чистое форматирование, инструменты, рефакторинг)
- Не создавай delta для чистого форматирования, изменений инструментов используй `skip_specs: true`, не создавай delta.
или рефакторинга. Для изменения без изменения поведения используй - Проверки: `openspec schema validate use-case-driven`; для spec —
`skip_specs: true`. `openspec validate` и `python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids <spec-path>`.
- Проверь schema через openspec schema validate use-case-driven. Для неизменённых specs со старыми ID флаг не нужен. OpenSpec не проверяет все правила формата.
- Проверь spec через openspec validate и отдельно через
python3 openspec/schemas/use-case-driven/validate_format.py
--require-qualified-ids <spec-path>. Для неизменённых спецификаций
со старыми ID этот флаг не нужен.
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
requires: requires:
- proposal - proposal
@@ -226,59 +184,38 @@ artifacts:
description: Техническое описание решения и деталей реализации description: Техническое описание решения и деталей реализации
template: design.md template: design.md
instruction: | instruction: |
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
OpenSpec и технические идентификаторы, названия файлов, инструментов идентификаторы, названия файлов, инструментов и команды не переводи.
и команд без перевода.
Создай документ design, объясняющий, КАК реализовать изменение. Design объясняет, КАК реализовать изменение: архитектуру и подход, не пошаговый код.
Когда добавлять design.md (достаточно любого из условий): Добавляй design.md при любом из условий:
- Изменение затрагивает несколько сервисов или модулей либо вводит новый - Несколько сервисов/модулей или новый архитектурный подход.
архитектурный подход. - Внешняя зависимость или существенное изменение модели данных.
- Добавляется внешняя зависимость или существенно меняется модель данных. - Сложности безопасности, производительности или миграции.
- Есть сложность, связанная с безопасностью, производительностью или - Технические решения для устранения неоднозначности до разработки.
миграцией.
- До начала разработки нужно принять технические решения, чтобы устранить
неоднозначность.
Разделы: Разделы:
- **Context**: Только текущее состояние и ограничения, необходимые для - **Context**: Только текущее состояние и ограничения для объяснения подхода.
объяснения подхода. Причины изменения смотри в proposal, не повторяй их - **Goals / Non-Goals**: Что решение обеспечивает и исключает; границы решения без повтора scope proposal.
(например: «См. proposal.md — Why»). - **Decisions**: Ключевые технические решения, их обоснование и рассмотренные альтернативы.
- **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает. - **Risks / Trade-offs**: Ограничения и проблемы в формате [Риск] → [Меры снижения].
Не повторяй область работ из proposal; указывай только границы решения. - **Migration Plan**: Развёртывание и откат, если применимо.
- **Decisions**: Ключевые технические решения и их обоснование: почему - **Open Questions**: Только безопасно отложенные вопросы, не влияющие на
выбран один вариант вместо другого. Укажи рассмотренные альтернативы. specs, подход или состав задач. При отсутствии вопросов раздел не добавляй.
- **Risks / Trade-offs**: Известные ограничения и возможные проблемы. Влияющие вопросы выясни с пользователем сейчас, не подменяй ответ предположением.
Формат: [Риск] → [Меры снижения].
- **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо.
- **Open Questions**: Неизвестные, которые можно безопасно выяснить позже,
не меняя спецификации, подход или состав задач. Не добавляй, если таких
вопросов нет.
Открытые вопросы предназначены для действительно отложенных решений, а не Вместо повтора причин и состава изменения ссылайся на proposal, вместо
для пропущенных решений. Если ответ может изменить спецификации, выбранный копирования требований — на specs, используя Requirement ID и локальные FR.
подход или состав задач, выясни его сейчас: спроси пользователя, а не
делай предположение.
Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода. Сверь Project Context proposal с design: нужны ли новые/обновлённые постоянные
В proposal описаны причины и состав изменения, в design — способ документы и индекс? В Context ссылайся на требования Specs без дублирования.
реализации. Ссылайся на proposal для обоснования и на specs для требований;
если раздел только повторяет их, дай ссылку вместо повтора.
Ссылайся на Requirement ID и локальные FR; описывай решения реализации Перед проектированием прочитай применимые принятые ADR в `openspec/context/adr/`
без копирования требований. и укажи ID в Decisions. Для долгосрочного архитектурного решения или замены
принятого запланируй новый ADR по `openspec/schemas/use-case-driven/templates/adr.md`
Перед проектированием прочитай применимые принятые ADR из со статусом Proposed; самостоятельно не принимай его. Конфликт с действующим
`openspec/context/adr/` и укажи их идентификаторы в Decisions. Если ADR явно опиши и получи решение пользователя до выбора расходящегося подхода.
изменение принимает долгосрочное архитектурное решение или заменяет
принятое решение, запланируй создание нового ADR по шаблону
`openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed.
Не помечай ADR принятым самостоятельно. Если запрос противоречит
действующему ADR, явно опиши конфликт и запроси решение пользователя до
выбора расходящегося подхода.
Хороший design объясняет причины технических решений.
requires: requires:
- proposal - proposal
@@ -287,57 +224,41 @@ artifacts:
description: Контрольный список задач с отслеживаемым выполнением description: Контрольный список задач с отслеживаемым выполнением
template: tasks.md template: tasks.md
instruction: | instruction: |
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные Пиши группы и задачи по-русски; обязательные идентификаторы, пути файлов,
идентификаторы, пути файлов, названия API, коды и команды без перевода. названия API, коды и команды не переводи.
Создай список задач, разбивающий работу по реализации на части. Разбей реализацию на задачи по specs (что создать) и design (как реализовать).
Перед составлением задач проверь Open Questions в design.md. Если ответ на Проверь Open Questions в design.md: влияющие на результат вопросы сначала
какой-либо вопрос повлияет на результат разработки, сначала обсуди его с обсуди с пользователем; не закладывай неоговорённые предположения.
пользователем; не закладывай в список задач неоговорённые предположения.
**ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по Следуй шаблону: apply отслеживает только чекбоксы. Только `x` внутри скобок
формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным означает выполнение независимо от регистра и пробелов; любая другая отметка,
независимо от регистра и пробелов; например, `- [ x]` тоже означает включая пустые скобки, считается незавершённой. Строки без чекбокса не отслеживаются.
выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`,
считается незавершённой. Строки без чекбокса вообще не отслеживаются.
Правила: Правила:
- Группируй связанные задачи под нумерованными заголовками `##`. - Группируй связанные задачи под нумерованными заголовками `##`.
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`. - Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
- Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию. - Каждая задача выполнима за одну сессию; порядок соответствует зависимостям.
- Располагай задачи в порядке зависимостей: сначала то, что нужно сделать - В описание каждого чекбокса включай проверку: тест, команду, наблюдаемое
раньше. поведение или готовый артефакт. Отдельная задача проверки допустима только
- Для каждой задачи укажи способ проверки выполнения: тест, команду, для интеграционных/системных сценариев, охватывающих несколько задач реализации.
наблюдаемое поведение или готовый артефакт. Добавь проверку в описание
чекбокса. Выноси проверку в отдельную задачу только для интеграционных
или системных сценариев, охватывающих несколько задач реализации.
Пример: Пример:
``` ```
# Tasks - [ ] 1.1 Реализовать экспорт данных и проверить прохождение теста экспорта
## 1. Подготовка
- [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов
- [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки
## 2. Основная реализация
- [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта
- [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами
``` ```
Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это Связывай задачи с Requirement ID, FR и кодами завершения, если они затронуты.
реализовать.
Связывай задачи с Requirement ID, FR и кодами завершения, если задача Для нового или заменяющего ADR из design добавь отдельную задачу создания
затрагивает эти результаты. в `openspec/context/adr/` со статусом Proposed. При замене принятого решения
свяжи новый и прежний ADR полями `supersedes` и `superseded-by`.
Если в design предусмотрен новый или заменяющий ADR, включи в tasks Если proposal/design предусматривает создание/обновление постоянных документов
отдельную задачу на его создание в `openspec/context/adr/` со статусом контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md`
Proposed. При замене принятого решения свяжи новый и прежний ADR через при изменении состава документов; отсутствующий индекс создавай только
поля `supersedes` и `superseded-by`. при введении постоянных документов контекста или принятии проектом этой навигационной модели.
requires: requires:
- specs - specs
- design - design
@@ -347,5 +268,8 @@ apply:
tracks: tasks.md tracks: tasks.md
instruction: | instruction: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или выполненными по мере работы, включая задачи по обновлению проектного
потребуется уточнение. контекста и его индекса. Если индекс существует или его создание входит в
tasks.md, проверь, что он соответствует фактическому набору документов.
Убедись, что требования Specs не продублированы в Context.
Остановись, если столкнёшься с препятствием или потребуется уточнение.
@@ -27,3 +27,9 @@
## Impact ## Impact
<!-- Затронутые код, API, зависимости и системы --> <!-- Затронутые код, API, зависимости и системы -->
## Project Context
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
создать или обновить. Если обновления не нужны, напиши это явно.
Не переноси сюда функциональные требования из OpenSpec Specs. -->
@@ -20,6 +20,12 @@
Система SHALL <наблюдаемый результат завершённой функции>. Система SHALL <наблюдаемый результат завершённой функции>.
<!-- Выбирай формат по сложности сценария, независимо от типа FR и части системы.
Полный Use case используй для крупных многошаговых сценариев; сокращённый —
для простых коротких требований. Такие требования — кандидаты на выделение
в отдельные Requirements для переиспользования в сценариях других Requirements.
Не используй полный формат для простых требований, а сокращённый — для объёмных. -->
#### Scenario: <название завершённого процесса> #### Scenario: <название завершённого процесса>
##### Участники ##### Участники
@@ -69,7 +75,7 @@ HTTP endpoint располагай в завершающем разделе CONT
<При необходимости — параметры сообщений, связанные требования и соответствие <При необходимости — параметры сообщений, связанные требования и соответствие
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.> действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case. <!-- HTTP endpoint описывай в отдельном Requirement; формат Use case выбирай по сложности.
Контракт размещай в конце Requirement, не разбивая request/response на FR: Контракт размещай в конце Requirement, не разбивая request/response на FR:
#### CONTRACT #### CONTRACT
@@ -87,9 +93,7 @@ HTTP status: <код и условие возврата>.
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> | | `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
--> -->
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от <!-- Для сокращённого Use case замени полный Scenario следующим блоком:
типа FR и предмета описания. Для сокращенного Use case используй только основной
поток и ссылки на FR:
#### Scenario: Сокращенный use case: <предмет описания> #### Scenario: Сокращенный use case: <предмет описания>
@@ -417,8 +417,6 @@ def check_requirement(
scenario, details = block.split("#### Функциональные требования", 1) scenario, details = block.split("#### Функциональные требования", 1)
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1] scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
if has_contract: if has_contract:
if is_short_use_case:
errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case")
details, contract_content = details.split("#### CONTRACT", 1) details, contract_content = details.split("#### CONTRACT", 1)
errors.extend(check_http_endpoint_contract(contract_content)) errors.extend(check_http_endpoint_contract(contract_content))
sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE) sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE)
+127
View File
@@ -0,0 +1,127 @@
---
name: task-tracker
description: Веди задачу YouTrack при работе с OpenSpec Change, сохраняй связь после archive и учитывай фактическое время.
---
# Task Tracker
Одна верхнеуровневая задача на change; без подзадач и копирования `tasks.md`.
Используй YouTrack MCP по текущим контрактам инструментов.
Если пользователь передал ID задачи для начала Explore/Propose или работы над
change, начинай с контекста этой задачи и используй её; новую задачу не создавай.
Переданная задача может иметь любой тип: сохраняй её `Type` и не отклоняй
задачу из-за его значения.
## Настройки и связь
Читай `Project key` и `Application label` из применимого `AGENTS.md`.
Способ хранения метки определяй по схеме полей проекта: используй строковое
custom field `Labels`, если оно есть; иначе используй точный тег YouTrack.
Не записывай значение одновременно в поле и тег. Отсутствующие значения,
placeholders или конфликт настроек требуют уточнения.
Если в переданной задаче нужной метки нет, добавляй её автоматически без запроса
подтверждения; после записи проверь результат через `get_issue`.
Храни `task-tracker.yaml` в каталоге change реального OpenSpec store,
включай в Git: archive переносит файл вместе с change.
```yaml
version: 1
change_id: improve-validation
project_key: EXAMPLE
application_label: order-service
task_id: null
task_url: null
sync: {pending: null, last_error: null}
worklog:
- {id: session-1, date: '2026-10-14', minutes: 25, description: Explore, status: pending}
```
`change_id` сохраняет исходный ID, `task_id` непрозрачен, URL берётся из ответа.
Перед изменениями YouTrack сохраняй `sync.pending`: `create`, `update` или `close`;
очищай вместе с `last_error` после проверки всей операции, включая тег и время.
Записывай атомарно, сохраняя неизвестные поля; разрешай конфликты записей до вызовов.
## Жизненный цикл
1. **Найди:** приоритет у явно переданного пользователем ID, затем у связи
в активном каталоге/архиве по точному `change_id`, старых ссылок proposal
и результатов поиска. Для переданного ID сразу вызови `get_issue`; проверь
существование задачи, проект и отсутствие `subtask of`. Используй её
как авторитетную связь для этого запроса, даже если локальная связь отсутствует
или содержит прежний ID; прежнюю задачу не обновляй. Если ID не существует
или не подходит по проекту, остановись и сообщи об этом — замену не создавай.
Для остальных найденных задач через `get_issue` проверь принадлежность change,
проект и отсутствие `subtask of`.
Без ID ищи `search_issues` по проекту и маркеру
`OpenSpec Change: <application-label>/<change-id>`; для старых задач также slug.
Проверь кандидатов, все страницы, открытые и закрытые задачи.
Неоднозначность требует уточнения; ошибка чтения/поиска, включая 404,
не разрешает создание замены.
2. **Создай/привяжи:** если пользователь передал ID, привяжи эту задачу до
Explore/Propose и используй её описание как исходный контекст; `create_issue`
запрещён для этого запроса. Иначе, после содержательного proposal и до
specs/design/tasks (включая `skip_specs`), привяжи найденную задачу или создай
новую только для активного change после полного поиска без результатов и
незавершённых попыток.
Через `get_project` и `get_issue_fields_schema` проверь проект и обязательные
поля. `Type: Task` задавай только при создании новой задачи; у существующей
задачи сохраняй её тип. Сверь схему проекта с правилом выбора способа хранения
в разделе «Настройки и связь».
`create_issue`: русский заголовок по proposal и блок описания из шага 3,
без родителя. Если найдено строковое поле `Labels`, передай в `customFields`
точное значение `Application label`; если поля нет, добавь точный тег через
`manage_issue_tags`. Сразу сохрани ID/URL и проверь через `get_issue`, что
метка записана выбранным способом.
Для существующей задачи сначала прочитай поле/теги через `get_issue`.
Если точная метка уже есть — не меняй её. Если её нет, добавь без вопроса:
пустое поле `Labels` заполни значением `Application label`; в непустое строковое
поле допиши `, <Application label>`, сохранив прежний текст и не дублируя значение.
Для хранения тегом вызови `manage_issue_tags` с точным `Application label`.
При работе через тег не подменяй имя похожим. Если `manage_issue_tags` вернул
ошибку, сохрани полный ответ, включая подсказки, и перечитай задачу на случай
частично успешной операции. Сообщение «tag not found or not accessible» не
различает отсутствующий тег и тег, скрытый настройками доступа: проверь точное
имя; при верном имени попроси владельца/администратора проверить владельца,
видимость и права изменения тега. При отказе по задаче проверь права проекта.
После устранения причины повтори действие для той же задачи и подтверди через
`get_issue`; новую задачу из-за ошибки метки не создавай.
3. **Обнови:** через `update_issue` только при содержательных изменениях proposal.
В описании меняй только блок между `<!-- openspec-task:start -->`
и `<!-- openspec-task:end -->`, содержащий маркер change; добавь его старой задаче.
Сохраняй чужой текст, поля и теги; конфликт привязки/смену метки согласуй.
4. **Заархивируй, закрой и закоммить:** перед archive синхронизируй описание и
время. После подтверждённого переноса каталога читай связь из архива; через
`update_issue` установи успешный конечный статус из схемы полей и проверь
resolved. Перед изменением сохраняй `sync.pending: close`; после проверки
очисти его и `last_error`. Неясный статус уточни. При отмене или ошибке archive
задачу не закрывай и коммит не создавай. Уже завершённую задачу не закрывай
повторно и не переоткрывай.
После успешного archive и синхронизации YouTrack создай Git-коммит со всеми
относящимися к change изменениями, включая архив и очищенную связь. Перед
коммитом проверь `git status` и diff; не включай несвязанные или чужие
staged/working-tree изменения. Если изменения нельзя безопасно отделить,
оставь файлы незакоммиченными, сообщи о блокере и не создавай частичный коммит.
Сообщение коммита начинай с читаемого ключа связанной задачи YouTrack и пробела,
затем кратко опиши фактические изменения по-русски: `CON-27 Правка тестов`.
Ключ бери из данных задачи; не подставляй вместо него непрозрачный `task_id`.
Для архивного change продолжай
только незавершённые шаги и не запускай archive повторно.
## Время и восстановление
Измеряй время от Explore/proposal, без ожиданий и перерывов; синхронизируй
после сеансов Apply и перед archive. Старую длительность не выдумывай.
У каждого интервала уникальный неизменный ID: перед `log_work` сохраняй `sending`,
после подтверждения — `recorded`. Передавай локальную дату, положительные минуты, доступный проекту
`workType` и описание с `OpenSpec Worklog: <id>`; `recorded` повторно не отправляй.
При ошибке MCP/локальной записи останови синхронизацию, сохрани связь,
незавершённые операции и `last_error`. Если archive уже выполнен, проверь
архивную связь, состояние задачи и Git status/log; продолжи только незавершённые
закрытие или коммит, не повторяя archive и уже выполненный коммит. Перед повтором
сверяй внешнее состояние.
Неопределённый результат создания запрещает автоматическое повторное создание
даже при пустом поиске; `sending` требует сверки work items или ручной проверки,
если MCP их не читает. Выполненный archive не откатывай.
Сообщи change, ID/URL задачи, результат и оставшееся действие.
+121
View File
@@ -0,0 +1,121 @@
"""Check the binding's storage contract with the real CLI; no tracker calls."""
import json
import shutil
import subprocess
import tempfile
import unittest
from pathlib import Path
OPENSPEC = shutil.which("openspec")
SCHEMA_DIR = Path(__file__).resolve().parents[1] / "openspec/schemas/use-case-driven"
@unittest.skipUnless(OPENSPEC, "OpenSpec CLI is not installed")
class TaskTrackerArchiveTests(unittest.TestCase):
def setUp(self) -> None:
self.temp_dir = tempfile.TemporaryDirectory()
self.project = Path(self.temp_dir.name).resolve()
self.root = self.project / "openspec"
shutil.copytree(SCHEMA_DIR, self.root / "schemas/use-case-driven",
ignore=shutil.ignore_patterns("__pycache__"))
(self.root / "config.yaml").write_text("schema: use-case-driven\n")
(self.root / "specs").mkdir()
def tearDown(self) -> None:
self.temp_dir.cleanup()
def create_change(self, change_id: str) -> tuple[Path, bytes]:
change = self.root / "changes" / change_id
change.mkdir(parents=True)
(change / ".openspec.yaml").write_text(
"schema: use-case-driven\ncreated: '2026-10-14'\nskip_specs: true\n"
)
(change / "proposal.md").write_text(
"## Why\nImprove tooling.\n\n## What Changes\nUpdate instructions.\n"
"\n## Capabilities\nNo behavior changes.\n\n## Impact\nDocumentation.\n"
)
(change / "tasks.md").write_text("## 1. Documentation\n- [x] 1.1 Update\n")
binding = {
"version": 1, "change_id": change_id,
"project_key": "EXAMPLE", "application_label": "order-service",
"task_id": "opaque-id/123", "task_url": "https://tracker.example/task/123",
"sync": {"pending": "close", "last_error": "MCP unavailable"},
"worklog": [{"id": "session-1", "date": "2026-10-14", "minutes": 25,
"description": "Proposal", "status": "recorded"}],
}
# JSON is valid YAML; the test needs only the standard library.
content = json.dumps(binding, ensure_ascii=False, indent=2).encode()
(change / "task-tracker.yaml").write_bytes(content)
return change, content
def archive(self, change_id: str) -> tuple[subprocess.CompletedProcess, dict]:
result = subprocess.run(
[OPENSPEC, "archive", change_id, "--yes", "--json"],
cwd=self.project, capture_output=True, text=True, timeout=30,
)
self.assertTrue(result.stdout, result.stderr)
return result, json.loads(result.stdout)
def test_archive_moves_binding_and_pending_sync_then_retry_preserves_it(self) -> None:
change_id = "improve-order-validation"
change, content = self.create_change(change_id)
result, output = self.archive(change_id)
self.assertEqual(result.returncode, 0, result.stderr + result.stdout)
archived = Path(output["archive"]["path"])
self.assertFalse(change.exists())
self.assertEqual((archived / "task-tracker.yaml").read_bytes(), content)
# A fresh session can find the original ID without interpreting the archive name.
matches = [path for path in (self.root / "changes/archive").glob("*/task-tracker.yaml")
if json.loads(path.read_text())["change_id"] == change_id]
self.assertEqual(matches, [archived / "task-tracker.yaml"])
retry, _ = self.archive(change_id)
self.assertNotEqual(retry.returncode, 0)
self.assertEqual(matches[0].read_bytes(), content)
def test_archive_preserves_change_id_that_already_starts_with_date(self) -> None:
change_id = "2026-10-01-improve-validation"
_, content = self.create_change(change_id)
result, output = self.archive(change_id)
self.assertEqual(result.returncode, 0, result.stderr + result.stdout)
archived = Path(output["archive"]["path"])
self.assertEqual((archived / "task-tracker.yaml").read_bytes(), content)
self.assertEqual(json.loads(content)["change_id"], change_id)
def test_failed_validation_retains_active_binding_and_pending_sync(self) -> None:
change, content = self.create_change("invalid-change")
specs = change / "specs"
specs.mkdir()
(specs / "spec.md").write_text("## ADDED Requirements\nInvalid root spec.\n")
result, output = self.archive(change.name)
self.assertNotEqual(result.returncode, 0)
self.assertIsNone(output["archive"])
self.assertEqual((change / "task-tracker.yaml").read_bytes(), content)
self.assertEqual(list((self.root / "changes").glob("archive/*/task-tracker.yaml")), [])
def test_archive_collision_retains_both_bindings(self) -> None:
change, content = self.create_change("2026-10-01-existing-name")
archived = self.root / "changes/archive" / change.name
archived.mkdir(parents=True)
previous_binding = b'{"change_id": "earlier", "task_id": "other-task"}'
(archived / "task-tracker.yaml").write_bytes(previous_binding)
result, output = self.archive(change.name)
self.assertNotEqual(result.returncode, 0)
self.assertIsNone(output["archive"])
self.assertEqual((change / "task-tracker.yaml").read_bytes(), content)
self.assertEqual((archived / "task-tracker.yaml").read_bytes(), previous_binding)
if __name__ == "__main__":
unittest.main()
+81
View File
@@ -0,0 +1,81 @@
import sys
import unittest
from pathlib import Path
SCHEMA_DIR = Path(__file__).resolve().parents[1] / "openspec/schemas/use-case-driven"
sys.path.insert(0, str(SCHEMA_DIR))
import validate_format # noqa: E402
SHORT_REQUIREMENT = """### Requirement: Проверка готовности
**ID:** `SYS.HLT-01`
Система SHALL возвращать признак готовности к обработке запросов.
#### Scenario: Сокращенный use case: проверка готовности
##### Основной поток
1. Возвращаем признак готовности по [SYS.HLT-01.FR-01](#syshlt-01fr-01-признак-готовности).
#### Функциональные требования
##### SYS.HLT-01.FR-01: Признак готовности
Признак готовности равен true, когда приложение готово обрабатывать запросы.
"""
HTTP_CONTRACT = """
#### CONTRACT
##### Request
Метод: `GET`; путь: `/health`. Тело запроса отсутствует.
##### Response
HTTP status: `200` при готовности приложения.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `ready` | `boolean` | Обязательное | Только true; значения по умолчанию нет | Готовность приложения | По правилу SYS.HLT-01.FR-01 |
"""
class ShortUseCaseTests(unittest.TestCase):
def check_requirement(self, block: str) -> list[str]:
targets, fr_targets = validate_format.heading_targets(block)
return validate_format.check_requirement(
"Проверка готовности", block, targets, fr_targets,
require_qualified_ids=True,
)
def test_accepts_a_simple_requirement_without_http_contract(self) -> None:
self.assertEqual(self.check_requirement(SHORT_REQUIREMENT), [])
def test_accepts_a_simple_http_requirement_with_short_use_case(self) -> None:
self.assertEqual(self.check_requirement(SHORT_REQUIREMENT + HTTP_CONTRACT), [])
def test_short_http_use_case_still_requires_a_valid_contract(self) -> None:
contract = HTTP_CONTRACT.replace("HTTP status:", "Status:")
errors = self.check_requirement(SHORT_REQUIREMENT + contract)
self.assertTrue(any("в Response укажи HTTP status" in error for error in errors))
def test_short_http_use_case_still_rejects_extra_scenario_sections(self) -> None:
requirement = SHORT_REQUIREMENT.replace(
"##### Основной поток",
"##### Участники\n\n- Оператор.\n\n##### Основной поток",
)
errors = self.check_requirement(requirement + HTTP_CONTRACT)
self.assertTrue(any("только Основной поток" in error for error in errors))
if __name__ == "__main__":
unittest.main()