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

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
+10
View File
@@ -83,6 +83,16 @@ openspec schema validate use-case-driven
создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная
проектная ссылка либо адаптация инструкций к расположению активной схемы. проектная ссылка либо адаптация инструкций к расположению активной схемы.
### Заготовки контекста проекта
Ссылка на пользовательскую схему также не устанавливает `AGENTS.md` или
`openspec/context/` в проект-потребитель. Для начальной настройки можно вручную
скопировать и адаптировать файлы из
[`examples/project-bootstrap/`](examples/project-bootstrap/). Комплект включает
инструкции агента, индекс контекста, правила ADR и копию ADR-шаблона. Содержимое
индекса и любые дополнительные документы контекста должны соответствовать
конкретному проекту. В комплекте нет принятых ADR и описаний бизнес-домена.
## Статус ## Статус
@@ -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`; не принимай
решение самостоятельно.
+14 -8
View File
@@ -1,14 +1,10 @@
schema: use-case-driven schema: use-case-driven
# При настройке проекта YouTrack добавьте в context строку: # Проектные настройки YouTrack. Общие правила работы заданы в schema.yaml.
# YouTrack project key: <KEY> # В проектах, скопировавших эту схему, замените значения на свои.
context: | context: |
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и YouTrack project key: PL
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если YouTrack application label: openspec-schema
запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о
конфликте пользователю; не обходи решение молча. Новые ADR оформляй по
шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом
Proposed; не помечай решение Accepted без явного принятия владельцем решения.
rules: rules:
tasks: tasks:
@@ -21,3 +17,13 @@ rules:
публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений,
рефакторинга и документации, MINOR для обратно совместимых возможностей, рефакторинга и документации, MINOR для обратно совместимых возможностей,
MAJOR для несовместимых изменений публичного контракта. MAJOR для несовместимых изменений публичного контракта.
operations:
archive:
guidance:
- >-
Перед `openspec archive` внеси в связанную задачу YouTrack оставшееся
фактическое время, учитывая только ещё не записанное и используя
доступный проекту тип работы. После успешной архивации переведи задачу
в конечный статус проекта по доступным полям и значениям; не угадывай
статус. Change завершён только после архивации и закрытия задачи.
+46 -29
View File
@@ -5,6 +5,37 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему. с явно указанной `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 — отдельная бизнес-функция или понятный результат в иерархии доменов. - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
@@ -147,39 +178,25 @@ Scenario в таких операциях не создаётся. В delta со
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`. ссылок на неизменённые требования при проверке передай `--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. фиксируется в 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/` и называй файлы
+183 -277
View File
@@ -10,93 +10,77 @@ 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, зависимости и системы.
- **YouTrack**: После создания задачи укажи её ключ и URL.
ВАЖНО: раздел 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
потребуется соответствующий файл спецификации.
После подготовки содержательного первого варианта proposal создай для Change должен содержать новую/изменяемую capability либо `skip_specs: true`
каждого нового change, в том числе с `skip_specs: true`, ровно одну задачу в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta.
типа Task в YouTrack-проекте этого репозитория через подключённый YouTrack `skip_specs: true` допустим только без изменения описанного поведения
MCP. Создай задачу до перехода к specs, design и tasks, используя причину, (чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки.
scope и impact из proposal. Бери ключ проекта из `context` файла
`openspec/config.yaml`; в нём должна быть строка `YouTrack project key: <KEY>`.
Если строка отсутствует или ключ нельзя однозначно проверить через MCP,
уточни его у пользователя. Проект `Default` не используй как запасной
вариант. Перед созданием проверь схему обязательных полей проекта; не выдумывай значения.
Укажи slug change и краткую цель в задаче, затем
заполни в proposal раздел YouTrack ключом и URL задачи. Добавь work item с
фактически затраченным до этого временем на подготовку контекста change и
proposal.
При каждом последующем редактировании proposal пересмотри формулировки Для Project Context прочитай существующий `openspec/context/index.md` и
заголовка и описания связанной YouTrack-задачи. Если причина, scope, относящиеся к change документы из него. Не копируй функциональные требования
capabilities или impact изменились, обнови задачу через MCP так, чтобы они Specs в Context. Отсутствующий индекс включай в scope только при введении
соответствовали актуальному proposal; не создавай новую задачу. Если MCP постоянных документов контекста или принятии проектом этой навигационной модели.
недоступен, сообщи об этом и уточни, как продолжить.
В каждом изменении (`change`) должна быть указана хотя бы одна новая или YouTrack:
изменяемая capability либо явный отказ от спецификаций: `openspec validate` В `context` файла `openspec/config.yaml` обязательны строки
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не `YouTrack project key: <KEY>` и `YouTrack application label: <APP-NAME>`.
задано `skip_specs: true`. До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные
Используй `skip_specs: true` только когда поведение, описываемое поля и доступность/применимость тега `<APP-NAME>`. При отсутствии настройки,
спецификациями, не меняется (например, при чистом рефакторинге, изменении тега, невозможности проверки или недоступности MCP остановись, сообщи о проблеме
инструментов или документации). Не добавляй требование только ради и уточни конфигурацию либо дальнейшее действие. Не используй проект `Default`.
прохождения проверки.
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на После содержательного proposal, до specs/design/tasks, создай ровно одну
способе реализации: детали реализации относятся к design.md. задачу `Task` на change, включая `skip_specs: true`. Заголовок и описание
сформируй по причине и scope proposal, добавь slug change и тег с точным
именем из `YouTrack application label`; ключ и URL внеси в YouTrack раздел
`proposal.md`. При изменении причины, scope, capabilities или impact в proposal
обновляй связанную задачу без дубликатов. Тег приложения сохраняй до изменения настройки.
Этот документ задаёт основу: на нём строятся specs, design и tasks. Учитывай фактическое время всей работы от Explore и подготовки proposal:
при создании задачи внеси уже затраченное; после каждого сеанса Apply добавляй
только неучтённое время отдельным work item с доступным проекту типом работы.
Финальную синхронизацию времени и статуса выполняй по `openspec instructions archive`.
requires: [] requires: []
- id: specs - id: specs
@@ -104,141 +88,107 @@ 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 и другие), кроме обязательного полного HTTP-сценария.
и описываемой части системы: процесса выполнения, БД, API, UI и других. - Полный сценарий содержит разделы Участники, Предусловия,
- Полный сценарий использования содержит разделы Участники, Предусловия,
Основной поток, Альтернативы и ошибки, Результат, Коды завершения — Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
в таком порядке. в таком порядке.
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`; - Сокращённый сценарий содержит только `##### Основной поток`, без других
каждый шаг кратко описывает аспект и ссылается на 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
@@ -247,59 +197,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
@@ -308,63 +237,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`.
YouTrack-задача из proposal сопровождает весь change и не заменяет Если proposal/design предусматривает создание/обновление постоянных документов
чекбоксы реализации в tasks.md. На всех этапах change — от подготовки контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md`
proposal до реализации — записывай в YouTrack фактически затраченное время при изменении состава документов; отсутствующий индекс создавай только
отдельными work items через MCP, без дублирования уже внесённого времени. при введении постоянных документов контекста или принятии проектом этой навигационной модели.
Выбирай только тип работы, поддерживаемый проектом.
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
отдельную задачу на его создание в `openspec/context/adr/` со статусом
Proposed. При замене принятого решения свяжи новый и прежний ADR через
поля `supersedes` и `superseded-by`.
requires: requires:
- specs - specs
- design - design
@@ -374,12 +281,11 @@ apply:
tracks: tasks.md tracks: tasks.md
instruction: | instruction: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или выполненными по мере работы, включая задачи по обновлению проектного
потребуется уточнение. Для change с задачей YouTrack записывай фактически контекста и его индекса. Если индекс существует или его создание входит в
затраченное во время apply время в её work items через MCP; перед tasks.md, проверь, что он соответствует фактическому набору документов.
архивированием проверь, что учтено всё время работы над change. После Убедись, что требования Specs не продублированы в Context.
успешного `openspec archive` Для связанной задачи YouTrack после каждого рабочего сеанса запиши только
переведи задачу в конечный статус, предусмотренный проектом YouTrack, ещё не учтённое фактическое время через MCP, используя доступный тип работы.
используя доступную схему полей и значений. Не подставляй предполагаемое Перед архивацией change проверь, что учтено всё время начиная с Explore.
название статуса. Считай change завершённым только после успешного Остановись, если столкнёшься с препятствием или потребуется уточнение.
архивирования и закрытия YouTrack-задачи.
@@ -28,7 +28,12 @@
<!-- Затронутые код, API, зависимости и системы --> <!-- Затронутые код, API, зависимости и системы -->
## Project Context
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
создать или обновить. Если обновления не нужны, напиши это явно.
Не переноси сюда функциональные требования из OpenSpec Specs. -->
## YouTrack ## YouTrack
<!-- Заполни после подготовки proposal и создания задачи. -->
- Задача: `<PROJECT-123>` — <issue URL> - Задача: `<PROJECT-123>` — <issue URL>