16 KiB
Общие инструменты для OpenSpec и Codex
Репозиторий содержит три переиспользуемых артефакта:
| Артефакт | Назначение | Где находится |
|---|---|---|
Схема OpenSpec use-case-driven |
Русскоязычные спецификации поведения и workflow proposal → specs / design → tasks → apply |
openspec/schemas/use-case-driven/ |
Заготовки AGENTS.md и config.yaml с контекстом проекта |
Правила агента, параметры проекта и начальная навигация по постоянным документам | examples/project-bootstrap/ |
Скилл Codex task-tracker |
Одна задача на change: привязка, метка приложения, синхронизация, учёт времени, archive и коммит | 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 схемы.
На macOS/Linux пользовательские схемы находятся в
${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas, на Windows —
в %LOCALAPPDATA%\openspec\schemas, либо под XDG_DATA_HOME, если он задан.
2. Заготовки проектных инструкций и конфигурации
После openspec init перенесите в прикладной проект нужные части
examples/project-bootstrap/:
AGENTS.md— навигация по контексту, правила OpenSpec и вызовыtask-trackerв жизненном цикле change;openspec/config.yaml— выбор схемы и начальный контекст OpenSpec;openspec/context/— индекс контекста, правила ADR и шаблон решения.
Объедините заготовки с существующими файлами, сохраняя применимые инструкции
и настройки проекта. Заполните в проектном AGENTS.md:
## 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
описывает настройки самого репозитория; переносимая заготовка находится
в 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.
Для смены трекера меняйте только скилл. Перенос существующих
задач требует явного соответствия ID, чтобы не потерять историю связи.
Связь, сохраняющаяся после archive
Источник связи — task-tracker.yaml внутри каталога change:
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.
Запись содержит незавершённую операцию и журнал уже учтённого времени. После ошибки MCP скилл проверяет внешнее состояние перед повтором. При неизвестном результате создания или записи времени автоматический повтор запрещён до сверки. Если задача не закрылась после archive, связь и pending остаются в архиве для следующей сессии.
Это агентный workflow: самостоятельный запуск openspec archive вне Codex
переносит файл, но не вызывает скилл, не синхронизирует задачу и не создаёт
коммит. Для последующей
синхронизации попросите Codex использовать $task-tracker для архивного change.
При одновременной работе нескольких агентов требуется согласовать операции:
файл связи не является распределённой блокировкой.
Подключение из домашней директории
macOS и Linux
Замените /path/to/openspec-schema на абсолютный путь к своему клону:
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.
См. официальную документацию о скиллах.
Windows PowerShell
Junction позволяет использовать исходные каталоги без копирования:
$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')
Команды предполагают, что пути назначения ещё свободны. Если схема уже подключена, создайте только ссылку на скилл. Перед заменой существующей папки/ссылки проверьте её содержимое и источник.
Проверьте схему из каталога прикладного проекта:
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 без однозначной связи новую задачу
автоматически не создаёт.
Проверки и ограничения
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]. Применимые требования безопасности,
аудита и ролевой модели нужно явно учитывать при анализе изменения.