Files
openspec-schema/README.md
T

237 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Общие инструменты для OpenSpec и Codex
Репозиторий содержит три переиспользуемых артефакта:
| Артефакт | Назначение | Где находится |
|---|---|---|
| Схема 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) |
Схема и скилл хранятся и развиваются здесь. Подключайте их символическими
ссылками из пользовательских каталогов; обновление клона обновляет общий
источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте:
они содержат настройки конкретного приложения.
## 1. Схема `use-case-driven`
В отличие от базовой `spec-driven`, схема описывает поведение полными или
сокращёнными use cases без Gherkin. Один `Requirement` задаёт завершённую
функцию с одним `Scenario`; локальные `FR` фиксируют подробные правила,
устойчивые контракты и ограничения. HTTP-контракт находится в `CONTRACT`.
Master specs описывают `Purpose`, границы capability и требования; delta specs
используют стандартные операции OpenSpec. Технический синтаксис сохраняется,
пояснения пишутся по-русски. Подробности — в [README схемы](openspec/schemas/use-case-driven/README.md).
На 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]`. Применимые требования безопасности,
аудита и ролевой модели нужно явно учитывать при анализе изменения.