Template
Compare commits
6
Commits
aed0eea1ec
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b5558ec008 | ||
|
|
e2e2d0bcc2 | ||
|
|
a0fe47d4d3 | ||
|
|
f3cedcc5c3 | ||
|
|
ce62ddc704 | ||
|
|
f4b7ff3728 |
@@ -1,29 +1,236 @@
|
|||||||
# Схема OpenSpec `use-case-driven`
|
# Общие инструменты для OpenSpec и Codex
|
||||||
|
|
||||||
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
|
Репозиторий содержит три переиспользуемых артефакта:
|
||||||
базовой `spec-driven`. Она задаёт формат артефактов change и спецификаций
|
|
||||||
поведения; подробные правила схемы находятся в
|
|
||||||
[README схемы](openspec/schemas/use-case-driven/README.md).
|
|
||||||
|
|
||||||
## Чем отличается от `spec-driven`
|
| Артефакт | Назначение | Где находится |
|
||||||
|
|---|---|---|
|
||||||
|
| Схема OpenSpec `use-case-driven` | Русскоязычные спецификации поведения и workflow `proposal → specs / design → tasks → apply` | [`openspec/schemas/use-case-driven/`](openspec/schemas/use-case-driven/) |
|
||||||
|
| Заготовки `AGENTS.md` и `config.yaml` с контекстом проекта | Правила OpenSpec и Git для агента, параметры проекта и навигация по постоянным документам | [`examples/project-bootstrap/`](examples/project-bootstrap/) |
|
||||||
|
| Скилл Codex `task-tracker` | Одна задача на change: привязка, метка приложения, синхронизация, учёт времени, archive и коммит | [`skills/task-tracker/SKILL.md`](skills/task-tracker/SKILL.md) |
|
||||||
|
|
||||||
- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`.
|
Схема и скилл хранятся и развиваются здесь. Подключайте их символическими
|
||||||
Здесь используются сценарии использования без Gherkin: полные или
|
ссылками из пользовательских каталогов; обновление клона обновляет общий
|
||||||
сокращённые, связанные с функциональными требованиями.
|
источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте:
|
||||||
- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`.
|
они содержат настройки конкретного приложения.
|
||||||
Подробные правила, устойчивые контракты и обязательные ограничения
|
|
||||||
фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`.
|
|
||||||
- Master-спецификация явно описывает `Purpose`, `Границы` ответственности
|
|
||||||
capability и полный набор `Requirements`. Delta-спецификации меняют требования
|
|
||||||
стандартными операциями OpenSpec.
|
|
||||||
- Инструкции и пояснительный текст ориентированы на русский язык; технические
|
|
||||||
идентификаторы и синтаксис OpenSpec сохраняются.
|
|
||||||
|
|
||||||
## Статус
|
## 1. Схема `use-case-driven`
|
||||||
|
|
||||||
Схема находится в стадии доработки. Описаны ещё не все типы функциональных
|
В отличие от базовой `spec-driven`, схема описывает поведение полными или
|
||||||
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного
|
сокращёнными use cases без Gherkin. Один `Requirement` задаёт завершённую
|
||||||
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует,
|
функцию с одним `Scenario`; локальные `FR` фиксируют подробные правила,
|
||||||
что при подготовке спецификации будут выявлены все применимые требования — в
|
устойчивые контракты и ограничения. HTTP-контракт находится в `CONTRACT`.
|
||||||
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно
|
Master specs описывают `Purpose`, границы capability и требования; delta specs
|
||||||
учитывать при анализе изменения.
|
используют стандартные операции OpenSpec. Технический синтаксис сохраняется,
|
||||||
|
пояснения пишутся по-русски. Подробности — в [README схемы](openspec/schemas/use-case-driven/README.md).
|
||||||
|
|
||||||
|
На macOS/Linux пользовательские схемы находятся в
|
||||||
|
`${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows —
|
||||||
|
в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан.
|
||||||
|
|
||||||
|
## 2. Заготовки проектных инструкций и конфигурации
|
||||||
|
|
||||||
|
После `openspec init` перенесите в прикладной проект нужные части
|
||||||
|
[`examples/project-bootstrap/`](examples/project-bootstrap/):
|
||||||
|
|
||||||
|
- [`AGENTS.md`](examples/project-bootstrap/AGENTS.md) — навигация по контексту,
|
||||||
|
правила OpenSpec, Git-процесс и вызовы `task-tracker` в жизненном цикле change;
|
||||||
|
- [`openspec/config.yaml`](examples/project-bootstrap/openspec/config.yaml) —
|
||||||
|
выбор схемы и начальный контекст OpenSpec;
|
||||||
|
- `openspec/context/` — индекс контекста, правила ADR и шаблон решения.
|
||||||
|
|
||||||
|
Объедините заготовки с существующими файлами, сохраняя применимые инструкции
|
||||||
|
и настройки проекта. В шаблоне `AGENTS.md` задан двухэтапный Git-процесс:
|
||||||
|
первый PR содержит только планирование OpenSpec, второй — реализацию после
|
||||||
|
слияния первого PR и явной команды владельца. Для существующего проекта
|
||||||
|
объедините эти правила с его настройками целевой ветки и ревью. Заполните
|
||||||
|
в проектном `AGENTS.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Task Management
|
||||||
|
|
||||||
|
Для всех OpenSpec Changes используй скилл `task-tracker`.
|
||||||
|
|
||||||
|
Task tracker configuration:
|
||||||
|
|
||||||
|
- Project key: <KEY>
|
||||||
|
- Application label: <APP-NAME>
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
|
||||||
|
- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или
|
||||||
|
change, используй эту задачу и не создавай новую.
|
||||||
|
- При создании change без переданного ID создай или привяжи задачу после содержательного proposal.
|
||||||
|
- При существенном изменении change синхронизируй существующую задачу.
|
||||||
|
- После каждого рабочего сеанса Apply синхронизируй фактическое время.
|
||||||
|
- Перед archive выполни финальную синхронизацию; после успешной архивации
|
||||||
|
закрой задачу и закоммить изменения change. Начинай сообщение коммита с ключа
|
||||||
|
связанной задачи, затем кратко опиши изменения по-русски: `CON-27 Правка тестов`.
|
||||||
|
При ошибке archive задачу не закрывай.
|
||||||
|
- При повторном запросе возобнови незавершённую синхронизацию по существующей
|
||||||
|
связи, включая архивные changes.
|
||||||
|
|
||||||
|
Все операции управления задачами выполняй через скилл `task-tracker`.
|
||||||
|
```
|
||||||
|
|
||||||
|
`Project key` — ключ проекта в трекере, `Application label` — имя приложения,
|
||||||
|
которым маркируется каждая задача. Без обоих значений скилл не создаёт задачу.
|
||||||
|
Заполните эти значения для каждого прикладного проекта в его `AGENTS.md`.
|
||||||
|
Типовая заготовка хранится только в `examples/project-bootstrap/AGENTS.md`.
|
||||||
|
|
||||||
|
В `openspec/config.yaml` укажите `schema: use-case-driven` и дополните
|
||||||
|
предметный контекст и правила OpenSpec. Правила внешнего трекера в этот файл
|
||||||
|
не добавляются. Локальный [`openspec/config.yaml`](openspec/config.yaml)
|
||||||
|
описывает настройки самого репозитория; переносимая заготовка находится
|
||||||
|
в `examples/project-bootstrap/`.
|
||||||
|
|
||||||
|
## 3. Скилл `task-tracker`
|
||||||
|
|
||||||
|
Скилл создаёт или привязывает одну верхнеуровневую
|
||||||
|
задачу на change либо использует явно переданный ID, сохраняет метку приложения,
|
||||||
|
обновляет содержательное описание без копирования `tasks.md`, учитывает время
|
||||||
|
от Explore и коммитит изменения после успешной архивации и синхронизации задачи.
|
||||||
|
|
||||||
|
Границы компонентов:
|
||||||
|
|
||||||
|
| Компонент | Ответственность |
|
||||||
|
|---|---|
|
||||||
|
| Проектный `AGENTS.md` | Когда вызывать скилл, ключ проекта и метка приложения |
|
||||||
|
| `task-tracker` | Логические операции, связь с change и правила провайдера |
|
||||||
|
| OpenSpec | Спецификации, Change, Apply и Archive |
|
||||||
|
| MCP | Технический доступ к внешнему трекеру |
|
||||||
|
|
||||||
|
Текущая реализация использует YouTrack MCP; настройте его доступность в Codex.
|
||||||
|
Выбор поля `Labels` или YouTrack-тега, синхронизация статусов и учёт времени описаны
|
||||||
|
[в едином SKILL.md](skills/task-tracker/SKILL.md).
|
||||||
|
Для смены трекера меняйте только скилл. Перенос существующих
|
||||||
|
задач требует явного соответствия ID, чтобы не потерять историю связи.
|
||||||
|
|
||||||
|
### Связь, сохраняющаяся после archive
|
||||||
|
|
||||||
|
Источник связи — `task-tracker.yaml` внутри каталога change:
|
||||||
|
|
||||||
|
```text
|
||||||
|
openspec/changes/<change-id>/task-tracker.yaml
|
||||||
|
↓ openspec archive
|
||||||
|
openspec/changes/archive/<archive-name>/task-tracker.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Archive переносит весь каталог, включая файл связи. После успешного переноса
|
||||||
|
закройте YouTrack-задачу и зафиксируйте относящиеся к change изменения
|
||||||
|
Git-коммитом с сообщением в формате «ключ связанной задачи + краткое описание
|
||||||
|
изменений по-русски», например `CON-27 Правка тестов`. Исходный `change_id`,
|
||||||
|
непрозрачный `task_id`, URL и снимок проектных параметров остаются в файле.
|
||||||
|
Не пытайтесь восстанавливать ID только из архивного имени: change сам может
|
||||||
|
начинаться с даты. Сохраняйте файл в Git вместе с change и архивом.
|
||||||
|
Формат и правила восстановления — в
|
||||||
|
[`SKILL.md`](skills/task-tracker/SKILL.md).
|
||||||
|
|
||||||
|
Запись содержит незавершённую операцию и журнал уже учтённого времени.
|
||||||
|
После ошибки MCP скилл проверяет внешнее состояние перед повтором. При
|
||||||
|
неизвестном результате создания или записи времени автоматический повтор
|
||||||
|
запрещён до сверки. Если задача не закрылась после archive, связь и pending
|
||||||
|
остаются в архиве для следующей сессии.
|
||||||
|
|
||||||
|
Это агентный workflow: самостоятельный запуск `openspec archive` вне Codex
|
||||||
|
переносит файл, но не вызывает скилл, не синхронизирует задачу и не создаёт
|
||||||
|
коммит. Для последующей
|
||||||
|
синхронизации попросите Codex использовать `$task-tracker` для архивного change.
|
||||||
|
При одновременной работе нескольких агентов требуется согласовать операции:
|
||||||
|
файл связи не является распределённой блокировкой.
|
||||||
|
|
||||||
|
## Подключение из домашней директории
|
||||||
|
|
||||||
|
### macOS и Linux
|
||||||
|
|
||||||
|
Замените `/path/to/openspec-schema` на абсолютный путь к своему клону:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
tooling_repo="/path/to/openspec-schema"
|
||||||
|
schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas"
|
||||||
|
skills_dir="$HOME/.agents/skills"
|
||||||
|
|
||||||
|
mkdir -p "$schemas_dir" "$skills_dir"
|
||||||
|
ln -s "$tooling_repo/openspec/schemas/use-case-driven" \
|
||||||
|
"$schemas_dir/use-case-driven"
|
||||||
|
ln -s "$tooling_repo/skills/task-tracker" "$skills_dir/task-tracker"
|
||||||
|
```
|
||||||
|
|
||||||
|
Codex обнаруживает пользовательские скиллы в `~/.agents/skills` и поддерживает
|
||||||
|
ссылки на каталоги скиллов. Если новый скилл не появился, перезапустите Codex.
|
||||||
|
См. [официальную документацию о скиллах](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
|
||||||
|
|
||||||
|
### Windows PowerShell
|
||||||
|
|
||||||
|
Junction позволяет использовать исходные каталоги без копирования:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$toolingRepo = 'D:\path\to\openspec-schema'
|
||||||
|
$schemasDir = if ($env:XDG_DATA_HOME) {
|
||||||
|
Join-Path $env:XDG_DATA_HOME 'openspec\schemas'
|
||||||
|
} else {
|
||||||
|
Join-Path $env:LOCALAPPDATA 'openspec\schemas'
|
||||||
|
}
|
||||||
|
$skillsDir = Join-Path $HOME '.agents\skills'
|
||||||
|
New-Item -ItemType Directory -Force -Path $schemasDir, $skillsDir
|
||||||
|
New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') `
|
||||||
|
-Target (Join-Path $toolingRepo 'openspec\schemas\use-case-driven')
|
||||||
|
New-Item -ItemType Junction -Path (Join-Path $skillsDir 'task-tracker') `
|
||||||
|
-Target (Join-Path $toolingRepo 'skills\task-tracker')
|
||||||
|
```
|
||||||
|
|
||||||
|
Команды предполагают, что пути назначения ещё свободны. Если схема уже
|
||||||
|
подключена, создайте только ссылку на скилл. Перед заменой существующей
|
||||||
|
папки/ссылки проверьте её содержимое и источник.
|
||||||
|
|
||||||
|
Проверьте схему из каталога прикладного проекта:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
openspec schema which use-case-driven
|
||||||
|
openspec schema validate use-case-driven
|
||||||
|
```
|
||||||
|
|
||||||
|
Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex.
|
||||||
|
Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`.
|
||||||
|
|
||||||
|
Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над
|
||||||
|
пользовательской. Кроме того, схема ссылается на вспомогательные файлы
|
||||||
|
относительно проекта (`validate_format.py`, `patterns/`). Для доступа к ним
|
||||||
|
создайте в проекте ссылку `openspec/schemas/use-case-driven` на ту же общую
|
||||||
|
схему либо адаптируйте пути инструкций. Пользовательская ссылка сама
|
||||||
|
эти проектные пути не создаёт.
|
||||||
|
|
||||||
|
## Переход со старой интеграции
|
||||||
|
|
||||||
|
В прикладных проектах перенесите ключ и метку из старого `context` в
|
||||||
|
`AGENTS.md`, добавьте lifecycle из заготовки и подключите скилл. Удалите
|
||||||
|
старые инструкции трекера из `config.yaml`, включая
|
||||||
|
`operations.archive.guidance`; остальные контекст и правила сохраните.
|
||||||
|
Если схема скопирована в проект вместо ссылки, обновите также её копию.
|
||||||
|
|
||||||
|
Существующие ID/URL в proposal сохраняйте до проверенной привязки.
|
||||||
|
Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после
|
||||||
|
проверки задачи. Архивным changes без однозначной связи новую задачу
|
||||||
|
автоматически не создаёт.
|
||||||
|
|
||||||
|
## Проверки и ограничения
|
||||||
|
|
||||||
|
```sh
|
||||||
|
openspec schema validate use-case-driven
|
||||||
|
python3 -m unittest discover -s tests -v
|
||||||
|
```
|
||||||
|
|
||||||
|
Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI
|
||||||
|
во временных каталогах и проверяют сохранение связи и журнала при успешном
|
||||||
|
archive, отказе валидации и конфликте архива. Они не обращаются к трекеру;
|
||||||
|
без CLI пропускаются. Frontmatter скилла можно отдельно проверить
|
||||||
|
`scripts/quick_validate.py` из установленного `skill-creator`.
|
||||||
|
|
||||||
|
Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие
|
||||||
|
конфигурации описаны в скилле. Их внешнее выполнение требует доступного
|
||||||
|
провайдера; инструктивный скилл не даёт программных гарантий исполнения.
|
||||||
|
Для сквозной проверки используйте согласованный тестовый проект, не создавайте
|
||||||
|
тестовые задачи в рабочем проекте без согласования.
|
||||||
|
|
||||||
|
Схема продолжает развиваться: не все типы FR и форматы контрактов имеют
|
||||||
|
подробные паттерны, например FR `[UI]`. Применимые требования безопасности,
|
||||||
|
аудита и ролевой модели нужно явно учитывать при анализе изменения.
|
||||||
|
|||||||
@@ -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`.
|
||||||
@@ -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/`.
|
||||||
@@ -1,13 +1,5 @@
|
|||||||
schema: use-case-driven
|
schema: use-case-driven
|
||||||
|
|
||||||
context: |
|
|
||||||
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
|
|
||||||
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
|
|
||||||
запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
|
|
||||||
конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
|
|
||||||
шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
|
|
||||||
Proposed; не помечай решение Accepted без явного принятия владельцем решения.
|
|
||||||
|
|
||||||
rules:
|
rules:
|
||||||
tasks:
|
tasks:
|
||||||
- >-
|
- >-
|
||||||
|
|||||||
@@ -5,12 +5,20 @@
|
|||||||
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
|
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
|
||||||
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
|
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
|
||||||
|
|
||||||
|
## Git-процесс проекта
|
||||||
|
|
||||||
|
Схема задаёт порядок и формат OpenSpec-артефактов. Правила веток, двух
|
||||||
|
последовательных PR, ручного слияния и явной команды продолжения находятся
|
||||||
|
в [шаблоне проектных инструкций](../../../examples/project-bootstrap/AGENTS.md).
|
||||||
|
При подключении схемы включите правила из этого шаблона в проектный
|
||||||
|
`AGENTS.md` и согласуйте имя целевой ветки с настройками репозитория.
|
||||||
|
|
||||||
## Уровни спецификации
|
## Уровни спецификации
|
||||||
|
|
||||||
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
||||||
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
|
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
|
||||||
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
||||||
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
- Scenario — один из двух форматов Use case: полный или сокращённый. Формат определяется сложностью сценария, независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||||||
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
||||||
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
||||||
|
|
||||||
@@ -68,8 +76,11 @@ Markdown-рендерер автоматически создаёт якоря
|
|||||||
|
|
||||||
## Форматы Use case
|
## Форматы Use case
|
||||||
|
|
||||||
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
|
- Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий.
|
||||||
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
|
- Сокращённый Use case используй для простых коротких требований. Рассматривай их как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||||
|
- Выбирай формат по сложности: не используй полный Use case для простых требований, а сокращённый — для объёмных многошаговых сценариев. Правило действует и для HTTP endpoint.
|
||||||
|
|
||||||
|
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращённый Use case содержит только Основной поток; каждый шаг ссылается на FR.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
#### Scenario: Сокращенный use case: описание функции
|
#### Scenario: Сокращенный use case: описание функции
|
||||||
@@ -106,8 +117,8 @@ FR задаёт тексты, дальнейшие действия и связ
|
|||||||
|
|
||||||
## HTTP-контракт в Requirement
|
## HTTP-контракт в Requirement
|
||||||
|
|
||||||
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
|
Каждый endpoint оформляется отдельным Requirement. Формат Use case выбирается
|
||||||
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
|
по сложности сценария; сложные правила шагов выносятся в FR. После всех FR, в конце
|
||||||
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
|
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
|
||||||
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
|
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
|
||||||
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
|
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
|
||||||
@@ -151,6 +162,21 @@ Scenario в таких операциях не создаётся. В delta со
|
|||||||
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
|
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
|
||||||
Форматирование спецификации само по себе не реализует этот контракт в приложении.
|
Форматирование спецификации само по себе не реализует этот контракт в приложении.
|
||||||
|
|
||||||
|
## Постоянный контекст проекта
|
||||||
|
|
||||||
|
Для начальной настройки проекта можно скопировать заготовки из
|
||||||
|
[`examples/project-bootstrap/`](../../../examples/project-bootstrap/):
|
||||||
|
`AGENTS.md`, `openspec/context/index.md` и инструкции с шаблоном ADR. Они не
|
||||||
|
устанавливаются вместе с пользовательской ссылкой на схему и должны быть
|
||||||
|
адаптированы к структуре конкретного проекта.
|
||||||
|
|
||||||
|
При подготовке каждого change оценивай влияние на постоянный контекст в разделе
|
||||||
|
`Project Context` файла `proposal.md`. Если индекс контекста существует, изучай
|
||||||
|
релевантные документы выборочно. В design сверяй необходимость ADR и других
|
||||||
|
документов; задачи на их создание или обновление, включая актуализацию индекса,
|
||||||
|
добавляй в `tasks.md`. Выполняй эти задачи в рамках OpenSpec Apply. Не переноси
|
||||||
|
функциональные требования из Specs в Context.
|
||||||
|
|
||||||
## Архитектурные решения (ADR)
|
## Архитектурные решения (ADR)
|
||||||
|
|
||||||
Храни ADR проекта в `openspec/context/adr/` и называй файлы
|
Храни ADR проекта в `openspec/context/adr/` и называй файлы
|
||||||
|
|||||||
@@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич
|
|||||||
|
|
||||||
## HTTP endpoint
|
## HTTP endpoint
|
||||||
|
|
||||||
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
|
Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
|
||||||
правила обработки указываются в FR, а контракт помещается в самом конце
|
по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
|
||||||
Requirement:
|
Requirement:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
|
|||||||
@@ -10,72 +10,58 @@ artifacts:
|
|||||||
description: Начальный документ предложения, описывающий изменение
|
description: Начальный документ предложения, описывающий изменение
|
||||||
template: proposal.md
|
template: proposal.md
|
||||||
instruction: |
|
instruction: |
|
||||||
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
|
Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
|
||||||
OpenSpec и технические идентификаторы, названия API, файлов,
|
идентификаторы, названия API, файлов, инструментов, команды и коды не переводи.
|
||||||
инструментов, команд и коды без перевода.
|
|
||||||
|
|
||||||
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение.
|
Объясни, ПОЧЕМУ требуется изменение. Объём — 1–2 страницы; детали
|
||||||
|
реализации относятся к design.md.
|
||||||
|
|
||||||
Разделы:
|
Разделы:
|
||||||
- **Why**: 1–2 предложения о проблеме или возможности. Какую проблему
|
- **Why**: 1–2 предложения о проблеме или возможности и причинах изменения сейчас.
|
||||||
решает изменение? Почему его нужно сделать сейчас?
|
- **What Changes**: Точный список новых возможностей, изменений и удалений;
|
||||||
- **What Changes**: Список изменений. Точно опиши новые возможности,
|
несовместимые изменения помечай **BREAKING**.
|
||||||
изменения и удаления. Помечай несовместимые изменения как **BREAKING**.
|
- **Capabilities**: Создаваемые или изменяемые спецификации отдельных
|
||||||
- **Capabilities**: Укажи, какие спецификации будут созданы или изменены:
|
бизнес-функций или понятных результатов. Сохраняй полный иерархический
|
||||||
Capability представляет отдельную бизнес-функцию или понятный результат;
|
путь, например `domain/capability-name`.
|
||||||
сохраняй полный иерархический путь, например `domain/capability-name`.
|
Короткий читаемый префикс Requirement для новой capability: первые три буквы однословного
|
||||||
Для новой capability сформируй короткий читаемый префикс Requirement:
|
сегмента или первые буквы частей сегмента с дефисами; верхний регистр,
|
||||||
для однословного сегмента используй первые три буквы, для сегмента с
|
точки и порядок сегментов (`domain/capability-name` → `DOM.CN`).
|
||||||
дефисами — первые буквы его частей. Приводи сокращения к верхнему
|
Проверь уникальность префикса по Requirement ID основных спецификаций;
|
||||||
регистру, разделяй сегменты кода точкой и сохраняй их порядок:
|
при совпадении удлиняй сокращения новых сегментов до уникальности. Существующие префиксы
|
||||||
`domain/capability-name` → `DOM.CN`.
|
не меняй, включая переименование capability.
|
||||||
Перед назначением проверь уникальность префикса по Requirement ID в
|
- **New Capabilities**: Перечисли новые capabilities; для каждой создай
|
||||||
основных спецификациях проекта. Если префикс занят, удлиняй сокращения
|
`specs/<capability-path>/spec.md`; новые сегменты пиши в `kebab-case`,
|
||||||
новых сегментов до уникальности; уже используемые префиксы не меняй.
|
следуя структуре проекта.
|
||||||
Сохраняй префикс при переименовании capability.
|
- **Modified Capabilities**: Укажи существующие capabilities только при
|
||||||
- **New Capabilities**: Перечисли добавляемые capabilities. Для каждой
|
изменении описанного поведения, а не деталей реализации. Создай delta
|
||||||
создай `specs/<capability-path>/spec.md`. Используй `kebab-case` для
|
spec по точному существующему пути внутри `openspec/specs/`; если
|
||||||
новых сегментов пути (например, `user-auth` или `identity/user-auth`)
|
требования не меняются, оставь список пустым.
|
||||||
и следуй принятой в проекте структуре спецификаций.
|
- **Impact**: Затронутые код, API, зависимости и системы.
|
||||||
- **Modified Capabilities**: Перечисли существующие capabilities, чьи
|
- **Project Context**: Создаваемые или обновляемые постоянные документы,
|
||||||
REQUIREMENTS меняются. Добавляй сюда capability только при изменении
|
включая решение о необходимости ADR. Отсутствие изменений укажи явно.
|
||||||
поведения, описанного в спецификации, а не только деталей реализации.
|
|
||||||
Для каждой создай delta spec по точному существующему пути внутри
|
|
||||||
`openspec/specs/`. Оставь список пустым, если требования не меняются.
|
|
||||||
- **Impact**: Затронутые участки кода, API, зависимости и системы.
|
|
||||||
|
|
||||||
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs.
|
Перед заполнением Capabilities изучи существующие specs:
|
||||||
Перед его заполнением изучи существующие спецификации: выполни
|
1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes.
|
||||||
`openspec list --specs`, чтобы получить список capabilities проекта.
|
2. Для подходящих вариантов — `openspec show "<spec-id>" --type spec --json --no-scenarios`:
|
||||||
Для подходящих вариантов выполни `openspec show "<spec-id>" --type spec --json --no-scenarios`.
|
обзор назначения и требований без загрузки целых спецификаций.
|
||||||
Команда вернёт назначение capability и тексты требований, не загружая
|
3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком,
|
||||||
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам
|
включая сценарии: `openspec show "<spec-id>" --type spec`.
|
||||||
только для зарегистрированного отдельного хранилища и сохраняй
|
Добавляй `--store "<id>"` к этим командам только для зарегистрированного
|
||||||
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя,
|
отдельного хранилища. Сохраняй `--type spec`, чтобы избежать неоднозначности
|
||||||
без этого параметра возникнет неоднозначность при выборе. Команда
|
при одинаковых именах change и spec. Используй точный путь существующей
|
||||||
`openspec list` без `--specs` показывает активные изменения (`changes`),
|
capability, не создавай похожее имя. Каждой перечисленной capability
|
||||||
а не спецификации, поэтому не отражает уже описанное в проекте поведение.
|
соответствует файл спецификации.
|
||||||
Используй точный путь
|
|
||||||
существующей capability, не создавай похожее имя.
|
|
||||||
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
|
|
||||||
описано и что нужно изменить, прочитай каждую подходящую спецификацию
|
|
||||||
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
|
|
||||||
(с тем же правилом для `--store`). Для каждой перечисленной capability
|
|
||||||
потребуется соответствующий файл спецификации.
|
|
||||||
|
|
||||||
В каждом изменении (`change`) должна быть указана хотя бы одна новая или
|
Change должен содержать новую/изменяемую capability либо `skip_specs: true`
|
||||||
изменяемая capability либо явный отказ от спецификаций: `openspec validate`
|
в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta.
|
||||||
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не
|
`skip_specs: true` допустим только без изменения описанного поведения
|
||||||
задано `skip_specs: true`.
|
(чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки.
|
||||||
Используй `skip_specs: true` только когда поведение, описываемое
|
|
||||||
спецификациями, не меняется (например, при чистом рефакторинге, изменении
|
|
||||||
инструментов или документации). Не добавляй требование только ради
|
|
||||||
прохождения проверки.
|
|
||||||
|
|
||||||
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на
|
Для Project Context прочитай существующий `openspec/context/index.md` и
|
||||||
способе реализации: детали реализации относятся к design.md.
|
относящиеся к change документы из него. Не копируй функциональные требования
|
||||||
|
Specs в Context. Отсутствующий индекс включай в scope только при введении
|
||||||
|
постоянных документов контекста или принятии проектом этой навигационной модели.
|
||||||
|
|
||||||
Этот документ задаёт основу: на нём строятся specs, design и tasks.
|
|
||||||
requires: []
|
requires: []
|
||||||
|
|
||||||
- id: specs
|
- id: specs
|
||||||
@@ -83,141 +69,113 @@ artifacts:
|
|||||||
description: Подробные спецификации изменения
|
description: Подробные спецификации изменения
|
||||||
template: spec.md
|
template: spec.md
|
||||||
instruction: |
|
instruction: |
|
||||||
Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные
|
Пиши пояснения по-русски; обязательные заголовки OpenSpec, идентификаторы,
|
||||||
заголовки OpenSpec, идентификаторы, названия API и коды без перевода.
|
названия API и коды не переводи.
|
||||||
|
|
||||||
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
|
Описывай наблюдаемое поведение и устойчивые контракты в формате без Gherkin.
|
||||||
Правила ниже применяются к основным спецификациям и к полным блокам
|
Правила применяются к основным specs и полным блокам ADDED/MODIFIED в delta.
|
||||||
ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin.
|
|
||||||
|
|
||||||
Иерархия и границы:
|
Иерархия и границы:
|
||||||
- Capability описывает отдельную бизнес-функцию или понятный результат.
|
- Capability — отдельная бизнес-функция или понятный результат; сохраняй
|
||||||
- Сохраняй полный иерархический путь, например domain/capability-name.
|
полный иерархический путь, например domain/capability-name.
|
||||||
- Основная спецификация содержит раздел ## Границы между Purpose и
|
- Основная спецификация содержит раздел ## Границы между Purpose и
|
||||||
Requirements. Кратко укажи, за что отвечает capability, что входит в её
|
Requirements: кратко укажи ответственность, область, исключения и владельцев
|
||||||
область и что находится за её пределами или относится к другой capability
|
соседних обязанностей — другие capabilities или приложения. Не дублируй
|
||||||
либо приложению. Не дублируй Requirements и FR.
|
Requirements и FR; сведения об ответственности допустимы без задания поведения.
|
||||||
- Один Requirement описывает одну завершённую техническую функцию.
|
- Requirement — одна завершённая техническая функция, стабильный ID вида
|
||||||
- Не дроби один процесс на Requirements для чтения, валидации и записи.
|
AREA.CAP-01 и ровно один Scenario. Не дроби процесс на чтение, валидацию и запись.
|
||||||
- Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario.
|
- Префикс — сокращения сегментов пути capability через точки; проверяй
|
||||||
- Префикс Requirement состоит из сокращений сегментов пути capability,
|
уникальность по ID основных specs. Номер уникален внутри capability;
|
||||||
разделённых точками; его уникальность проверяется по ID в основных
|
|
||||||
спецификациях. Номер Requirement уникален внутри capability. Существующие
|
|
||||||
унаследованные Requirements могут сохранять прежние ID.
|
унаследованные Requirements могут сохранять прежние ID.
|
||||||
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
|
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
|
||||||
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
|
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
|
||||||
- В Requirements и FR включай только сведения, меняющие наблюдаемое
|
- В Requirements и FR оставляй только наблюдаемое поведение, устойчивые
|
||||||
поведение, устойчивый контракт или обязательное техническое ограничение.
|
контракты и обязательные технические ограничения. Удаляй повторы и
|
||||||
Удаляй повторы, пояснения и формулировки, которые не меняют поведение и
|
пояснения, не влияющие на поведение и не снимающие неоднозначность контракта.
|
||||||
не снимают неоднозначность контракта. В ## Границы оставляй краткие
|
|
||||||
сведения об ответственности и владении, необходимые для понимания
|
|
||||||
области capability, даже если они сами по себе не задают поведение.
|
|
||||||
|
|
||||||
Scenario:
|
Scenario:
|
||||||
- Поддерживаются два формата сценария использования: полный и
|
- Выбирай формат по сложности сценария, независимо от типа FR и части системы
|
||||||
сокращённый. Автор выбирает формат по ситуации, независимо от типа FR
|
(процесс, БД, API, UI и другие).
|
||||||
и описываемой части системы: процесса выполнения, БД, API, UI и других.
|
- Полный Use case используй для крупных многошаговых сценариев с большим
|
||||||
- Полный сценарий использования содержит разделы Участники, Предусловия,
|
количеством последовательных действий, а не для простых коротких требований.
|
||||||
|
- Сокращённый Use case используй для простых коротких требований, а не для
|
||||||
|
объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты
|
||||||
|
на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||||
|
- Полный сценарий содержит разделы Участники, Предусловия,
|
||||||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||||||
в таком порядке.
|
в таком порядке.
|
||||||
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`;
|
- Сокращённый сценарий содержит только `##### Основной поток`, без других
|
||||||
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
|
разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на FR.
|
||||||
участников, предусловий, альтернатив и ошибок, результата или кодов
|
- В обычном сценарии Назначение опционально: добавляй только сведения,
|
||||||
завершения и не задаёт отдельные ветвления во время выполнения.
|
которых нет в заголовке. Контекст отсутствует.
|
||||||
- В обычном сценарии Назначение опционально; добавляй только если оно
|
|
||||||
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
|
|
||||||
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
||||||
- Шаг сценария выполнения может назвать действие, конечную точку API или
|
- В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR.
|
||||||
способ записи и сослаться на FR.
|
- Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария
|
||||||
- Каждую конечную точку HTTP описывай в отдельном Requirement с полным
|
выбирай по его сложности.
|
||||||
сценарием использования.
|
Сложные правила шагов выноси в FR со ссылками из сценария.
|
||||||
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
|
|
||||||
- Основной поток и альтернативы обычного сценария включают коды
|
- Основной поток и альтернативы обычного сценария включают коды
|
||||||
завершения, если они определены для этой функции.
|
завершения, если они определены для этой функции.
|
||||||
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
|
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
|
||||||
сообщений и дальнейшая логика располагаются за пределами Scenario.
|
сообщений и дальнейшая логика располагаются за пределами Scenario.
|
||||||
- Единственная таблица Scenario — Коды завершения с колонками
|
- Единственная таблица Scenario — Коды завершения с колонками
|
||||||
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
|
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
|
||||||
- Код сам сообщает смысл итога; дополнительный этап или свободный текст
|
- Код сам сообщает смысл итога без дополнительного этапа или свободного текста.
|
||||||
не должен требоваться для понимания кода. События промежуточных шагов
|
Промежуточные события не являются кодами завершения; не создавай код для каждой диагностики.
|
||||||
не являются кодами завершения. Не создавай код для каждой диагностики.
|
- Каждый код ссылается на локальные FR с дальнейшей логикой, текстом или правилами результата.
|
||||||
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
|
|
||||||
логику, текст или применимые правила результата.
|
|
||||||
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
|
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
|
||||||
содержательного текста без адресов Markdown-ссылок.
|
содержательного текста без адресов Markdown-ссылок.
|
||||||
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
|
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
|
||||||
|
|
||||||
Функциональные требования:
|
Функциональные требования:
|
||||||
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
|
- После Scenario идёт `#### Функциональные требования` с заголовками
|
||||||
- Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее.
|
`##### <requirement-id>.FR-NN [метка]: <название>`; метка опциональна.
|
||||||
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
|
Локальная нумерация начинается с FR-01 в каждом Requirement.
|
||||||
Номер начинается с FR-01 в каждом Requirement.
|
- FR — отдельное понятное правило или связанный контракт;
|
||||||
- FR содержит отдельное понятное правило или связанный контракт; не дроби
|
не дроби связную логику на множество атомарных FR.
|
||||||
связную логику на множество атомарных FR.
|
- FR без метки — логика, правила или последовательность шагов.
|
||||||
- Обычный FR без метки описывает логику, правила или последовательность
|
Метки [DB], [API], [UI] ставь сразу после ID; они не входят в ID и не меняют slug.
|
||||||
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
|
- [DB] — структура БД; для таблицы следуй
|
||||||
или [UI]; метка не входит в ID и не меняет slug ссылки.
|
|
||||||
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
|
|
||||||
контракт сообщения или технического лога. Контракт конечной точки HTTP
|
|
||||||
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
|
|
||||||
UI; детальный паттерн будет добавлен отдельно.
|
|
||||||
- Для FR [DB] с таблицей БД следуй паттерну
|
|
||||||
`openspec/schemas/use-case-driven/patterns/database-table.md`.
|
`openspec/schemas/use-case-driven/patterns/database-table.md`.
|
||||||
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
|
- [API] — контракт сообщения или технического лога; сериализуемое сообщение
|
||||||
`openspec/schemas/use-case-driven/patterns/message-contract.md`.
|
оформляй по `openspec/schemas/use-case-driven/patterns/message-contract.md`.
|
||||||
- Контракт конечной точки HTTP не оформляй отдельными FR. После раздела
|
- [UI] — требования к UI; детальный паттерн будет добавлен отдельно.
|
||||||
Функциональные требования добавляй завершающий раздел CONTRACT с
|
- HTTP-контракт размещай после Функциональных требований в завершающем
|
||||||
подразделами Request и Response в таком порядке. В Request указывай
|
CONTRACT, не в отдельных FR. Подразделы — Request, затем Response.
|
||||||
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
|
В Request указывай один HTTP-метод и путь, явно отмечай отсутствие тела.
|
||||||
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
|
Таблицы тела запроса и ответа оформляй по message-contract.md.
|
||||||
- В таблице Response раздела CONTRACT укажи для каждого поля источник
|
- В response-таблицах для каждого поля укажи источник или правило формирования:
|
||||||
значения или правило его формирования в последней колонке.
|
в последней колонке CONTRACT и в «Формирование значения» для FR [API].
|
||||||
- В таблице ответа контракта FR [API] укажи для каждого поля источник
|
- Не добавляй HTML-якоря <a id="..."></a>; используй Markdown-якоря заголовков.
|
||||||
значения или правило его формирования в колонке «Формирование значения».
|
- Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка,
|
||||||
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
|
например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
|
||||||
якоря из заголовков Requirement и FR.
|
|
||||||
- Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его
|
|
||||||
заголовка, например
|
|
||||||
[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID
|
|
||||||
используется и для ссылки внутри Requirement, и для ссылки на другой
|
|
||||||
Requirement.
|
|
||||||
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
||||||
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
||||||
новые FR добавляй в конец. Порядок первого документа последовательный.
|
новые FR добавляй в конец. Порядок первого документа последовательный.
|
||||||
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
|
- Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия,
|
||||||
сообщения/действия, если это часть контракта. Параметры сообщений
|
если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода.
|
||||||
являются данными, а не скрытым значением кода.
|
- При отличии смыслового кода от текущего поведения явно опиши в FR соответствие
|
||||||
- Если смысловой код спецификации отличается от текущего поведения системы,
|
и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением.
|
||||||
явно опиши соответствие и статус реализации в FR. Не утверждай,
|
|
||||||
что новый код или текст уже возвращается приложением.
|
|
||||||
|
|
||||||
Работа с OpenSpec:
|
Работа с OpenSpec:
|
||||||
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
|
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
|
||||||
- Основная спецификация следует краткой схеме templates/main-spec.md; это формат-
|
- Основная spec: Purpose, ## Границы и полный актуальный набор Requirements.
|
||||||
ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы
|
Ориентир формата — templates/main-spec.md, не генерируемый артефакт.
|
||||||
и полный актуальный набор Requirements.
|
|
||||||
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
|
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
|
||||||
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
|
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
|
||||||
- Для новой capability delta-спецификация начинается с ## Purpose
|
- Для новой capability начинай delta с ## Purpose (не менее 50 знаков);
|
||||||
(не менее 50 знаков). Для существующей capability Purpose в delta не добавляй.
|
для существующей Purpose не добавляй.
|
||||||
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
|
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR;
|
||||||
Его заголовок должен совпадать с заголовком соответствующего Requirement
|
заголовок совпадает с соответствующим Requirement основной spec.
|
||||||
в основной спецификации.
|
|
||||||
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
|
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
|
||||||
Это операции над требованиями, не сценарии технических функций.
|
Это операции над требованиями, не сценарии технических функций.
|
||||||
- При копировании блоков в delta сохраняй ID Requirements, номера и
|
- В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками.
|
||||||
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
|
Для ссылок на неизменённый Requirement основной spec проверяй delta
|
||||||
неизменённый Requirement основной спецификации, проверяй delta с
|
с `--base <master-spec>`.
|
||||||
`--base <master-spec>`.
|
- Без изменения поведения (чистое форматирование, инструменты, рефакторинг)
|
||||||
- Не создавай delta для чистого форматирования, изменений инструментов
|
используй `skip_specs: true`, не создавай delta.
|
||||||
или рефакторинга. Для изменения без изменения поведения используй
|
- Проверки: `openspec schema validate use-case-driven`; для spec —
|
||||||
`skip_specs: true`.
|
`openspec validate` и `python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids <spec-path>`.
|
||||||
- Проверь schema через openspec schema validate use-case-driven.
|
Для неизменённых specs со старыми ID флаг не нужен. OpenSpec не проверяет все правила формата.
|
||||||
- Проверь spec через openspec validate и отдельно через
|
|
||||||
python3 openspec/schemas/use-case-driven/validate_format.py
|
|
||||||
--require-qualified-ids <spec-path>. Для неизменённых спецификаций
|
|
||||||
со старыми ID этот флаг не нужен.
|
|
||||||
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
|
|
||||||
requires:
|
requires:
|
||||||
- proposal
|
- proposal
|
||||||
|
|
||||||
@@ -226,59 +184,38 @@ artifacts:
|
|||||||
description: Техническое описание решения и деталей реализации
|
description: Техническое описание решения и деталей реализации
|
||||||
template: design.md
|
template: design.md
|
||||||
instruction: |
|
instruction: |
|
||||||
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
|
Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические
|
||||||
OpenSpec и технические идентификаторы, названия файлов, инструментов
|
идентификаторы, названия файлов, инструментов и команды не переводи.
|
||||||
и команд без перевода.
|
|
||||||
|
|
||||||
Создай документ design, объясняющий, КАК реализовать изменение.
|
Design объясняет, КАК реализовать изменение: архитектуру и подход, не пошаговый код.
|
||||||
|
|
||||||
Когда добавлять design.md (достаточно любого из условий):
|
Добавляй design.md при любом из условий:
|
||||||
- Изменение затрагивает несколько сервисов или модулей либо вводит новый
|
- Несколько сервисов/модулей или новый архитектурный подход.
|
||||||
архитектурный подход.
|
- Внешняя зависимость или существенное изменение модели данных.
|
||||||
- Добавляется внешняя зависимость или существенно меняется модель данных.
|
- Сложности безопасности, производительности или миграции.
|
||||||
- Есть сложность, связанная с безопасностью, производительностью или
|
- Технические решения для устранения неоднозначности до разработки.
|
||||||
миграцией.
|
|
||||||
- До начала разработки нужно принять технические решения, чтобы устранить
|
|
||||||
неоднозначность.
|
|
||||||
|
|
||||||
Разделы:
|
Разделы:
|
||||||
- **Context**: Только текущее состояние и ограничения, необходимые для
|
- **Context**: Только текущее состояние и ограничения для объяснения подхода.
|
||||||
объяснения подхода. Причины изменения смотри в proposal, не повторяй их
|
- **Goals / Non-Goals**: Что решение обеспечивает и исключает; границы решения без повтора scope proposal.
|
||||||
(например: «См. proposal.md — Why»).
|
- **Decisions**: Ключевые технические решения, их обоснование и рассмотренные альтернативы.
|
||||||
- **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает.
|
- **Risks / Trade-offs**: Ограничения и проблемы в формате [Риск] → [Меры снижения].
|
||||||
Не повторяй область работ из proposal; указывай только границы решения.
|
- **Migration Plan**: Развёртывание и откат, если применимо.
|
||||||
- **Decisions**: Ключевые технические решения и их обоснование: почему
|
- **Open Questions**: Только безопасно отложенные вопросы, не влияющие на
|
||||||
выбран один вариант вместо другого. Укажи рассмотренные альтернативы.
|
specs, подход или состав задач. При отсутствии вопросов раздел не добавляй.
|
||||||
- **Risks / Trade-offs**: Известные ограничения и возможные проблемы.
|
Влияющие вопросы выясни с пользователем сейчас, не подменяй ответ предположением.
|
||||||
Формат: [Риск] → [Меры снижения].
|
|
||||||
- **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо.
|
|
||||||
- **Open Questions**: Неизвестные, которые можно безопасно выяснить позже,
|
|
||||||
не меняя спецификации, подход или состав задач. Не добавляй, если таких
|
|
||||||
вопросов нет.
|
|
||||||
|
|
||||||
Открытые вопросы предназначены для действительно отложенных решений, а не
|
Вместо повтора причин и состава изменения ссылайся на proposal, вместо
|
||||||
для пропущенных решений. Если ответ может изменить спецификации, выбранный
|
копирования требований — на specs, используя Requirement ID и локальные FR.
|
||||||
подход или состав задач, выясни его сейчас: спроси пользователя, а не
|
|
||||||
делай предположение.
|
|
||||||
|
|
||||||
Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода.
|
Сверь Project Context proposal с design: нужны ли новые/обновлённые постоянные
|
||||||
В proposal описаны причины и состав изменения, в design — способ
|
документы и индекс? В Context ссылайся на требования Specs без дублирования.
|
||||||
реализации. Ссылайся на proposal для обоснования и на specs для требований;
|
|
||||||
если раздел только повторяет их, дай ссылку вместо повтора.
|
|
||||||
|
|
||||||
Ссылайся на Requirement ID и локальные FR; описывай решения реализации
|
Перед проектированием прочитай применимые принятые ADR в `openspec/context/adr/`
|
||||||
без копирования требований.
|
и укажи ID в Decisions. Для долгосрочного архитектурного решения или замены
|
||||||
|
принятого запланируй новый ADR по `openspec/schemas/use-case-driven/templates/adr.md`
|
||||||
Перед проектированием прочитай применимые принятые ADR из
|
со статусом Proposed; самостоятельно не принимай его. Конфликт с действующим
|
||||||
`openspec/context/adr/` и укажи их идентификаторы в Decisions. Если
|
ADR явно опиши и получи решение пользователя до выбора расходящегося подхода.
|
||||||
изменение принимает долгосрочное архитектурное решение или заменяет
|
|
||||||
принятое решение, запланируй создание нового ADR по шаблону
|
|
||||||
`openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed.
|
|
||||||
Не помечай ADR принятым самостоятельно. Если запрос противоречит
|
|
||||||
действующему ADR, явно опиши конфликт и запроси решение пользователя до
|
|
||||||
выбора расходящегося подхода.
|
|
||||||
|
|
||||||
Хороший design объясняет причины технических решений.
|
|
||||||
requires:
|
requires:
|
||||||
- proposal
|
- proposal
|
||||||
|
|
||||||
@@ -287,57 +224,41 @@ artifacts:
|
|||||||
description: Контрольный список задач с отслеживаемым выполнением
|
description: Контрольный список задач с отслеживаемым выполнением
|
||||||
template: tasks.md
|
template: tasks.md
|
||||||
instruction: |
|
instruction: |
|
||||||
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные
|
Пиши группы и задачи по-русски; обязательные идентификаторы, пути файлов,
|
||||||
идентификаторы, пути файлов, названия API, коды и команды без перевода.
|
названия API, коды и команды не переводи.
|
||||||
|
|
||||||
Создай список задач, разбивающий работу по реализации на части.
|
Разбей реализацию на задачи по specs (что создать) и design (как реализовать).
|
||||||
|
|
||||||
Перед составлением задач проверь Open Questions в design.md. Если ответ на
|
Проверь Open Questions в design.md: влияющие на результат вопросы сначала
|
||||||
какой-либо вопрос повлияет на результат разработки, сначала обсуди его с
|
обсуди с пользователем; не закладывай неоговорённые предположения.
|
||||||
пользователем; не закладывай в список задач неоговорённые предположения.
|
|
||||||
|
|
||||||
**ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по
|
Следуй шаблону: apply отслеживает только чекбоксы. Только `x` внутри скобок
|
||||||
формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным
|
означает выполнение независимо от регистра и пробелов; любая другая отметка,
|
||||||
независимо от регистра и пробелов; например, `- [ x]` тоже означает
|
включая пустые скобки, считается незавершённой. Строки без чекбокса не отслеживаются.
|
||||||
выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`,
|
|
||||||
считается незавершённой. Строки без чекбокса вообще не отслеживаются.
|
|
||||||
|
|
||||||
Правила:
|
Правила:
|
||||||
- Группируй связанные задачи под нумерованными заголовками `##`.
|
- Группируй связанные задачи под нумерованными заголовками `##`.
|
||||||
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
|
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
|
||||||
- Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию.
|
- Каждая задача выполнима за одну сессию; порядок соответствует зависимостям.
|
||||||
- Располагай задачи в порядке зависимостей: сначала то, что нужно сделать
|
- В описание каждого чекбокса включай проверку: тест, команду, наблюдаемое
|
||||||
раньше.
|
поведение или готовый артефакт. Отдельная задача проверки допустима только
|
||||||
- Для каждой задачи укажи способ проверки выполнения: тест, команду,
|
для интеграционных/системных сценариев, охватывающих несколько задач реализации.
|
||||||
наблюдаемое поведение или готовый артефакт. Добавь проверку в описание
|
|
||||||
чекбокса. Выноси проверку в отдельную задачу только для интеграционных
|
|
||||||
или системных сценариев, охватывающих несколько задач реализации.
|
|
||||||
|
|
||||||
Пример:
|
Пример:
|
||||||
```
|
```
|
||||||
# Tasks
|
- [ ] 1.1 Реализовать экспорт данных и проверить прохождение теста экспорта
|
||||||
|
|
||||||
## 1. Подготовка
|
|
||||||
|
|
||||||
- [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов
|
|
||||||
- [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки
|
|
||||||
|
|
||||||
## 2. Основная реализация
|
|
||||||
|
|
||||||
- [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта
|
|
||||||
- [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это
|
Связывай задачи с Requirement ID, FR и кодами завершения, если они затронуты.
|
||||||
реализовать.
|
|
||||||
|
|
||||||
Связывай задачи с Requirement ID, FR и кодами завершения, если задача
|
Для нового или заменяющего ADR из design добавь отдельную задачу создания
|
||||||
затрагивает эти результаты.
|
в `openspec/context/adr/` со статусом Proposed. При замене принятого решения
|
||||||
|
свяжи новый и прежний ADR полями `supersedes` и `superseded-by`.
|
||||||
|
|
||||||
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
|
Если proposal/design предусматривает создание/обновление постоянных документов
|
||||||
отдельную задачу на его создание в `openspec/context/adr/` со статусом
|
контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md`
|
||||||
Proposed. При замене принятого решения свяжи новый и прежний ADR через
|
при изменении состава документов; отсутствующий индекс создавай только
|
||||||
поля `supersedes` и `superseded-by`.
|
при введении постоянных документов контекста или принятии проектом этой навигационной модели.
|
||||||
requires:
|
requires:
|
||||||
- specs
|
- specs
|
||||||
- design
|
- design
|
||||||
@@ -347,5 +268,8 @@ apply:
|
|||||||
tracks: tasks.md
|
tracks: tasks.md
|
||||||
instruction: |
|
instruction: |
|
||||||
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
|
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
|
||||||
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
|
выполненными по мере работы, включая задачи по обновлению проектного
|
||||||
потребуется уточнение.
|
контекста и его индекса. Если индекс существует или его создание входит в
|
||||||
|
tasks.md, проверь, что он соответствует фактическому набору документов.
|
||||||
|
Убедись, что требования Specs не продублированы в Context.
|
||||||
|
Остановись, если столкнёшься с препятствием или потребуется уточнение.
|
||||||
|
|||||||
@@ -27,3 +27,9 @@
|
|||||||
## Impact
|
## Impact
|
||||||
|
|
||||||
<!-- Затронутые код, API, зависимости и системы -->
|
<!-- Затронутые код, API, зависимости и системы -->
|
||||||
|
|
||||||
|
## Project Context
|
||||||
|
|
||||||
|
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
|
||||||
|
создать или обновить. Если обновления не нужны, напиши это явно.
|
||||||
|
Не переноси сюда функциональные требования из OpenSpec Specs. -->
|
||||||
|
|||||||
@@ -20,6 +20,12 @@
|
|||||||
|
|
||||||
Система SHALL <наблюдаемый результат завершённой функции>.
|
Система SHALL <наблюдаемый результат завершённой функции>.
|
||||||
|
|
||||||
|
<!-- Выбирай формат по сложности сценария, независимо от типа FR и части системы.
|
||||||
|
Полный Use case используй для крупных многошаговых сценариев; сокращённый —
|
||||||
|
для простых коротких требований. Такие требования — кандидаты на выделение
|
||||||
|
в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||||
|
Не используй полный формат для простых требований, а сокращённый — для объёмных. -->
|
||||||
|
|
||||||
#### Scenario: <название завершённого процесса>
|
#### Scenario: <название завершённого процесса>
|
||||||
|
|
||||||
##### Участники
|
##### Участники
|
||||||
@@ -69,7 +75,7 @@ HTTP endpoint располагай в завершающем разделе CONT
|
|||||||
<При необходимости — параметры сообщений, связанные требования и соответствие
|
<При необходимости — параметры сообщений, связанные требования и соответствие
|
||||||
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
|
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
|
||||||
|
|
||||||
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
|
<!-- HTTP endpoint описывай в отдельном Requirement; формат Use case выбирай по сложности.
|
||||||
Контракт размещай в конце Requirement, не разбивая request/response на FR:
|
Контракт размещай в конце Requirement, не разбивая request/response на FR:
|
||||||
|
|
||||||
#### CONTRACT
|
#### CONTRACT
|
||||||
@@ -87,9 +93,7 @@ HTTP status: <код и условие возврата>.
|
|||||||
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
|
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
|
<!-- Для сокращённого Use case замени полный Scenario следующим блоком:
|
||||||
типа FR и предмета описания. Для сокращенного Use case используй только основной
|
|
||||||
поток и ссылки на FR:
|
|
||||||
|
|
||||||
#### Scenario: Сокращенный use case: <предмет описания>
|
#### Scenario: Сокращенный use case: <предмет описания>
|
||||||
|
|
||||||
|
|||||||
@@ -417,8 +417,6 @@ def check_requirement(
|
|||||||
scenario, details = block.split("#### Функциональные требования", 1)
|
scenario, details = block.split("#### Функциональные требования", 1)
|
||||||
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
|
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
|
||||||
if has_contract:
|
if has_contract:
|
||||||
if is_short_use_case:
|
|
||||||
errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case")
|
|
||||||
details, contract_content = details.split("#### CONTRACT", 1)
|
details, contract_content = details.split("#### CONTRACT", 1)
|
||||||
errors.extend(check_http_endpoint_contract(contract_content))
|
errors.extend(check_http_endpoint_contract(contract_content))
|
||||||
sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE)
|
sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE)
|
||||||
|
|||||||
@@ -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 задачи, результат и оставшееся действие.
|
||||||
@@ -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()
|
||||||
@@ -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()
|
||||||
Reference in New Issue
Block a user