@@ -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 через o pens pec schema validate use-case-driven.
Для неизменённых specs со старыми ID флаг не нужен. O penS pec не проверяет все правила формата.
- Проверь 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 и технические идентификаторы, названия файлов, инструментов
идентификаторы, названия файлов, инструментов и команды не переводи.
и команд без перевода.
Создай документ d esign, объясняющий , КАК реализовать изменение.
D esign объясняет , КАК реализовать изменение: архитектуру и подход, не пошаговый код .
Когда д обавлять 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-задачи.