Compare commits

..
4 Commits
17 changed files with 957 additions and 390 deletions
+198 -56
View File
@@ -1,94 +1,236 @@
# Схема OpenSpec `use-case-driven`
# Общие инструменты для OpenSpec и Codex
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
базовой `spec-driven`. Она задаёт формат артефактов change и спецификаций
поведения; подробные правила схемы находятся в
[README схемы](openspec/schemas/use-case-driven/README.md).
Репозиторий содержит три переиспользуемых артефакта:
| Артефакт | Назначение | Где находится |
|---|---|---|
| Схема 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) |
## Чем отличается от `spec-driven`
Схема и скилл хранятся и развиваются здесь. Подключайте их символическими
ссылками из пользовательских каталогов; обновление клона обновляет общий
источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте:
они содержат настройки конкретного приложения.
- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`.
Здесь используются сценарии использования без Gherkin: полные или
сокращённые, связанные с функциональными требованиями.
- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`.
Подробные правила, устойчивые контракты и обязательные ограничения
фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`.
- Master-спецификация явно описывает `Purpose`, `Границы` ответственности
capability и полный набор `Requirements`. Delta-спецификации меняют требования
стандартными операциями OpenSpec.
- Инструкции и пояснительный текст ориентированы на русский язык; технические
идентификаторы и синтаксис OpenSpec сохраняются.
## 1. Схема `use-case-driven`
## Подключение схемы в проектах
В отличие от базовой `spec-driven`, схема описывает поведение полными или
сокращёнными use cases без Gherkin. Один `Requirement` задаёт завершённую
функцию с одним `Scenario`; локальные `FR` фиксируют подробные правила,
устойчивые контракты и ограничения. HTTP-контракт находится в `CONTRACT`.
Master specs описывают `Purpose`, границы capability и требования; delta specs
используют стандартные операции OpenSpec. Технический синтаксис сохраняется,
пояснения пишутся по-русски. Подробности — в [README схемы](openspec/schemas/use-case-driven/README.md).
Схему можно подключить один раз для всех проектов пользователя. OpenSpec ищет
пользовательские схемы в `~/.local/share/openspec/schemas` на macOS и Linux,
а в `%LOCALAPPDATA%\openspec\schemas` на Windows. Если задана переменная
`XDG_DATA_HOME`, OpenSpec использует `$XDG_DATA_HOME/openspec/schemas` вместо
стандартного пути.
На macOS/Linux пользовательские схемы находятся в
`${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows —
в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан.
1. Клонируйте этот репозиторий в удобную папку. Путь к клону можно выбрать
самостоятельно.
2. В пользовательской папке схем создайте ссылку с именем `use-case-driven`,
ведущую на `openspec/schemas/use-case-driven` внутри клона.
## 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
Команды учитывают `XDG_DATA_HOME`, если он задан. Замените путь в `ln -s` на
путь к своему клону:
Замените `/path/to/openspec-schema` на абсолютный путь к своему клону:
```sh
tooling_repo="/path/to/openspec-schema"
schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas"
mkdir -p "$schemas_dir"
ln -s "/path/to/openspec-schema/openspec/schemas/use-case-driven" \
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
Замените путь в `$schemaSource` на путь к своему клону. Junction создаёт ссылку
на папку без копирования файлов:
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'
}
$schemaSource = 'D:\path\to\openspec-schema\openspec\schemas\use-case-driven'
New-Item -ItemType Directory -Force -Path $schemasDir
New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') -Target $schemaSource
$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')
```
После этого изменения схемы в клоне сразу доступны всем проектам, в которых
указано `schema: use-case-driven`. Проверьте подключение из каталога проекта:
Команды предполагают, что пути назначения ещё свободны. Если схема уже
подключена, создайте только ссылку на скилл. Перед заменой существующей
папки/ссылки проверьте её содержимое и источник.
Проверьте схему из каталога прикладного проекта:
```sh
openspec schema which use-case-driven
openspec schema validate use-case-driven
```
Если в проекте есть собственная схема `openspec/schemas/use-case-driven`, она
имеет приоритет над пользовательской.
Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex.
Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`.
Команды создания ссылки предполагают, что путь назначения ещё не занят. Если
там уже есть папка или ссылка `use-case-driven`, сначала проверьте её содержимое
и источник, прежде чем заменять.
Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над
пользовательской. Кроме того, схема ссылается на вспомогательные файлы
относительно проекта (`validate_format.py`, `patterns/`). Для доступа к ним
создайте в проекте ссылку `openspec/schemas/use-case-driven` на ту же общую
схему либо адаптируйте пути инструкций. Пользовательская ссылка сама
эти проектные пути не создаёт.
В текущей схеме инструкции также ссылаются на дополнительные файлы по путям
относительно проекта, например
`openspec/schemas/use-case-driven/validate_format.py` и `patterns/`. Одна
пользовательская ссылка делает схему и шаблоны доступными OpenSpec, но не
создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная
проектная ссылка либо адаптация инструкций к расположению активной схемы.
## Переход со старой интеграции
В прикладных проектах перенесите ключ и метку из старого `context` в
`AGENTS.md`, добавьте lifecycle из заготовки и подключите скилл. Удалите
старые инструкции трекера из `config.yaml`, включая
`operations.archive.guidance`; остальные контекст и правила сохраните.
Если схема скопирована в проект вместо ссылки, обновите также её копию.
## Статус
Существующие ID/URL в proposal сохраняйте до проверенной привязки.
Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после
проверки задачи. Архивным changes без однозначной связи новую задачу
автоматически не создаёт.
Схема находится в стадии доработки. Описаны ещё не все типы функциональных
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует,
что при подготовке спецификации будут выявлены все применимые требования — в
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно
учитывать при анализе изменения.
## Проверки и ограничения
```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/`.
-10
View File
@@ -1,15 +1,5 @@
schema: use-case-driven
# При настройке проекта YouTrack добавьте в context строку:
# YouTrack project key: <KEY>
context: |
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
Proposed; не помечай решение Accepted без явного принятия владельцем решения.
rules:
tasks:
- >-
+31 -34
View File
@@ -5,12 +5,20 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
## Git-процесс проекта
Схема задаёт порядок и формат OpenSpec-артефактов. Правила веток, двух
последовательных PR, ручного слияния и явной команды продолжения находятся
в [шаблоне проектных инструкций](../../../examples/project-bootstrap/AGENTS.md).
При подключении схемы включите правила из этого шаблона в проектный
`AGENTS.md` и согласуйте имя целевой ветки с настройками репозитория.
## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- Scenario — один из двух форматов Use case: полный или сокращённый. Формат определяется сложностью сценария, независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- FR — подробные правила и контракты сообщений за пределами Scenario;
контракт HTTP endpoint размещается в завершающем CONTRACT.
@@ -68,8 +76,11 @@ Markdown-рендерер автоматически создаёт якоря
## Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
- Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий.
- Сокращённый Use case используй для простых коротких требований. Рассматривай их как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
- Выбирай формат по сложности: не используй полный Use case для простых требований, а сокращённый — для объёмных многошаговых сценариев. Правило действует и для HTTP endpoint.
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращённый Use case содержит только Основной поток; каждый шаг ссылается на FR.
```text
#### Scenario: Сокращенный use case: описание функции
@@ -106,8 +117,8 @@ FR задаёт тексты, дальнейшие действия и связ
## HTTP-контракт в Requirement
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
Каждый endpoint оформляется отдельным Requirement. Формат Use case выбирается
по сложности сценария; сложные правила шагов выносятся в FR. После всех FR, в конце
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
@@ -147,39 +158,25 @@ Scenario в таких операциях не создаётся. В delta со
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
## Учёт change в YouTrack
Каждый новый change, включая change с `skip_specs: true`, получает ровно одну
задачу типа Task в YouTrack-проекте соответствующего репозитория. Сначала
подготовь содержательный proposal с причиной, scope, capabilities и impact;
затем, до перехода к specs, design и tasks, создай задачу через подключённый
YouTrack MCP. Ключ проекта укажи в `context` файла `openspec/config.yaml`; добавь
строку `YouTrack project key: <KEY>`. Если строки нет или ключ нельзя однозначно
проверить через MCP, уточни его у пользователя; проект `Default` не является
автоматическим запасным вариантом. Перед созданием прочитай схему обязательных
полей проекта и используй только допустимые значения. Не добавляй произвольное
верхнеуровневое поле `youtrack_project`: оно не входит в контракт OpenSpec.
В задаче укажи slug change и краткую цель, а её ключ и URL сохрани в разделе
`## YouTrack` файла `proposal.md`. При создании задачи также внеси work item с
фактически затраченным временем на подготовку контекста change и proposal.
При каждом последующем редактировании proposal пересмотри заголовок и описание
задачи. Если изменились причина, scope, capabilities или impact, обнови связанную
задачу через MCP в соответствии с актуальным proposal; не создавай дубликат.
Если MCP недоступен, явно сообщи об этом и уточни дальнейшее действие.
На всех этапах change — от подготовки proposal до реализации — записывай
фактически затраченное время в YouTrack как work items, используя поддерживаемый
проектом тип работы и не дублируя уже внесённые записи. При архивировании учти
всё оставшееся время, затем выполни `openspec archive`; после успешной архивации
переведи связанную задачу в конечный статус, предусмотренный YouTrack-проектом.
Определи поле и значение статуса по схеме проекта, не угадывай их. Change
завершён только после успешного архивирования и закрытия задачи.
Если смысловые коды или сообщения ещё не выдаются приложением, это явно
фиксируется в 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 проекта в `openspec/context/adr/` и называй файлы
@@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич
## HTTP endpoint
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
правила обработки указываются в FR, а контракт помещается в самом конце
Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
Requirement:
```markdown
+169 -279
View File
@@ -10,93 +10,58 @@ artifacts:
description: Начальный документ предложения, описывающий изменение
template: proposal.md
instruction: |
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
OpenSpec и технические идентификаторы, названия API, файлов,
инструментов, команд и коды без перевода.
Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
идентификаторы, названия API, файлов, инструментов, команды и коды не переводи.
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение.
Объясни, ПОЧЕМУ требуется изменение. Объём — 1–2 страницы; детали
реализации относятся к design.md.
Разделы:
- **Why**: 1–2 предложения о проблеме или возможности. Какую проблему
решает изменение? Почему его нужно сделать сейчас?
- **What Changes**: Список изменений. Точно опиши новые возможности,
изменения и удаления. Помечай несовместимые изменения как **BREAKING**.
- **Capabilities**: Укажи, какие спецификации будут созданы или изменены:
Capability представляет отдельную бизнес-функцию или понятный результат;
сохраняй полный иерархический путь, например `domain/capability-name`.
Для новой capability сформируй короткий читаемый префикс Requirement:
для однословного сегмента используй первые три буквы, для сегмента с
дефисами — первые буквы его частей. Приводи сокращения к верхнему
регистру, разделяй сегменты кода точкой и сохраняй их порядок:
`domain/capability-name` → `DOM.CN`.
Перед назначением проверь уникальность префикса по Requirement ID в
основных спецификациях проекта. Если префикс занят, удлиняй сокращения
новых сегментов до уникальности; уже используемые префиксы не меняй.
Сохраняй префикс при переименовании capability.
- **New Capabilities**: Перечисли добавляемые capabilities. Для каждой
создай `specs/<capability-path>/spec.md`. Используй `kebab-case` для
новых сегментов пути (например, `user-auth` или `identity/user-auth`)
и следуй принятой в проекте структуре спецификаций.
- **Modified Capabilities**: Перечисли существующие capabilities, чьи
REQUIREMENTS меняются. Добавляй сюда capability только при изменении
поведения, описанного в спецификации, а не только деталей реализации.
Для каждой создай delta spec по точному существующему пути внутри
`openspec/specs/`. Оставь список пустым, если требования не меняются.
- **Impact**: Затронутые участки кода, API, зависимости и системы.
- **YouTrack**: После создания задачи укажи её ключ и URL.
- **Why**: 1–2 предложения о проблеме или возможности и причинах изменения сейчас.
- **What Changes**: Точный список новых возможностей, изменений и удалений;
несовместимые изменения помечай **BREAKING**.
- **Capabilities**: Создаваемые или изменяемые спецификации отдельных
бизнес-функций или понятных результатов. Сохраняй полный иерархический
путь, например `domain/capability-name`.
Короткий читаемый префикс Requirement для новой capability: первые три буквы однословного
сегмента или первые буквы частей сегмента с дефисами; верхний регистр,
точки и порядок сегментов (`domain/capability-name` → `DOM.CN`).
Проверь уникальность префикса по Requirement ID основных спецификаций;
при совпадении удлиняй сокращения новых сегментов до уникальности. Существующие префиксы
не меняй, включая переименование capability.
- **New Capabilities**: Перечисли новые capabilities; для каждой создай
`specs/<capability-path>/spec.md`; новые сегменты пиши в `kebab-case`,
следуя структуре проекта.
- **Modified Capabilities**: Укажи существующие capabilities только при
изменении описанного поведения, а не деталей реализации. Создай delta
spec по точному существующему пути внутри `openspec/specs/`; если
требования не меняются, оставь список пустым.
- **Impact**: Затронутые код, API, зависимости и системы.
- **Project Context**: Создаваемые или обновляемые постоянные документы,
включая решение о необходимости ADR. Отсутствие изменений укажи явно.
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs.
Перед его заполнением изучи существующие спецификации: выполни
`openspec list --specs`, чтобы получить список capabilities проекта.
Для подходящих вариантов выполни `openspec show "<spec-id>" --type spec --json --no-scenarios`.
Команда вернёт назначение capability и тексты требований, не загружая
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам
только для зарегистрированного отдельного хранилища и сохраняй
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя,
без этого параметра возникнет неоднозначность при выборе. Команда
`openspec list` без `--specs` показывает активные изменения (`changes`),
а не спецификации, поэтому не отражает уже описанное в проекте поведение.
Используй точный путь
существующей capability, не создавай похожее имя.
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
описано и что нужно изменить, прочитай каждую подходящую спецификацию
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
(с тем же правилом для `--store`). Для каждой перечисленной capability
потребуется соответствующий файл спецификации.
Перед заполнением Capabilities изучи существующие specs:
1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes.
2. Для подходящих вариантов — `openspec show "<spec-id>" --type spec --json --no-scenarios`:
обзор назначения и требований без загрузки целых спецификаций.
3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком,
включая сценарии: `openspec show "<spec-id>" --type spec`.
Добавляй `--store "<id>"` к этим командам только для зарегистрированного
отдельного хранилища. Сохраняй `--type spec`, чтобы избежать неоднозначности
при одинаковых именах change и spec. Используй точный путь существующей
capability, не создавай похожее имя. Каждой перечисленной capability
соответствует файл спецификации.
После подготовки содержательного первого варианта proposal создай для
каждого нового change, в том числе с `skip_specs: true`, ровно одну задачу
типа Task в YouTrack-проекте этого репозитория через подключённый YouTrack
MCP. Создай задачу до перехода к specs, design и tasks, используя причину,
scope и impact из proposal. Бери ключ проекта из `context` файла
`openspec/config.yaml`; в нём должна быть строка `YouTrack project key: <KEY>`.
Если строка отсутствует или ключ нельзя однозначно проверить через MCP,
уточни его у пользователя. Проект `Default` не используй как запасной
вариант. Перед созданием проверь схему обязательных полей проекта; не выдумывай значения.
Укажи slug change и краткую цель в задаче, затем
заполни в proposal раздел YouTrack ключом и URL задачи. Добавь work item с
фактически затраченным до этого временем на подготовку контекста change и
proposal.
Change должен содержать новую/изменяемую capability либо `skip_specs: true`
в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta.
`skip_specs: true` допустим только без изменения описанного поведения
(чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки.
При каждом последующем редактировании proposal пересмотри формулировки
заголовка и описания связанной YouTrack-задачи. Если причина, scope,
capabilities или impact изменились, обнови задачу через MCP так, чтобы они
соответствовали актуальному proposal; не создавай новую задачу. Если MCP
недоступен, сообщи об этом и уточни, как продолжить.
Для Project Context прочитай существующий `openspec/context/index.md` и
относящиеся к change документы из него. Не копируй функциональные требования
Specs в Context. Отсутствующий индекс включай в scope только при введении
постоянных документов контекста или принятии проектом этой навигационной модели.
В каждом изменении (`change`) должна быть указана хотя бы одна новая или
изменяемая capability либо явный отказ от спецификаций: `openspec validate`
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не
задано `skip_specs: true`.
Используй `skip_specs: true` только когда поведение, описываемое
спецификациями, не меняется (например, при чистом рефакторинге, изменении
инструментов или документации). Не добавляй требование только ради
прохождения проверки.
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на
способе реализации: детали реализации относятся к design.md.
Этот документ задаёт основу: на нём строятся specs, design и tasks.
requires: []
- id: specs
@@ -104,141 +69,113 @@ artifacts:
description: Подробные спецификации изменения
template: spec.md
instruction: |
Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные
заголовки OpenSpec, идентификаторы, названия API и коды без перевода.
Пиши пояснения по-русски; обязательные заголовки OpenSpec, идентификаторы,
названия API и коды не переводи.
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
Правила ниже применяются к основным спецификациям и к полным блокам
ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin.
Описывай наблюдаемое поведение и устойчивые контракты в формате без Gherkin.
Правила применяются к основным specs и полным блокам ADDED/MODIFIED в delta.
Иерархия и границы:
- Capability описывает отдельную бизнес-функцию или понятный результат.
- Сохраняй полный иерархический путь, например domain/capability-name.
- Capability — отдельная бизнес-функция или понятный результат; сохраняй
полный иерархический путь, например domain/capability-name.
- Основная спецификация содержит раздел ## Границы между Purpose и
Requirements. Кратко укажи, за что отвечает capability, что входит в её
область и что находится за её пределами или относится к другой capability
либо приложению. Не дублируй Requirements и FR.
- Один Requirement описывает одну завершённую техническую функцию.
- Не дроби один процесс на Requirements для чтения, валидации и записи.
- Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario.
- Префикс Requirement состоит из сокращений сегментов пути capability,
разделённых точками; его уникальность проверяется по ID в основных
спецификациях. Номер Requirement уникален внутри capability. Существующие
Requirements: кратко укажи ответственность, область, исключения и владельцев
соседних обязанностей — другие capabilities или приложения. Не дублируй
Requirements и FR; сведения об ответственности допустимы без задания поведения.
- Requirement — одна завершённая техническая функция, стабильный ID вида
AREA.CAP-01 и ровно один Scenario. Не дроби процесс на чтение, валидацию и запись.
- Префикс — сокращения сегментов пути capability через точки; проверяй
уникальность по ID основных specs. Номер уникален внутри capability;
унаследованные Requirements могут сохранять прежние ID.
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
- В Requirements и FR включай только сведения, меняющие наблюдаемое
поведение, устойчивый контракт или обязательное техническое ограничение.
Удаляй повторы, пояснения и формулировки, которые не меняют поведение и
не снимают неоднозначность контракта. В ## Границы оставляй краткие
сведения об ответственности и владении, необходимые для понимания
области capability, даже если они сами по себе не задают поведение.
- В Requirements и FR оставляй только наблюдаемое поведение, устойчивые
контракты и обязательные технические ограничения. Удаляй повторы и
пояснения, не влияющие на поведение и не снимающие неоднозначность контракта.
Scenario:
- Поддерживаются два формата сценария использования: полный и
сокращённый. Автор выбирает формат по ситуации, независимо от типа FR
и описываемой части системы: процесса выполнения, БД, API, UI и других.
- Полный сценарий использования содержит разделы Участники, Предусловия,
- Выбирай формат по сложности сценария, независимо от типа FR и части системы
(процесс, БД, API, UI и другие).
- Полный Use case используй для крупных многошаговых сценариев с большим
количеством последовательных действий, а не для простых коротких требований.
- Сокращённый Use case используй для простых коротких требований, а не для
объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты
на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
- Полный сценарий содержит разделы Участники, Предусловия,
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
в таком порядке.
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`;
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
участников, предусловий, альтернатив и ошибок, результата или кодов
завершения и не задаёт отдельные ветвления во время выполнения.
- В обычном сценарии Назначение опционально; добавляй только если оно
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
- Сокращённый сценарий содержит только `##### Основной поток`, без других
разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на FR.
- В обычном сценарии Назначение опционально: добавляй только сведения,
которых нет в заголовке. Контекст отсутствует.
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
- Шаг сценария выполнения может назвать действие, конечную точку API или
способ записи и сослаться на FR.
- Каждую конечную точку HTTP описывай в отдельном Requirement с полным
сценарием использования.
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
- В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR.
- Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария
выбирай по его сложности.
Сложные правила шагов выноси в FR со ссылками из сценария.
- Основной поток и альтернативы обычного сценария включают коды
завершения, если они определены для этой функции.
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
сообщений и дальнейшая логика располагаются за пределами Scenario.
- Единственная таблица Scenario — Коды завершения с колонками
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
- Код сам сообщает смысл итога; дополнительный этап или свободный текст
не должен требоваться для понимания кода. События промежуточных шагов
не являются кодами завершения. Не создавай код для каждой диагностики.
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
логику, текст или применимые правила результата.
- Код сам сообщает смысл итога без дополнительного этапа или свободного текста.
Промежуточные события не являются кодами завершения; не создавай код для каждой диагностики.
- Каждый код ссылается на локальные FR с дальнейшей логикой, текстом или правилами результата.
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
содержательного текста без адресов Markdown-ссылок.
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
Функциональные требования:
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
- Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее.
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
Номер начинается с FR-01 в каждом Requirement.
- FR содержит отдельное понятное правило или связанный контракт; не дроби
связную логику на множество атомарных FR.
- Обычный FR без метки описывает логику, правила или последовательность
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
или [UI]; метка не входит в ID и не меняет slug ссылки.
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
контракт сообщения или технического лога. Контракт конечной точки HTTP
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
UI; детальный паттерн будет добавлен отдельно.
- Для FR [DB] с таблицей БД следуй паттерну
- После Scenario идёт `#### Функциональные требования` с заголовками
`##### <requirement-id>.FR-NN [метка]: <название>`; метка опциональна.
Локальная нумерация начинается с FR-01 в каждом Requirement.
- FR — отдельное понятное правило или связанный контракт;
не дроби связную логику на множество атомарных FR.
- FR без метки — логика, правила или последовательность шагов.
Метки [DB], [API], [UI] ставь сразу после ID; они не входят в ID и не меняют slug.
- [DB] — структура БД; для таблицы следуй
`openspec/schemas/use-case-driven/patterns/database-table.md`.
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
`openspec/schemas/use-case-driven/patterns/message-contract.md`.
- Контракт конечной точки HTTP не оформляй отдельными FR. После раздела
Функциональные требования добавляй завершающий раздел CONTRACT с
подразделами Request и Response в таком порядке. В Request указывай
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
- В таблице Response раздела CONTRACT укажи для каждого поля источник
значения или правило его формирования в последней колонке.
- В таблице ответа контракта FR [API] укажи для каждого поля источник
значения или правило его формирования в колонке «Формирование значения».
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
якоря из заголовков Requirement и FR.
- Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его
заголовка, например
[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID
используется и для ссылки внутри Requirement, и для ссылки на другой
Requirement.
- [API] — контракт сообщения или технического лога; сериализуемое сообщение
оформляй по `openspec/schemas/use-case-driven/patterns/message-contract.md`.
- [UI] — требования к UI; детальный паттерн будет добавлен отдельно.
- HTTP-контракт размещай после Функциональных требований в завершающем
CONTRACT, не в отдельных FR. Подразделы — Request, затем Response.
В Request указывай один HTTP-метод и путь, явно отмечай отсутствие тела.
Таблицы тела запроса и ответа оформляй по message-contract.md.
- В response-таблицах для каждого поля укажи источник или правило формирования:
в последней колонке CONTRACT и в «Формирование значения» для FR [API].
- Не добавляй HTML-якоря <a id="..."></a>; используй Markdown-якоря заголовков.
- Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка,
например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
новые FR добавляй в конец. Порядок первого документа последовательный.
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
сообщения/действия, если это часть контракта. Параметры сообщений
являются данными, а не скрытым значением кода.
- Если смысловой код спецификации отличается от текущего поведения системы,
явно опиши соответствие и статус реализации в FR. Не утверждай,
что новый код или текст уже возвращается приложением.
- Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия,
если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода.
- При отличии смыслового кода от текущего поведения явно опиши в FR соответствие
и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением.
Работа с OpenSpec:
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
- Основная спецификация следует краткой схеме templates/main-spec.md; это формат-
ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы
и полный актуальный набор Requirements.
- Основная spec: Purpose, ## Границы и полный актуальный набор Requirements.
Ориентир формата — templates/main-spec.md, не генерируемый артефакт.
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
- Для новой capability delta-спецификация начинается с ## Purpose
(не менее 50 знаков). Для существующей capability Purpose в delta не добавляй.
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
Его заголовок должен совпадать с заголовком соответствующего Requirement
в основной спецификации.
- Для новой capability начинай delta с ## Purpose (не менее 50 знаков);
для существующей Purpose не добавляй.
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR;
заголовок совпадает с соответствующим Requirement основной spec.
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
Это операции над требованиями, не сценарии технических функций.
- При копировании блоков в delta сохраняй ID Requirements, номера и
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
неизменённый Requirement основной спецификации, проверяй delta с
`--base <master-spec>`.
- Не создавай delta для чистого форматирования, изменений инструментов
или рефакторинга. Для изменения без изменения поведения используй
`skip_specs: true`.
- Проверь schema через openspec schema validate use-case-driven.
- Проверь spec через openspec validate и отдельно через
python3 openspec/schemas/use-case-driven/validate_format.py
--require-qualified-ids <spec-path>. Для неизменённых спецификаций
со старыми ID этот флаг не нужен.
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
- В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками.
Для ссылок на неизменённый Requirement основной spec проверяй delta
с `--base <master-spec>`.
- Без изменения поведения (чистое форматирование, инструменты, рефакторинг)
используй `skip_specs: true`, не создавай delta.
- Проверки: `openspec schema validate use-case-driven`; для spec —
`openspec validate` и `python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids <spec-path>`.
Для неизменённых specs со старыми ID флаг не нужен. OpenSpec не проверяет все правила формата.
requires:
- proposal
@@ -247,59 +184,38 @@ artifacts:
description: Техническое описание решения и деталей реализации
template: design.md
instruction: |
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
OpenSpec и технические идентификаторы, названия файлов, инструментов
и команд без перевода.
Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
идентификаторы, названия файлов, инструментов и команды не переводи.
Создай документ design, объясняющий, КАК реализовать изменение.
Design объясняет, КАК реализовать изменение: архитектуру и подход, не пошаговый код.
Когда добавлять design.md (достаточно любого из условий):
- Изменение затрагивает несколько сервисов или модулей либо вводит новый
архитектурный подход.
- Добавляется внешняя зависимость или существенно меняется модель данных.
- Есть сложность, связанная с безопасностью, производительностью или
миграцией.
- До начала разработки нужно принять технические решения, чтобы устранить
неоднозначность.
Добавляй design.md при любом из условий:
- Несколько сервисов/модулей или новый архитектурный подход.
- Внешняя зависимость или существенное изменение модели данных.
- Сложности безопасности, производительности или миграции.
- Технические решения для устранения неоднозначности до разработки.
Разделы:
- **Context**: Только текущее состояние и ограничения, необходимые для
объяснения подхода. Причины изменения смотри в proposal, не повторяй их
(например: «См. proposal.md — Why»).
- **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает.
Не повторяй область работ из proposal; указывай только границы решения.
- **Decisions**: Ключевые технические решения и их обоснование: почему
выбран один вариант вместо другого. Укажи рассмотренные альтернативы.
- **Risks / Trade-offs**: Известные ограничения и возможные проблемы.
Формат: [Риск] → [Меры снижения].
- **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо.
- **Open Questions**: Неизвестные, которые можно безопасно выяснить позже,
не меняя спецификации, подход или состав задач. Не добавляй, если таких
вопросов нет.
- **Context**: Только текущее состояние и ограничения для объяснения подхода.
- **Goals / Non-Goals**: Что решение обеспечивает и исключает; границы решения без повтора scope proposal.
- **Decisions**: Ключевые технические решения, их обоснование и рассмотренные альтернативы.
- **Risks / Trade-offs**: Ограничения и проблемы в формате [Риск] → [Меры снижения].
- **Migration Plan**: Развёртывание и откат, если применимо.
- **Open Questions**: Только безопасно отложенные вопросы, не влияющие на
specs, подход или состав задач. При отсутствии вопросов раздел не добавляй.
Влияющие вопросы выясни с пользователем сейчас, не подменяй ответ предположением.
Открытые вопросы предназначены для действительно отложенных решений, а не
для пропущенных решений. Если ответ может изменить спецификации, выбранный
подход или состав задач, выясни его сейчас: спроси пользователя, а не
делай предположение.
Вместо повтора причин и состава изменения ссылайся на proposal, вместо
копирования требований — на specs, используя Requirement ID и локальные FR.
Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода.
В proposal описаны причины и состав изменения, в design — способ
реализации. Ссылайся на proposal для обоснования и на specs для требований;
если раздел только повторяет их, дай ссылку вместо повтора.
Сверь Project Context proposal с design: нужны ли новые/обновлённые постоянные
документы и индекс? В Context ссылайся на требования Specs без дублирования.
Ссылайся на Requirement ID и локальные FR; описывай решения реализации
без копирования требований.
Перед проектированием прочитай применимые принятые ADR из
`openspec/context/adr/` и укажи их идентификаторы в Decisions. Если
изменение принимает долгосрочное архитектурное решение или заменяет
принятое решение, запланируй создание нового ADR по шаблону
`openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed.
Не помечай ADR принятым самостоятельно. Если запрос противоречит
действующему ADR, явно опиши конфликт и запроси решение пользователя до
выбора расходящегося подхода.
Хороший design объясняет причины технических решений.
Перед проектированием прочитай применимые принятые ADR в `openspec/context/adr/`
и укажи ID в Decisions. Для долгосрочного архитектурного решения или замены
принятого запланируй новый ADR по `openspec/schemas/use-case-driven/templates/adr.md`
со статусом Proposed; самостоятельно не принимай его. Конфликт с действующим
ADR явно опиши и получи решение пользователя до выбора расходящегося подхода.
requires:
- proposal
@@ -308,63 +224,41 @@ artifacts:
description: Контрольный список задач с отслеживаемым выполнением
template: tasks.md
instruction: |
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные
идентификаторы, пути файлов, названия API, коды и команды без перевода.
Пиши группы и задачи по-русски; обязательные идентификаторы, пути файлов,
названия API, коды и команды не переводи.
Создай список задач, разбивающий работу по реализации на части.
Разбей реализацию на задачи по specs (что создать) и design (как реализовать).
Перед составлением задач проверь Open Questions в design.md. Если ответ на
какой-либо вопрос повлияет на результат разработки, сначала обсуди его с
пользователем; не закладывай в список задач неоговорённые предположения.
Проверь Open Questions в design.md: влияющие на результат вопросы сначала
обсуди с пользователем; не закладывай неоговорённые предположения.
**ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по
формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным
независимо от регистра и пробелов; например, `- [ x]` тоже означает
выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`,
считается незавершённой. Строки без чекбокса вообще не отслеживаются.
Следуй шаблону: apply отслеживает только чекбоксы. Только `x` внутри скобок
означает выполнение независимо от регистра и пробелов; любая другая отметка,
включая пустые скобки, считается незавершённой. Строки без чекбокса не отслеживаются.
Правила:
- Группируй связанные задачи под нумерованными заголовками `##`.
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
- Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию.
- Располагай задачи в порядке зависимостей: сначала то, что нужно сделать
раньше.
- Для каждой задачи укажи способ проверки выполнения: тест, команду,
наблюдаемое поведение или готовый артефакт. Добавь проверку в описание
чекбокса. Выноси проверку в отдельную задачу только для интеграционных
или системных сценариев, охватывающих несколько задач реализации.
- Каждая задача выполнима за одну сессию; порядок соответствует зависимостям.
- В описание каждого чекбокса включай проверку: тест, команду, наблюдаемое
поведение или готовый артефакт. Отдельная задача проверки допустима только
для интеграционных/системных сценариев, охватывающих несколько задач реализации.
Пример:
```
# Tasks
## 1. Подготовка
- [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов
- [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки
## 2. Основная реализация
- [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта
- [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами
- [ ] 1.1 Реализовать экспорт данных и проверить прохождение теста экспорта
```
Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это
реализовать.
Связывай задачи с Requirement ID, FR и кодами завершения, если они затронуты.
Связывай задачи с Requirement ID, FR и кодами завершения, если задача
затрагивает эти результаты.
Для нового или заменяющего ADR из design добавь отдельную задачу создания
в `openspec/context/adr/` со статусом Proposed. При замене принятого решения
свяжи новый и прежний ADR полями `supersedes` и `superseded-by`.
YouTrack-задача из proposal сопровождает весь change и не заменяет
чекбоксы реализации в tasks.md. На всех этапах change — от подготовки
proposal до реализации — записывай в YouTrack фактически затраченное время
отдельными work items через MCP, без дублирования уже внесённого времени.
Выбирай только тип работы, поддерживаемый проектом.
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
отдельную задачу на его создание в `openspec/context/adr/` со статусом
Proposed. При замене принятого решения свяжи новый и прежний ADR через
поля `supersedes` и `superseded-by`.
Если proposal/design предусматривает создание/обновление постоянных документов
контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md`
при изменении состава документов; отсутствующий индекс создавай только
при введении постоянных документов контекста или принятии проектом этой навигационной модели.
requires:
- specs
- design
@@ -374,12 +268,8 @@ apply:
tracks: tasks.md
instruction: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
потребуется уточнение. Для change с задачей YouTrack записывай фактически
затраченное во время apply время в её work items через MCP; перед
архивированием проверь, что учтено всё время работы над change. После
успешного `openspec archive`
переведи задачу в конечный статус, предусмотренный проектом YouTrack,
используя доступную схему полей и значений. Не подставляй предполагаемое
название статуса. Считай change завершённым только после успешного
архивирования и закрытия YouTrack-задачи.
выполненными по мере работы, включая задачи по обновлению проектного
контекста и его индекса. Если индекс существует или его создание входит в
tasks.md, проверь, что он соответствует фактическому набору документов.
Убедись, что требования Specs не продублированы в Context.
Остановись, если столкнёшься с препятствием или потребуется уточнение.
@@ -28,7 +28,8 @@
<!-- Затронутые код, API, зависимости и системы -->
## YouTrack
## Project Context
<!-- Заполни после подготовки proposal и создания задачи. -->
- Задача: `<PROJECT-123>` — <issue URL>
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
создать или обновить. Если обновления не нужны, напиши это явно.
Не переноси сюда функциональные требования из OpenSpec Specs. -->
@@ -20,6 +20,12 @@
Система SHALL <наблюдаемый результат завершённой функции>.
<!-- Выбирай формат по сложности сценария, независимо от типа FR и части системы.
Полный Use case используй для крупных многошаговых сценариев; сокращённый —
для простых коротких требований. Такие требования — кандидаты на выделение
в отдельные Requirements для переиспользования в сценариях других Requirements.
Не используй полный формат для простых требований, а сокращённый — для объёмных. -->
#### Scenario: <название завершённого процесса>
##### Участники
@@ -69,7 +75,7 @@ HTTP endpoint располагай в завершающем разделе CONT
<При необходимости — параметры сообщений, связанные требования и соответствие
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
<!-- HTTP endpoint описывай в отдельном Requirement; формат Use case выбирай по сложности.
Контракт размещай в конце Requirement, не разбивая request/response на FR:
#### CONTRACT
@@ -87,9 +93,7 @@ HTTP status: <код и условие возврата>.
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
-->
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
типа FR и предмета описания. Для сокращенного Use case используй только основной
поток и ссылки на FR:
<!-- Для сокращённого Use case замени полный Scenario следующим блоком:
#### Scenario: Сокращенный use case: <предмет описания>
@@ -417,8 +417,6 @@ def check_requirement(
scenario, details = block.split("#### Функциональные требования", 1)
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
if has_contract:
if is_short_use_case:
errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case")
details, contract_content = details.split("#### CONTRACT", 1)
errors.extend(check_http_endpoint_contract(contract_content))
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()