Template
231 lines
16 KiB
Markdown
231 lines
16 KiB
Markdown
# Общие инструменты для 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` с контекстом проекта | Правила агента, параметры проекта и начальная навигация по постоянным документам | [`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 и вызовы `task-tracker` в жизненном цикле change;
|
||
- [`openspec/config.yaml`](examples/project-bootstrap/openspec/config.yaml) —
|
||
выбор схемы и начальный контекст OpenSpec;
|
||
- `openspec/context/` — индекс контекста, правила ADR и шаблон решения.
|
||
|
||
Объедините заготовки с существующими файлами, сохраняя применимые инструкции
|
||
и настройки проекта. Заполните в проектном `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 с русским описанием в 4–7 слов.
|
||
При ошибке 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-коммитом с русским сообщением из 4–7 слов. Исходный `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]`. Применимые требования безопасности,
|
||
аудита и ролевой модели нужно явно учитывать при анализе изменения.
|