diff --git a/README.md b/README.md index 6d42772..548a806 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,16 @@ openspec schema validate use-case-driven создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная проектная ссылка либо адаптация инструкций к расположению активной схемы. +### Заготовки контекста проекта + +Ссылка на пользовательскую схему также не устанавливает `AGENTS.md` или +`openspec/context/` в проект-потребитель. Для начальной настройки можно вручную +скопировать и адаптировать файлы из +[`examples/project-bootstrap/`](examples/project-bootstrap/). Комплект включает +инструкции агента, индекс контекста, правила ADR и копию ADR-шаблона. Содержимое +индекса и любые дополнительные документы контекста должны соответствовать +конкретному проекту. В комплекте нет принятых ADR и описаний бизнес-домена. + ## Статус diff --git a/examples/project-bootstrap/openspec/context/adr/ADR-template.md b/examples/project-bootstrap/openspec/context/adr/ADR-template.md new file mode 100644 index 0000000..abeb532 --- /dev/null +++ b/examples/project-bootstrap/openspec/context/adr/ADR-template.md @@ -0,0 +1,36 @@ +--- +status: Proposed +date: YYYY-MM-DD +decision-makers: + - <имя или роль владельца решения> +supersedes: [] +superseded-by: +--- + +# ADR-<номер>: <Краткое название решения> + +## Контекст и проблема + +Какую проблему нужно решить и какие ограничения важны для выбора? + +## Факторы решения + +- <Требование или ограничение, влияющее на решение> + +## Рассмотренные варианты + +- **<Вариант>** — преимущества и недостатки. + +## Решение + +Какой вариант выбран и почему? Заполняется при принятии ADR; до этого раздел +может содержать предлагаемое решение. + +## Последствия + +- Положительные: <результаты и преимущества>. +- Отрицательные или компромиссы: <цена решения, ограничения, риски>. + +## Связанные решения + +- diff --git a/examples/project-bootstrap/openspec/context/adr/README.md b/examples/project-bootstrap/openspec/context/adr/README.md new file mode 100644 index 0000000..69cccbe --- /dev/null +++ b/examples/project-bootstrap/openspec/context/adr/README.md @@ -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`; не принимай +решение самостоятельно. diff --git a/openspec/config.yaml b/openspec/config.yaml index 63f2890..e4e0cd4 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,14 +1,10 @@ schema: use-case-driven -# При настройке проекта YouTrack добавьте в context строку: -# YouTrack project key: +# Проектные настройки YouTrack. Общие правила работы заданы в schema.yaml. +# В проектах, скопировавших эту схему, замените значения на свои. context: | - ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и - реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если - запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о - конфликте пользователю; не обходи решение молча. Новые ADR оформляй по - шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом - Proposed; не помечай решение Accepted без явного принятия владельцем решения. + YouTrack project key: PL + YouTrack application label: openspec-schema rules: tasks: @@ -21,3 +17,13 @@ rules: публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей, MAJOR для несовместимых изменений публичного контракта. + +operations: + archive: + guidance: + - >- + Перед `openspec archive` внеси в связанную задачу YouTrack оставшееся + фактическое время, учитывая только ещё не записанное и используя + доступный проекту тип работы. После успешной архивации переведи задачу + в конечный статус проекта по доступным полям и значениям; не угадывай + статус. Change завершён только после архивации и закрытия задачи. diff --git a/openspec/schemas/use-case-driven/README.md b/openspec/schemas/use-case-driven/README.md index 1c734ba..58e046a 100644 --- a/openspec/schemas/use-case-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -5,6 +5,37 @@ формат требований определён в `schema.yaml` и шаблонах. Существующие changes с явно указанной `schema: spec-driven` продолжают использовать свою схему. +## Настройка YouTrack + +Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке +`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь +строки в существующий блок, сохранив остальной проектный контекст: + +```yaml +context: | + YouTrack project key: + YouTrack application label: +``` + +Схема создаёт одну задачу `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 `. -## Учёт 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: `. Если строки нет или ключ нельзя однозначно -проверить через 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/` и называй файлы diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml index 3a3092d..f25f75a 100644 --- a/openspec/schemas/use-case-driven/schema.yaml +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -10,93 +10,77 @@ artifacts: description: Начальный документ предложения, описывающий изменение template: proposal.md instruction: | - Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки - OpenSpec и технические идентификаторы, названия API, файлов, - инструментов, команд и коды без перевода. + Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические + идентификаторы, названия API, файлов, инструментов, команды и коды не переводи. - Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение. + Объясни, ПОЧЕМУ требуется изменение. Объём — 1–2 страницы; детали + реализации относятся к design.md. Разделы: - - **Why**: 1–2 предложения о проблеме или возможности. Какую проблему - решает изменение? Почему его нужно сделать сейчас? - - **What Changes**: Список изменений. Точно опиши новые возможности, - изменения и удаления. Помечай несовместимые изменения как **BREAKING**. - - **Capabilities**: Укажи, какие спецификации будут созданы или изменены: - Capability представляет отдельную бизнес-функцию или понятный результат; - сохраняй полный иерархический путь, например `domain/capability-name`. - Для новой capability сформируй короткий читаемый префикс Requirement: - для однословного сегмента используй первые три буквы, для сегмента с - дефисами — первые буквы его частей. Приводи сокращения к верхнему - регистру, разделяй сегменты кода точкой и сохраняй их порядок: - `domain/capability-name` → `DOM.CN`. - Перед назначением проверь уникальность префикса по Requirement ID в - основных спецификациях проекта. Если префикс занят, удлиняй сокращения - новых сегментов до уникальности; уже используемые префиксы не меняй. - Сохраняй префикс при переименовании capability. - - **New Capabilities**: Перечисли добавляемые capabilities. Для каждой - создай `specs//spec.md`. Используй `kebab-case` для - новых сегментов пути (например, `user-auth` или `identity/user-auth`) - и следуй принятой в проекте структуре спецификаций. - - **Modified Capabilities**: Перечисли существующие capabilities, чьи - REQUIREMENTS меняются. Добавляй сюда capability только при изменении - поведения, описанного в спецификации, а не только деталей реализации. - Для каждой создай delta spec по точному существующему пути внутри - `openspec/specs/`. Оставь список пустым, если требования не меняются. - - **Impact**: Затронутые участки кода, API, зависимости и системы. - - **YouTrack**: После создания задачи укажи её ключ и URL. + - **Why**: 1–2 предложения о проблеме или возможности и причинах изменения сейчас. + - **What Changes**: Точный список новых возможностей, изменений и удалений; + несовместимые изменения помечай **BREAKING**. + - **Capabilities**: Создаваемые или изменяемые спецификации отдельных + бизнес-функций или понятных результатов. Сохраняй полный иерархический + путь, например `domain/capability-name`. + Короткий читаемый префикс Requirement для новой capability: первые три буквы однословного + сегмента или первые буквы частей сегмента с дефисами; верхний регистр, + точки и порядок сегментов (`domain/capability-name` → `DOM.CN`). + Проверь уникальность префикса по Requirement ID основных спецификаций; + при совпадении удлиняй сокращения новых сегментов до уникальности. Существующие префиксы + не меняй, включая переименование capability. + - **New Capabilities**: Перечисли новые capabilities; для каждой создай + `specs//spec.md`; новые сегменты пиши в `kebab-case`, + следуя структуре проекта. + - **Modified Capabilities**: Укажи существующие capabilities только при + изменении описанного поведения, а не деталей реализации. Создай delta + spec по точному существующему пути внутри `openspec/specs/`; если + требования не меняются, оставь список пустым. + - **Impact**: Затронутые код, API, зависимости и системы. + - **Project Context**: Создаваемые или обновляемые постоянные документы, + включая решение о необходимости ADR. Отсутствие изменений укажи явно. - ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs. - Перед его заполнением изучи существующие спецификации: выполни - `openspec list --specs`, чтобы получить список capabilities проекта. - Для подходящих вариантов выполни `openspec show "" --type spec --json --no-scenarios`. - Команда вернёт назначение capability и тексты требований, не загружая - целые файлы спецификаций. Добавляй `--store ""` к обеим командам - только для зарегистрированного отдельного хранилища и сохраняй - `--type spec`: если артефакт `change` и спецификация имеют одинаковое имя, - без этого параметра возникнет неоднозначность при выборе. Команда - `openspec list` без `--specs` показывает активные изменения (`changes`), - а не спецификации, поэтому не отражает уже описанное в проекте поведение. - Используй точный путь - существующей capability, не создавай похожее имя. - Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже - описано и что нужно изменить, прочитай каждую подходящую спецификацию - целиком, включая сценарии, командой `openspec show "" --type spec` - (с тем же правилом для `--store`). Для каждой перечисленной capability - потребуется соответствующий файл спецификации. + Перед заполнением Capabilities изучи существующие specs: + 1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes. + 2. Для подходящих вариантов — `openspec show "" --type spec --json --no-scenarios`: + обзор назначения и требований без загрузки целых спецификаций. + 3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком, + включая сценарии: `openspec show "" --type spec`. + Добавляй `--store ""` к этим командам только для зарегистрированного + отдельного хранилища. Сохраняй `--type spec`, чтобы избежать неоднозначности + при одинаковых именах change и spec. Используй точный путь существующей + capability, не создавай похожее имя. Каждой перечисленной capability + соответствует файл спецификации. - После подготовки содержательного первого варианта proposal создай для - каждого нового change, в том числе с `skip_specs: true`, ровно одну задачу - типа Task в YouTrack-проекте этого репозитория через подключённый YouTrack - MCP. Создай задачу до перехода к specs, design и tasks, используя причину, - scope и impact из proposal. Бери ключ проекта из `context` файла - `openspec/config.yaml`; в нём должна быть строка `YouTrack project key: `. - Если строка отсутствует или ключ нельзя однозначно проверить через MCP, - уточни его у пользователя. Проект `Default` не используй как запасной - вариант. Перед созданием проверь схему обязательных полей проекта; не выдумывай значения. - Укажи slug change и краткую цель в задаче, затем - заполни в proposal раздел YouTrack ключом и URL задачи. Добавь work item с - фактически затраченным до этого временем на подготовку контекста change и - proposal. + Change должен содержать новую/изменяемую capability либо `skip_specs: true` + в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta. + `skip_specs: true` допустим только без изменения описанного поведения + (чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки. - При каждом последующем редактировании proposal пересмотри формулировки - заголовка и описания связанной YouTrack-задачи. Если причина, scope, - capabilities или impact изменились, обнови задачу через MCP так, чтобы они - соответствовали актуальному proposal; не создавай новую задачу. Если MCP - недоступен, сообщи об этом и уточни, как продолжить. + Для Project Context прочитай существующий `openspec/context/index.md` и + относящиеся к change документы из него. Не копируй функциональные требования + Specs в Context. Отсутствующий индекс включай в scope только при введении + постоянных документов контекста или принятии проектом этой навигационной модели. - В каждом изменении (`change`) должна быть указана хотя бы одна новая или - изменяемая capability либо явный отказ от спецификаций: `openspec validate` - отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не - задано `skip_specs: true`. - Используй `skip_specs: true` только когда поведение, описываемое - спецификациями, не меняется (например, при чистом рефакторинге, изменении - инструментов или документации). Не добавляй требование только ради - прохождения проверки. + YouTrack: + В `context` файла `openspec/config.yaml` обязательны строки + `YouTrack project key: ` и `YouTrack application label: `. + До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные + поля и доступность/применимость тега ``. При отсутствии настройки, + тега, невозможности проверки или недоступности MCP остановись, сообщи о проблеме + и уточни конфигурацию либо дальнейшее действие. Не используй проект `Default`. - Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на - способе реализации: детали реализации относятся к design.md. + После содержательного proposal, до specs/design/tasks, создай ровно одну + задачу `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: [] - id: specs @@ -104,141 +88,107 @@ artifacts: description: Подробные спецификации изменения template: spec.md instruction: | - Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные - заголовки OpenSpec, идентификаторы, названия API и коды без перевода. + Пиши пояснения по-русски; обязательные заголовки OpenSpec, идентификаторы, + названия API и коды не переводи. - Создай спецификации наблюдаемого поведения и устойчивых контрактов. - Правила ниже применяются к основным спецификациям и к полным блокам - ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin. + Описывай наблюдаемое поведение и устойчивые контракты в формате без Gherkin. + Правила применяются к основным specs и полным блокам ADDED/MODIFIED в delta. Иерархия и границы: - - Capability описывает отдельную бизнес-функцию или понятный результат. - - Сохраняй полный иерархический путь, например domain/capability-name. + - Capability — отдельная бизнес-функция или понятный результат; сохраняй + полный иерархический путь, например domain/capability-name. - Основная спецификация содержит раздел ## Границы между Purpose и - Requirements. Кратко укажи, за что отвечает capability, что входит в её - область и что находится за её пределами или относится к другой capability - либо приложению. Не дублируй Requirements и FR. - - Один Requirement описывает одну завершённую техническую функцию. - - Не дроби один процесс на Requirements для чтения, валидации и записи. - - Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario. - - Префикс Requirement состоит из сокращений сегментов пути capability, - разделённых точками; его уникальность проверяется по ID в основных - спецификациях. Номер Requirement уникален внутри capability. Существующие + Requirements: кратко укажи ответственность, область, исключения и владельцев + соседних обязанностей — другие capabilities или приложения. Не дублируй + Requirements и FR; сведения об ответственности допустимы без задания поведения. + - Requirement — одна завершённая техническая функция, стабильный ID вида + AREA.CAP-01 и ровно один Scenario. Не дроби процесс на чтение, валидацию и запись. + - Префикс — сокращения сегментов пути capability через точки; проверяй + уникальность по ID основных specs. Номер уникален внутри capability; унаследованные Requirements могут сохранять прежние ID. - Заголовки OpenSpec: ### Requirement: и #### Scenario:. - Описание Requirement содержит SHALL/MUST и наблюдаемый результат. - - В Requirements и FR включай только сведения, меняющие наблюдаемое - поведение, устойчивый контракт или обязательное техническое ограничение. - Удаляй повторы, пояснения и формулировки, которые не меняют поведение и - не снимают неоднозначность контракта. В ## Границы оставляй краткие - сведения об ответственности и владении, необходимые для понимания - области capability, даже если они сами по себе не задают поведение. + - В Requirements и FR оставляй только наблюдаемое поведение, устойчивые + контракты и обязательные технические ограничения. Удаляй повторы и + пояснения, не влияющие на поведение и не снимающие неоднозначность контракта. Scenario: - - Поддерживаются два формата сценария использования: полный и - сокращённый. Автор выбирает формат по ситуации, независимо от типа FR - и описываемой части системы: процесса выполнения, БД, API, UI и других. - - Полный сценарий использования содержит разделы Участники, Предусловия, + - Автор выбирает полный или сокращённый сценарий независимо от типа FR + и части системы (процесс, БД, API, UI и другие), кроме обязательного полного HTTP-сценария. + - Полный сценарий содержит разделы Участники, Предусловия, Основной поток, Альтернативы и ошибки, Результат, Коды завершения — в таком порядке. - - Сокращённый сценарий использования содержит только раздел `##### Основной поток`; - каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит - участников, предусловий, альтернатив и ошибок, результата или кодов - завершения и не задаёт отдельные ветвления во время выполнения. - - В обычном сценарии Назначение опционально; добавляй только если оно - сообщает сведения, которых нет в заголовке. Контекст отсутствует. + - Сокращённый сценарий содержит только `##### Основной поток`, без других + разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на FR. + - В обычном сценарии Назначение опционально: добавляй только сведения, + которых нет в заголовке. Контекст отсутствует. - Основной поток — нумерованные короткие шаги «Что делаем — как делаем». - - Шаг сценария выполнения может назвать действие, конечную точку API или - способ записи и сослаться на FR. - - Каждую конечную точку HTTP описывай в отдельном Requirement с полным - сценарием использования. - Сложные правила шага выноси в FR и связывай со сценарием ссылками. + - В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR. + - Каждую конечную точку HTTP описывай отдельным Requirement с полным сценарием. + Сложные правила шагов выноси в FR со ссылками из сценария. - Основной поток и альтернативы обычного сценария включают коды завершения, если они определены для этой функции. - Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты сообщений и дальнейшая логика располагаются за пределами Scenario. - Единственная таблица Scenario — Коды завершения с колонками Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE. - - Код сам сообщает смысл итога; дополнительный этап или свободный текст - не должен требоваться для понимания кода. События промежуточных шагов - не являются кодами завершения. Не создавай код для каждой диагностики. - - Каждая запись кода ссылается на локальные FR, определяющие дальнейшую - логику, текст или применимые правила результата. + - Код сам сообщает смысл итога без дополнительного этапа или свободного текста. + Промежуточные события не являются кодами завершения; не создавай код для каждой диагностики. + - Каждый код ссылается на локальные FR с дальнейшей логикой, текстом или правилами результата. - Каждый шаг, альтернатива и абзац сценария — не более 240 знаков содержательного текста без адресов Markdown-ссылок. - Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT. Функциональные требования: - - После Scenario, на уровне ####, идёт раздел Функциональные требования. - - Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее. - - ID FR содержит ID Requirement и локальный номер: .FR-NN. - Номер начинается с FR-01 в каждом Requirement. - - FR содержит отдельное понятное правило или связанный контракт; не дроби - связную логику на множество атомарных FR. - - Обычный FR без метки описывает логику, правила или последовательность - шагов. Типизированный FR помечай сразу после ID меткой [DB], [API] - или [UI]; метка не входит в ID и не меняет slug ссылки. - - [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает - контракт сообщения или технического лога. Контракт конечной точки HTTP - размещается в отдельном разделе CONTRACT. [UI] описывает требования к - UI; детальный паттерн будет добавлен отдельно. - - Для FR [DB] с таблицей БД следуй паттерну + - После Scenario идёт `#### Функциональные требования` с заголовками + `##### .FR-NN [метка]: <название>`; метка опциональна. + Локальная нумерация начинается с FR-01 в каждом Requirement. + - FR — отдельное понятное правило или связанный контракт; + не дроби связную логику на множество атомарных FR. + - FR без метки — логика, правила или последовательность шагов. + Метки [DB], [API], [UI] ставь сразу после ID; они не входят в ID и не меняют slug. + - [DB] — структура БД; для таблицы следуй `openspec/schemas/use-case-driven/patterns/database-table.md`. - - Для сериализуемого контракта сообщения в FR [API] следуй паттерну - `openspec/schemas/use-case-driven/patterns/message-contract.md`. - - Контракт конечной точки HTTP не оформляй отдельными FR. После раздела - Функциональные требования добавляй завершающий раздел CONTRACT с - подразделами Request и Response в таком порядке. В Request указывай - один HTTP-метод и путь; для отсутствующего тела явно отмечай это. - Таблицы тела запроса и ответа оформляй по паттерну message-contract.md. - - В таблице Response раздела CONTRACT укажи для каждого поля источник - значения или правило его формирования в последней колонке. - - В таблице ответа контракта FR [API] укажи для каждого поля источник - значения или правило его формирования в колонке «Формирование значения». - - Не добавляй HTML-якоря вида . Markdown генерирует - якоря из заголовков Requirement и FR. - - Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его - заголовка, например - [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID - используется и для ссылки внутри Requirement, и для ссылки на другой - Requirement. + - [API] — контракт сообщения или технического лога; сериализуемое сообщение + оформляй по `openspec/schemas/use-case-driven/patterns/message-contract.md`. + - [UI] — требования к UI; детальный паттерн будет добавлен отдельно. + - HTTP-контракт размещай после Функциональных требований в завершающем + CONTRACT, не в отдельных FR. Подразделы — Request, затем Response. + В Request указывай один HTTP-метод и путь, явно отмечай отсутствие тела. + Таблицы тела запроса и ответа оформляй по message-contract.md. + - В response-таблицах для каждого поля укажи источник или правило формирования: + в последней колонке CONTRACT и в «Формирование значения» для FR [API]. + - Не добавляй HTML-якоря ; используй Markdown-якоря заголовков. + - Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка, + например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. - Сохраняй существующие ID. При изменении FR сохраняй его номер; новые FR добавляй в конец. Порядок первого документа последовательный. - - Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие - сообщения/действия, если это часть контракта. Параметры сообщений - являются данными, а не скрытым значением кода. - - Если смысловой код спецификации отличается от текущего поведения системы, - явно опиши соответствие и статус реализации в FR. Не утверждай, - что новый код или текст уже возвращается приложением. + - Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия, + если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода. + - При отличии смыслового кода от текущего поведения явно опиши в FR соответствие + и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением. Работа с OpenSpec: - Создай specs//spec.md для каждой capability из proposal. - - Основная спецификация следует краткой схеме templates/main-spec.md; это формат- - ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы - и полный актуальный набор Requirements. + - Основная spec: Purpose, ## Границы и полный актуальный набор Requirements. + Ориентир формата — templates/main-spec.md, не генерируемый артефакт. - Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements. - - Для новой capability delta-спецификация начинается с ## Purpose - (не менее 50 знаков). Для существующей capability Purpose в delta не добавляй. - - MODIFIED содержит полный Requirement: ID, один Scenario и все FR. - Его заголовок должен совпадать с заголовком соответствующего Requirement - в основной спецификации. + - Для новой capability начинай delta с ## Purpose (не менее 50 знаков); + для существующей Purpose не добавляй. + - MODIFIED содержит полный Requirement: ID, один Scenario и все FR; + заголовок совпадает с соответствующим Requirement основной spec. - В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO. Это операции над требованиями, не сценарии технических функций. - - При копировании блоков в delta сохраняй ID Requirements, номера и - заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в - неизменённый Requirement основной спецификации, проверяй delta с - `--base `. - - Не создавай delta для чистого форматирования, изменений инструментов - или рефакторинга. Для изменения без изменения поведения используй - `skip_specs: true`. - - Проверь schema через openspec schema validate use-case-driven. - - Проверь spec через openspec validate и отдельно через - python3 openspec/schemas/use-case-driven/validate_format.py - --require-qualified-ids . Для неизменённых спецификаций - со старыми ID этот флаг не нужен. - Стандартный валидатор OpenSpec не проверяет все правила этого формата. + - В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками. + Для ссылок на неизменённый Requirement основной spec проверяй delta + с `--base `. + - Без изменения поведения (чистое форматирование, инструменты, рефакторинг) + используй `skip_specs: true`, не создавай delta. + - Проверки: `openspec schema validate use-case-driven`; для spec — + `openspec validate` и `python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids `. + Для неизменённых specs со старыми ID флаг не нужен. OpenSpec не проверяет все правила формата. requires: - proposal @@ -247,59 +197,38 @@ artifacts: description: Техническое описание решения и деталей реализации template: design.md instruction: | - Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки - OpenSpec и технические идентификаторы, названия файлов, инструментов - и команд без перевода. + Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические + идентификаторы, названия файлов, инструментов и команды не переводи. - Создай документ design, объясняющий, КАК реализовать изменение. + Design объясняет, КАК реализовать изменение: архитектуру и подход, не пошаговый код. - Когда добавлять design.md (достаточно любого из условий): - - Изменение затрагивает несколько сервисов или модулей либо вводит новый - архитектурный подход. - - Добавляется внешняя зависимость или существенно меняется модель данных. - - Есть сложность, связанная с безопасностью, производительностью или - миграцией. - - До начала разработки нужно принять технические решения, чтобы устранить - неоднозначность. + Добавляй design.md при любом из условий: + - Несколько сервисов/модулей или новый архитектурный подход. + - Внешняя зависимость или существенное изменение модели данных. + - Сложности безопасности, производительности или миграции. + - Технические решения для устранения неоднозначности до разработки. Разделы: - - **Context**: Только текущее состояние и ограничения, необходимые для - объяснения подхода. Причины изменения смотри в proposal, не повторяй их - (например: «См. proposal.md — Why»). - - **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает. - Не повторяй область работ из proposal; указывай только границы решения. - - **Decisions**: Ключевые технические решения и их обоснование: почему - выбран один вариант вместо другого. Укажи рассмотренные альтернативы. - - **Risks / Trade-offs**: Известные ограничения и возможные проблемы. - Формат: [Риск] → [Меры снижения]. - - **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо. - - **Open Questions**: Неизвестные, которые можно безопасно выяснить позже, - не меняя спецификации, подход или состав задач. Не добавляй, если таких - вопросов нет. + - **Context**: Только текущее состояние и ограничения для объяснения подхода. + - **Goals / Non-Goals**: Что решение обеспечивает и исключает; границы решения без повтора scope proposal. + - **Decisions**: Ключевые технические решения, их обоснование и рассмотренные альтернативы. + - **Risks / Trade-offs**: Ограничения и проблемы в формате [Риск] → [Меры снижения]. + - **Migration Plan**: Развёртывание и откат, если применимо. + - **Open Questions**: Только безопасно отложенные вопросы, не влияющие на + specs, подход или состав задач. При отсутствии вопросов раздел не добавляй. + Влияющие вопросы выясни с пользователем сейчас, не подменяй ответ предположением. - Открытые вопросы предназначены для действительно отложенных решений, а не - для пропущенных решений. Если ответ может изменить спецификации, выбранный - подход или состав задач, выясни его сейчас: спроси пользователя, а не - делай предположение. + Вместо повтора причин и состава изменения ссылайся на proposal, вместо + копирования требований — на specs, используя Requirement ID и локальные FR. - Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода. - В proposal описаны причины и состав изменения, в design — способ - реализации. Ссылайся на proposal для обоснования и на specs для требований; - если раздел только повторяет их, дай ссылку вместо повтора. + Сверь Project Context proposal с design: нужны ли новые/обновлённые постоянные + документы и индекс? В Context ссылайся на требования Specs без дублирования. - Ссылайся на Requirement ID и локальные FR; описывай решения реализации - без копирования требований. - - Перед проектированием прочитай применимые принятые ADR из - `openspec/context/adr/` и укажи их идентификаторы в Decisions. Если - изменение принимает долгосрочное архитектурное решение или заменяет - принятое решение, запланируй создание нового ADR по шаблону - `openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed. - Не помечай ADR принятым самостоятельно. Если запрос противоречит - действующему ADR, явно опиши конфликт и запроси решение пользователя до - выбора расходящегося подхода. - - Хороший design объясняет причины технических решений. + Перед проектированием прочитай применимые принятые ADR в `openspec/context/adr/` + и укажи ID в Decisions. Для долгосрочного архитектурного решения или замены + принятого запланируй новый ADR по `openspec/schemas/use-case-driven/templates/adr.md` + со статусом Proposed; самостоятельно не принимай его. Конфликт с действующим + ADR явно опиши и получи решение пользователя до выбора расходящегося подхода. requires: - proposal @@ -308,63 +237,41 @@ artifacts: description: Контрольный список задач с отслеживаемым выполнением template: tasks.md instruction: | - Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные - идентификаторы, пути файлов, названия API, коды и команды без перевода. + Пиши группы и задачи по-русски; обязательные идентификаторы, пути файлов, + названия API, коды и команды не переводи. - Создай список задач, разбивающий работу по реализации на части. + Разбей реализацию на задачи по specs (что создать) и design (как реализовать). - Перед составлением задач проверь Open Questions в design.md. Если ответ на - какой-либо вопрос повлияет на результат разработки, сначала обсуди его с - пользователем; не закладывай в список задач неоговорённые предположения. + Проверь Open Questions в design.md: влияющие на результат вопросы сначала + обсуди с пользователем; не закладывай неоговорённые предположения. - **ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по - формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным - независимо от регистра и пробелов; например, `- [ x]` тоже означает - выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`, - считается незавершённой. Строки без чекбокса вообще не отслеживаются. + Следуй шаблону: apply отслеживает только чекбоксы. Только `x` внутри скобок + означает выполнение независимо от регистра и пробелов; любая другая отметка, + включая пустые скобки, считается незавершённой. Строки без чекбокса не отслеживаются. Правила: - Группируй связанные задачи под нумерованными заголовками `##`. - Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`. - - Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию. - - Располагай задачи в порядке зависимостей: сначала то, что нужно сделать - раньше. - - Для каждой задачи укажи способ проверки выполнения: тест, команду, - наблюдаемое поведение или готовый артефакт. Добавь проверку в описание - чекбокса. Выноси проверку в отдельную задачу только для интеграционных - или системных сценариев, охватывающих несколько задач реализации. + - Каждая задача выполнима за одну сессию; порядок соответствует зависимостям. + - В описание каждого чекбокса включай проверку: тест, команду, наблюдаемое + поведение или готовый артефакт. Отдельная задача проверки допустима только + для интеграционных/системных сценариев, охватывающих несколько задач реализации. Пример: ``` - # Tasks - - ## 1. Подготовка - - - [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов - - [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки - - ## 2. Основная реализация - - - [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта - - [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами + - [ ] 1.1 Реализовать экспорт данных и проверить прохождение теста экспорта ``` - Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это - реализовать. + Связывай задачи с Requirement ID, FR и кодами завершения, если они затронуты. - Связывай задачи с Requirement ID, FR и кодами завершения, если задача - затрагивает эти результаты. + Для нового или заменяющего ADR из design добавь отдельную задачу создания + в `openspec/context/adr/` со статусом Proposed. При замене принятого решения + свяжи новый и прежний ADR полями `supersedes` и `superseded-by`. - YouTrack-задача из proposal сопровождает весь change и не заменяет - чекбоксы реализации в tasks.md. На всех этапах change — от подготовки - proposal до реализации — записывай в YouTrack фактически затраченное время - отдельными work items через MCP, без дублирования уже внесённого времени. - Выбирай только тип работы, поддерживаемый проектом. - - Если в design предусмотрен новый или заменяющий ADR, включи в tasks - отдельную задачу на его создание в `openspec/context/adr/` со статусом - Proposed. При замене принятого решения свяжи новый и прежний ADR через - поля `supersedes` и `superseded-by`. + Если proposal/design предусматривает создание/обновление постоянных документов + контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md` + при изменении состава документов; отсутствующий индекс создавай только + при введении постоянных документов контекста или принятии проектом этой навигационной модели. requires: - specs - design @@ -374,12 +281,11 @@ apply: tracks: tasks.md instruction: | Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их - выполненными по мере работы. Остановись, если столкнёшься с препятствием или - потребуется уточнение. Для change с задачей YouTrack записывай фактически - затраченное во время apply время в её work items через MCP; перед - архивированием проверь, что учтено всё время работы над change. После - успешного `openspec archive` - переведи задачу в конечный статус, предусмотренный проектом YouTrack, - используя доступную схему полей и значений. Не подставляй предполагаемое - название статуса. Считай change завершённым только после успешного - архивирования и закрытия YouTrack-задачи. + выполненными по мере работы, включая задачи по обновлению проектного + контекста и его индекса. Если индекс существует или его создание входит в + tasks.md, проверь, что он соответствует фактическому набору документов. + Убедись, что требования Specs не продублированы в Context. + Для связанной задачи YouTrack после каждого рабочего сеанса запиши только + ещё не учтённое фактическое время через MCP, используя доступный тип работы. + Перед архивацией change проверь, что учтено всё время начиная с Explore. + Остановись, если столкнёшься с препятствием или потребуется уточнение. diff --git a/openspec/schemas/use-case-driven/templates/proposal.md b/openspec/schemas/use-case-driven/templates/proposal.md index 02b8155..0191b18 100644 --- a/openspec/schemas/use-case-driven/templates/proposal.md +++ b/openspec/schemas/use-case-driven/templates/proposal.md @@ -28,7 +28,12 @@ +## Project Context + + + ## YouTrack - - Задача: `` —