diff --git a/openspec/config.yaml b/openspec/config.yaml index 3632647..9fb0945 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,7 +1,21 @@ schema: use-case-driven +context: | + ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и + реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если + запрос или предлагаемое решение конфликтует с принятым ADR, явно сообщи о + конфликте пользователю; не обходи решение молча. Новые ADR оформляй по + шаблону `openspec/schemas/use-case-driven/templates/adr.md` со статусом + Proposed; не помечай решение Accepted без явного принятия владельцем решения. + rules: tasks: - - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в `pyproject.toml`; один change повышает версию ровно один раз. - - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. - - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. + - >- + Завершай каждый реализуемый change отдельной последней задачей на + увеличение версии пакета в `pyproject.toml`; один change повышает версию + ровно один раз. До 1.0.0 используй PATCH для исправлений, рефакторинга и + документации, MINOR для новых возможностей и изменений публичного + контракта, в том числе несовместимых; переход на 1.0.0 начинает стабильный + публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, + рефакторинга и документации, MINOR для обратно совместимых возможностей, + MAJOR для несовместимых изменений публичного контракта. diff --git a/openspec/schemas/use-case-driven/README.md b/openspec/schemas/use-case-driven/README.md index 207cd1c..c739b1f 100644 --- a/openspec/schemas/use-case-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -151,6 +151,38 @@ Scenario в таких операциях не создаётся. В delta со фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. Форматирование спецификации само по себе не реализует этот контракт в приложении. +## Архитектурные решения (ADR) + +Храни ADR проекта в `openspec/context/adr/` и называй файлы +`ADR-<номер>-<краткое-описание>.md`, например +`ADR-0001-use-postgresql.md`. Используй четырёхзначную последовательную +нумерацию: новый номер на единицу больше максимального номера в каталоге. +Номер не переиспользуется, даже если решение отклонено или заменено. Краткое +описание в имени файла пиши в `kebab-case`. + +Создавай ADR для долгосрочных архитектурных решений с последствиями для +будущих изменений: выбора между значимыми вариантами, общих ограничений, +границ компонентов и решений, которые иначе пришлось бы повторно принимать. +Не создавай ADR для каждого change, деталей реализации, уже полностью заданных +спецификацией, или временных задач. + +В ADR фиксируй контекст и проблему, факторы решения, рассмотренные варианты, +выбранное решение и его последствия. Используй статусы `Proposed`, `Accepted`, +`Rejected` и `Superseded`. Предложенный ADR становится действующим только после +явного принятия владельцем решения. Отклонённые и заменённые ADR сохраняй как +историю. Не меняй принятое решение задним числом: при пересмотре создай новый +ADR со ссылкой на заменяемый и обнови его статус на `Superseded`. В новом ADR +укажи заменяемый ID в `supersedes`, а в прежнем — новый ID в `superseded-by`. + +Перед проектированием и реализацией агент читает применимые принятые ADR. +Изменение должно ссылаться на относящиеся к нему ADR в `design.md`. При +противоречии между запросом и принятым ADR агент явно сообщает о конфликте и +получает решение пользователя, а не обходит ADR молча. Агент может подготовить +ADR со статусом `Proposed`, но не принимает его самостоятельно. + +Шаблон нового решения находится в +[`templates/adr.md`](templates/adr.md). + ## Проверки ```sh diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml index 59cb16b..f45f106 100644 --- a/openspec/schemas/use-case-driven/schema.yaml +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -269,6 +269,15 @@ artifacts: Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований. + Перед проектированием прочитай применимые принятые ADR из + `openspec/context/adr/` и укажи их идентификаторы в Decisions. Если + изменение принимает долгосрочное архитектурное решение или заменяет + принятое решение, запланируй создание нового ADR по шаблону + `openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed. + Не помечай ADR принятым самостоятельно. Если запрос противоречит + действующему ADR, явно опиши конфликт и запроси решение пользователя до + выбора расходящегося подхода. + Хороший design объясняет причины технических решений. requires: - proposal @@ -324,6 +333,11 @@ artifacts: Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. + + Если в design предусмотрен новый или заменяющий ADR, включи в tasks + отдельную задачу на его создание в `openspec/context/adr/` со статусом + Proposed. При замене принятого решения свяжи новый и прежний ADR через + поля `supersedes` и `superseded-by`. requires: - specs - design diff --git a/openspec/schemas/use-case-driven/templates/adr.md b/openspec/schemas/use-case-driven/templates/adr.md new file mode 100644 index 0000000..abeb532 --- /dev/null +++ b/openspec/schemas/use-case-driven/templates/adr.md @@ -0,0 +1,36 @@ +--- +status: Proposed +date: YYYY-MM-DD +decision-makers: + - <имя или роль владельца решения> +supersedes: [] +superseded-by: +--- + +# ADR-<номер>: <Краткое название решения> + +## Контекст и проблема + +Какую проблему нужно решить и какие ограничения важны для выбора? + +## Факторы решения + +- <Требование или ограничение, влияющее на решение> + +## Рассмотренные варианты + +- **<Вариант>** — преимущества и недостатки. + +## Решение + +Какой вариант выбран и почему? Заполняется при принятии ADR; до этого раздел +может содержать предлагаемое решение. + +## Последствия + +- Положительные: <результаты и преимущества>. +- Отрицательные или компромиссы: <цена решения, ограничения, риски>. + +## Связанные решения + +-