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

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
+183 -277
View File
@@ -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/<capability-path>/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/<capability-path>/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 "<spec-id>" --type spec --json --no-scenarios`.
Команда вернёт назначение capability и тексты требований, не загружая
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам
только для зарегистрированного отдельного хранилища и сохраняй
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя,
без этого параметра возникнет неоднозначность при выборе. Команда
`openspec list` без `--specs` показывает активные изменения (`changes`),
а не спецификации, поэтому не отражает уже описанное в проекте поведение.
Используй точный путь
существующей capability, не создавай похожее имя.
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
описано и что нужно изменить, прочитай каждую подходящую спецификацию
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
(с тем же правилом для `--store`). Для каждой перечисленной capability
потребуется соответствующий файл спецификации.
Перед заполнением Capabilities изучи существующие specs:
1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes.
2. Для подходящих вариантов — `openspec show "<spec-id>" --type spec --json --no-scenarios`:
обзор назначения и требований без загрузки целых спецификаций.
3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком,
включая сценарии: `openspec show "<spec-id>" --type spec`.
Добавляй `--store "<id>"` к этим командам только для зарегистрированного
отдельного хранилища. Сохраняй `--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: <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: <KEY>` и `YouTrack application label: <APP-NAME>`.
До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные
поля и доступность/применимость тега `<APP-NAME>`. При отсутствии настройки,
тега, невозможности проверки или недоступности 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 и локальный номер: <requirement-id>.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 идёт `#### Функциональные требования` с заголовками
`##### <requirement-id>.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-якоря вида <a id="..."></a>. 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-якоря <a id="..."></a>; используй Markdown-якоря заголовков.
- Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка,
например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
новые FR добавляй в конец. Порядок первого документа последовательный.
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
сообщения/действия, если это часть контракта. Параметры сообщений
являются данными, а не скрытым значением кода.
- Если смысловой код спецификации отличается от текущего поведения системы,
явно опиши соответствие и статус реализации в FR. Не утверждай,
что новый код или текст уже возвращается приложением.
- Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия,
если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода.
- При отличии смыслового кода от текущего поведения явно опиши в FR соответствие
и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением.
Работа с OpenSpec:
- Создай specs/<capability-path>/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 <master-spec>`.
- Не создавай 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 <spec-path>. Для неизменённых спецификаций
со старыми ID этот флаг не нужен.
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
- В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками.
Для ссылок на неизменённый Requirement основной spec проверяй delta
с `--base <master-spec>`.
- Без изменения поведения (чистое форматирование, инструменты, рефакторинг)
используй `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 <spec-path>`.
Для неизменённых 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.
Остановись, если столкнёшься с препятствием или потребуется уточнение.