Compare commits

...
2 Commits
Author SHA1 Message Date
alex b5558ec008 Обновил git процесс 2026-10-18 20:17:26 +03:00
alex e2e2d0bcc2 Правки процесс работы с task tracker 2026-10-16 21:39:10 +03:00
14 changed files with 646 additions and 163 deletions
+196 -64
View File
@@ -1,104 +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`; остальные контекст и правила сохраните.
Если схема скопирована в проект вместо ссылки, обновите также её копию.
Ссылка на пользовательскую схему также не устанавливает `AGENTS.md` или
`openspec/context/` в проект-потребитель. Для начальной настройки можно вручную
скопировать и адаптировать файлы из
[`examples/project-bootstrap/`](examples/project-bootstrap/). Комплект включает
инструкции агента, индекс контекста, правила ADR и копию ADR-шаблона. Содержимое
индекса и любые дополнительные документы контекста должны соответствовать
конкретному проекту. В комплекте нет принятых ADR и описаний бизнес-домена.
Существующие ID/URL в proposal сохраняйте до проверенной привязки.
Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после
проверки задачи. Архивным changes без однозначной связи новую задачу
автоматически не создаёт.
## Проверки и ограничения
## Статус
```sh
openspec schema validate use-case-driven
python3 -m unittest discover -s tests -v
```
Схема находится в стадии доработки. Описаны ещё не все типы функциональных
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует,
что при подготовке спецификации будут выявлены все применимые требования — в
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно
учитывать при анализе изменения.
Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI
во временных каталогах и проверяют сохранение связи и журнала при успешном
archive, отказе валидации и конфликте архива. Они не обращаются к трекеру;
без CLI пропускаются. Frontmatter скилла можно отдельно проверить
`scripts/quick_validate.py` из установленного `skill-creator`.
Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие
конфигурации описаны в скилле. Их внешнее выполнение требует доступного
провайдера; инструктивный скилл не даёт программных гарантий исполнения.
Для сквозной проверки используйте согласованный тестовый проект, не создавайте
тестовые задачи в рабочем проекте без согласования.
Схема продолжает развиваться: не все типы FR и форматы контрактов имеют
подробные паттерны, например FR `[UI]`. Применимые требования безопасности,
аудита и ролевой модели нужно явно учитывать при анализе изменения.
+53
View File
@@ -20,3 +20,56 @@
обновляй `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`.
+30 -12
View File
@@ -8,7 +8,9 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав
В комплект входят:
- `AGENTS.md` — навигация по проектному контексту и правила OpenSpec;
- `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` — заготовка нового решения.
@@ -18,24 +20,40 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав
требования из `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` проектные параметры
интеграции YouTrack в существующем блоке `context`, сохранив остальной контекст:
После `openspec init` объедините заготовку `openspec/config.yaml` с конфигурацией
проекта, сохранив существующие настройки. Выберите `schema: use-case-driven`
и дополните предметный контекст. Настройки задач заполняйте в `AGENTS.md`:
```yaml
context: |
YouTrack project key: <KEY>
YouTrack application label: <APP-NAME>
```markdown
Task tracker configuration:
- Project key: <KEY>
- Application label: <APP-NAME>
```
Укажите ключ проекта и имя приложения, которое должно записываться в тег каждой
задачи. Общие правила создания задачи, учёта времени и архивации берутся из
схемы `use-case-driven`. Добавьте также `operations.archive.guidance` из раздела
«Настройка YouTrack» в README схемы: OpenSpec загружает эту подсказку отдельно
при вызове `openspec instructions archive`.
Укажите ключ проекта и имя приложения, которым маркируется каждая задача. Скилл
сохраняет его в строковое поле `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.
-16
View File
@@ -1,11 +1,5 @@
schema: use-case-driven
# Проектные настройки YouTrack. Общие правила работы заданы в schema.yaml.
# В проектах, скопировавших эту схему, замените значения на свои.
context: |
YouTrack project key: PL
YouTrack application label: openspec-schema
rules:
tasks:
- >-
@@ -17,13 +11,3 @@ rules:
публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений,
рефакторинга и документации, MINOR для обратно совместимых возможностей,
MAJOR для несовместимых изменений публичного контракта.
operations:
archive:
guidance:
- >-
Перед `openspec archive` внеси в связанную задачу YouTrack оставшееся
фактическое время, учитывая только ещё не записанное и используя
доступный проекту тип работы. После успешной архивации переведи задачу
в конечный статус проекта по доступным полям и значениям; не угадывай
статус. Change завершён только после архивации и закрытия задачи.
+14 -34
View File
@@ -5,43 +5,20 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
## Настройка YouTrack
## Git-процесс проекта
Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке
`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь
строки в существующий блок, сохранив остальной проектный контекст:
```yaml
context: |
YouTrack project key: <KEY>
YouTrack application label: <APP-NAME>
```
Схема создаёт одну задачу `Task` на change, добавляет к ней тег с указанным
именем приложения и учитывает фактическое время от Explore до архивации. В
YouTrack этот механизм называется тегом; настройка `application label` задаёт
точное имя этого тега. Если интеграция или тег недоступны, workflow останавливается
и сообщает о проблеме, а не создаёт задачу без метки приложения.
Завершающие действия YouTrack для команды `openspec archive` настраиваются отдельно
от схемы — в `operations.archive.guidance` файла `openspec/config.yaml`:
```yaml
operations:
archive:
guidance:
- >-
Перед openspec archive внеси в связанную задачу YouTrack оставшееся
фактическое время, учитывая только ещё не записанное. После успешной
архивации переведи задачу в конечный статус проекта по доступным полям;
не угадывай статус. Change завершён после архивации и закрытия задачи.
```
Схема задаёт порядок и формат 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.
@@ -99,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: описание функции
@@ -137,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 и таблица сериализуемого ответа. Не создавай
@@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич
## HTTP endpoint
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
правила обработки указываются в FR, а контракт помещается в самом конце
Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
Requirement:
```markdown
+9 -25
View File
@@ -62,25 +62,6 @@ artifacts:
Specs в Context. Отсутствующий индекс включай в scope только при введении
постоянных документов контекста или принятии проектом этой навигационной модели.
YouTrack:
В `context` файла `openspec/config.yaml` обязательны строки
`YouTrack project key: <KEY>` и `YouTrack application label: <APP-NAME>`.
До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные
поля и доступность/применимость тега `<APP-NAME>`. При отсутствии настройки,
тега, невозможности проверки или недоступности MCP остановись, сообщи о проблеме
и уточни конфигурацию либо дальнейшее действие. Не используй проект `Default`.
После содержательного proposal, до specs/design/tasks, создай ровно одну
задачу `Task` на change, включая `skip_specs: true`. Заголовок и описание
сформируй по причине и scope proposal, добавь slug change и тег с точным
именем из `YouTrack application label`; ключ и URL внеси в YouTrack раздел
`proposal.md`. При изменении причины, scope, capabilities или impact в proposal
обновляй связанную задачу без дубликатов. Тег приложения сохраняй до изменения настройки.
Учитывай фактическое время всей работы от Explore и подготовки proposal:
при создании задачи внеси уже затраченное; после каждого сеанса Apply добавляй
только неучтённое время отдельным work item с доступным проекту типом работы.
Финальную синхронизацию времени и статуса выполняй по `openspec instructions archive`.
requires: []
- id: specs
@@ -113,8 +94,13 @@ artifacts:
пояснения, не влияющие на поведение и не снимающие неоднозначность контракта.
Scenario:
- Автор выбирает полный или сокращённый сценарий независимо от типа FR
и части системы (процесс, БД, API, UI и другие), кроме обязательного полного HTTP-сценария.
- Выбирай формат по сложности сценария, независимо от типа FR и части системы
(процесс, БД, API, UI и другие).
- Полный Use case используй для крупных многошаговых сценариев с большим
количеством последовательных действий, а не для простых коротких требований.
- Сокращённый Use case используй для простых коротких требований, а не для
объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты
на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
- Полный сценарий содержит разделы Участники, Предусловия,
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
в таком порядке.
@@ -124,7 +110,8 @@ artifacts:
которых нет в заголовке. Контекст отсутствует.
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
- В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR.
- Каждую конечную точку HTTP описывай отдельным Requirement с полным сценарием.
- Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария
выбирай по его сложности.
Сложные правила шагов выноси в FR со ссылками из сценария.
- Основной поток и альтернативы обычного сценария включают коды
завершения, если они определены для этой функции.
@@ -285,7 +272,4 @@ apply:
контекста и его индекса. Если индекс существует или его создание входит в
tasks.md, проверь, что он соответствует фактическому набору документов.
Убедись, что требования Specs не продублированы в Context.
Для связанной задачи YouTrack после каждого рабочего сеанса запиши только
ещё не учтённое фактическое время через MCP, используя доступный тип работы.
Перед архивацией change проверь, что учтено всё время начиная с Explore.
Остановись, если столкнёшься с препятствием или потребуется уточнение.
@@ -33,7 +33,3 @@
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
создать или обновить. Если обновления не нужны, напиши это явно.
Не переноси сюда функциональные требования из OpenSpec Specs. -->
## YouTrack
- Задача: `<PROJECT-123>` — <issue URL>
@@ -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()