Оптимизация описания

This commit is contained in:
2026-10-13 23:16:46 +03:00
parent ce62ddc704
commit f3cedcc5c3
7 changed files with 319 additions and 315 deletions
+46 -29
View File
@@ -5,6 +5,37 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
## Настройка YouTrack
Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке
`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь
строки в существующий блок, сохранив остальной проектный контекст:
```yaml
context: |
YouTrack project key: <KEY>
YouTrack application label: <APP-NAME>
```
Схема создаёт одну задачу `Task` на change, добавляет к ней тег с указанным
именем приложения и учитывает фактическое время от Explore до архивации. В
YouTrack этот механизм называется тегом; настройка `application label` задаёт
точное имя этого тега. Если интеграция или тег недоступны, workflow останавливается
и сообщает о проблеме, а не создаёт задачу без метки приложения.
Завершающие действия YouTrack для команды `openspec archive` настраиваются отдельно
от схемы — в `operations.archive.guidance` файла `openspec/config.yaml`:
```yaml
operations:
archive:
guidance:
- >-
Перед openspec archive внеси в связанную задачу YouTrack оставшееся
фактическое время, учитывая только ещё не записанное. После успешной
архивации переведи задачу в конечный статус проекта по доступным полям;
не угадывай статус. Change завершён после архивации и закрытия задачи.
```
## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
@@ -147,39 +178,25 @@ Scenario в таких операциях не создаётся. В delta со
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
## Учёт change в YouTrack
Каждый новый change, включая change с `skip_specs: true`, получает ровно одну
задачу типа Task в YouTrack-проекте соответствующего репозитория. Сначала
подготовь содержательный proposal с причиной, scope, capabilities и impact;
затем, до перехода к specs, design и tasks, создай задачу через подключённый
YouTrack MCP. Ключ проекта укажи в `context` файла `openspec/config.yaml`; добавь
строку `YouTrack project key: <KEY>`. Если строки нет или ключ нельзя однозначно
проверить через MCP, уточни его у пользователя; проект `Default` не является
автоматическим запасным вариантом. Перед созданием прочитай схему обязательных
полей проекта и используй только допустимые значения. Не добавляй произвольное
верхнеуровневое поле `youtrack_project`: оно не входит в контракт OpenSpec.
В задаче укажи slug change и краткую цель, а её ключ и URL сохрани в разделе
`## YouTrack` файла `proposal.md`. При создании задачи также внеси work item с
фактически затраченным временем на подготовку контекста change и proposal.
При каждом последующем редактировании proposal пересмотри заголовок и описание
задачи. Если изменились причина, scope, capabilities или impact, обнови связанную
задачу через MCP в соответствии с актуальным proposal; не создавай дубликат.
Если MCP недоступен, явно сообщи об этом и уточни дальнейшее действие.
На всех этапах change — от подготовки proposal до реализации — записывай
фактически затраченное время в YouTrack как work items, используя поддерживаемый
проектом тип работы и не дублируя уже внесённые записи. При архивировании учти
всё оставшееся время, затем выполни `openspec archive`; после успешной архивации
переведи связанную задачу в конечный статус, предусмотренный YouTrack-проектом.
Определи поле и значение статуса по схеме проекта, не угадывай их. Change
завершён только после успешного архивирования и закрытия задачи.
Если смысловые коды или сообщения ещё не выдаются приложением, это явно
фиксируется в 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 проекта в `openspec/context/adr/` и называй файлы