557 lines
38 KiB
Markdown
557 lines
38 KiB
Markdown
# Анализ обновлённой схемы (v2)
|
||
|
||
## 1. Улучшения по сравнению с v1
|
||
|
||
- **Валидация на каждом этапе** – добавлен обязательный запуск `bash specs/scripts/verify-openspec-planning.sh <change>` на стадиях Proposal, Specs, Design и Tasks. Это исключает синтаксические и структурные ошибки до ревью.
|
||
- **Явные артефактные границы** – для каждого артефакта чётко прописано, что **нельзя** включать (например, технологии, имена файлов, пошаговые инструкции). Это предотвращает смешение уровней абстракции.
|
||
- **Утверждение и инвалидация approvals** – каждый следующий артефакт создаётся только после утверждения предыдущего владельцем. При обнаружении несоответствия инвалидируются все downstream approvals.
|
||
- **Трассируемость задач** – в `tasks.md` добавлены обязательные поля `Covers` и `Verification`. Каждая задача теперь привязана к конкретному требованию (`capability-path — exact Requirement heading`) или имеет обоснование `N/A`.
|
||
- **Роллбэк-контракт** – в `design.md` внутри раздела Migration Plan добавлен `### Rollback Contract` с полями Status, Trigger, Actions, Data safety, Verification. Обязателен для критичных изменений (auth, данные, публичные контракты).
|
||
- **Поддержка многокомпонентных изменений** – введены owner‑области (`frontend`, `backend`, `specs`, `docs`, `workspace`). Для каждой `affected` области из Delivery Map должна существовать задача, а `workspace` используется только для оркестрации или верификации.
|
||
- **Примеры для всех типов дельт** – в инструкции к `specs` добавлены компактные примеры для ADDED, MODIFIED, REMOVED, RENAMED, что снижает неоднозначность для AI.
|
||
- **Доработан процесс `apply`** – включает проверку approvals, выполнение скрипта, пошаговое выполнение задач с верификацией, а также механизм обратной связи (feedback routing) при обнаружении несоответствий.
|
||
|
||
## 2. Оставшиеся незначительные нюансы
|
||
|
||
- Инструкции всё ещё достаточно объёмны; можно вынести повторяющиеся части (например, описание `planningHome.root`) в отдельный общий файл.
|
||
- Отсутствует интеграция с CI/CD для автоматического запуска валидации при создании PR – это уже за рамками схемы, но может быть добавлено.
|
||
- Нет явного механизма версионирования самих изменений (кроме версии схемы).
|
||
|
||
## 3. Оценка по 100‑балльной шкале
|
||
|
||
| Критерий | Вес | Оценка | Обоснование |
|
||
|----------|-----|--------|-------------|
|
||
| **Полнота жизненного цикла** (proposal → specs → design → tasks → apply) | 20% | 20 | Все этапы присутствуют, с явными переходами и зависимостями. Есть обратная связь и инвалидация approval при несоответствиях. |
|
||
| **Чёткость разделения уровней абстракции** (why/what/how/do) | 15% | 15 | Артефактные границы жёстко прописаны для каждого этапа. Это предотвращает смешивание intent, поведения, архитектуры и реализации. |
|
||
| **Поведенческая спецификация** (формат дельт, сценарии WHEN/THEN) | 10% | 10 | Требования используют SHALL/MUST, сценарии с 4 `#`, поддерживаются ADDED/MODIFIED/REMOVED/RENAMED. Полное копирование при модификации – безопасно. |
|
||
| **Автоматическая валидация** (verify-openspec-planning.sh) | 10% | 10 | Встроенный скрипт на каждом этапе – отличное решение, предотвращающее синтаксические ошибки до ревью. |
|
||
| **Трассируемость** (Covers в задачах) | 10% | 10 | Каждая задача явно привязана к требованию или имеет обоснование N/A. Это даёт полную прослеживаемость. |
|
||
| **Управление рисками и решениями** (Solution Assessment, Rollback Contract) | 10% | 9 | Оба раздела присутствуют и формализованы. Немного не хватает конкретных критериев, когда `Solution Assessment` обязателен (хотя области перечислены). |
|
||
| **Поддержка многокомпонентных изменений** (owner‑areas, workspace) | 10% | 9 | Введены `frontend/backend/specs/docs/workspace` с явными правилами. Есть, но не детализирована синхронизация версий и порядок деплоя – это скорее для проектов с несколькими репозиториями. |
|
||
| **Процесс утверждений и инвалидаций** | 10% | 10 | Чётко прописано, что каждый артефакт требует approval владельца, а при изменении более раннего артефакта – инвалидируются downstream approvals. |
|
||
| **Инструкции для AI** (чёткость, примеры, избегание неоднозначности) | 5% | 4 | Инструкции подробны, есть примеры. Однако всё ещё достаточно объёмны; можно было бы вынести повторяющиеся части в отдельный файл. |
|
||
|
||
**Итого:** 20 + 15 + 10 + 10 + 10 + 9 + 9 + 10 + 4 = **94/100**
|
||
|
||
## 4. Заключение
|
||
|
||
Схема **почти эталонная** для SDD с openspec. Она пригодна для использования в командах, поддерживает сложные сценарии и обеспечивает высокую дисциплину. Оценка **94/100** отражает уверенность в её качестве и практическую применимость. Рекомендуется внедрить её в pet‑проектах и при необходимости адаптировать под конкретные соглашения команды (например, добавить интеграцию с CI/CD).
|
||
|
||
|
||
## 1. Полная схема
|
||
|
||
### schema.yaml
|
||
```yaml
|
||
name: wealth-ledger-sdd
|
||
version: 2
|
||
description: WealthLedger SDD workflow - proposal → specs → design → tasks → apply
|
||
artifacts:
|
||
- id: proposal
|
||
generates: proposal.md
|
||
description: Owner-approved intent without implementation details
|
||
template: proposal.md
|
||
instruction: |
|
||
Создай Proposal, который формулирует намерение и объясняет, ПОЧЕМУ
|
||
изменение нужно. Его должен понимать и утверждать владелец продукта или
|
||
процесса без знания структуры кода.
|
||
|
||
Sections:
|
||
Разделы:
|
||
- **Why**: проблема или возможность и причина заняться ею сейчас.
|
||
- **What Changes**: намерение, ожидаемый результат и явные non-goals.
|
||
- **Capabilities**: какие поведенческие specs появятся или изменятся:
|
||
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
|
||
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
|
||
- **Impact**: затронутые пользователи, процессы или части системы только
|
||
на уровне scope.
|
||
|
||
IMPORTANT: The Capabilities section is critical. It creates the contract between
|
||
proposal and specs phases. Research existing specs before filling this in.
|
||
Each capability listed here will need a corresponding spec file.
|
||
|
||
Every change must either declare at least one capability (new or
|
||
modified) or explicitly opt out of specs: `openspec validate` rejects a
|
||
change with zero deltas unless the change's `.openspec.yaml` sets
|
||
`skip_specs: true`. Use `skip_specs: true` only when no spec-level
|
||
behavior changes (pure refactor, tooling, docs) - specs describe
|
||
behavior, so if behavior does not change, no spec should change either.
|
||
Do not invent a requirement just to satisfy validation.
|
||
|
||
Artifact boundary — MUST NOT include:
|
||
- технологии, библиотеки, зависимости или выбранную архитектуру: эти
|
||
решения появляются только после Delta Specs в Design;
|
||
- API signatures, database structures, имена файлов, классов или
|
||
функций: это implementation detail для Design;
|
||
- implementation steps, task decomposition или verification commands:
|
||
это конкретизируется в Tasks после утверждения Design.
|
||
|
||
This is the foundation - specs, design, and tasks all build on this.
|
||
|
||
До сохранения исследуй canonical main specs и remediation registry для
|
||
audit-derived change. После записи выполни
|
||
`bash specs/scripts/verify-openspec-planning.sh <change>`: на этой стадии
|
||
verifier проверяет Proposal и явно оставляет downstream validation
|
||
pending. Исправь технический формат и повтори check до запроса approval;
|
||
structural success не означает approval Change Owner.
|
||
requires: []
|
||
|
||
- id: specs
|
||
generates: "specs/**/*.md"
|
||
description: Observable behavior and invariants changed by the proposal
|
||
template: spec.md
|
||
instruction: |
|
||
Создай Delta Specs, определяющие, ЧТО наблюдаемо изменяется в системе.
|
||
|
||
Spec является behavior contract, а не планом изменения кода.
|
||
|
||
Good spec content:
|
||
- Observable behavior users or downstream systems rely on
|
||
- Inputs, outputs, and error conditions
|
||
- External constraints (security, privacy, reliability, compatibility)
|
||
- Scenarios that can be tested or explicitly validated
|
||
|
||
Artifact boundary — MUST NOT include:
|
||
- intent или scope за пределами утверждённого Proposal: сначала верни
|
||
изменение в Proposal;
|
||
- internal components, class/function names, files или database
|
||
structures: implementation structure определяется в Design;
|
||
- library, framework или infrastructure choices: alternatives и решение
|
||
принадлежат Design;
|
||
- step-by-step implementation, delivery sequencing или verification
|
||
commands: это принадлежит Tasks;
|
||
- test procedure вместо behavior scenario: scenario фиксирует
|
||
наблюдаемые WHEN/THEN, а способ проверки выбирается позднее.
|
||
|
||
Quick test: if the implementation can change without changing externally
|
||
visible behavior, it likely does not belong in the spec.
|
||
|
||
Create one spec file per capability listed in the proposal's Capabilities section.
|
||
`<capability-path>` is the spec directory relative to `specs/` (for example,
|
||
`user-auth` or `identity/user-auth`). Preserve the full path:
|
||
- New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
|
||
- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
|
||
|
||
There must be at least one spec file unless the change's `.openspec.yaml`
|
||
sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
|
||
rejects a zero-delta change without that marker. If the proposal lists no
|
||
capabilities and `skip_specs` is not set, revisit the proposal first.
|
||
|
||
Delta operations (use ## headers):
|
||
- **ADDED Requirements**: New capabilities
|
||
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
|
||
- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
|
||
- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
|
||
|
||
Format requirements:
|
||
- Each requirement: `### Requirement: <name>` followed by description
|
||
- Use SHALL/MUST for normative requirements (avoid should/may)
|
||
- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
|
||
- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
|
||
- Every requirement MUST have at least one scenario.
|
||
|
||
New capabilities only: start the delta spec with a `## Purpose` section -
|
||
one or two sentences (50+ characters, or `openspec validate --strict`
|
||
reports it as too brief) describing what the capability is for. Archive
|
||
copies it into the main spec it creates; without it the new main spec is
|
||
left with a `TBD ... Update Purpose after archive` placeholder to fill in
|
||
by hand. Do NOT add `## Purpose` to a delta for an existing capability -
|
||
that spec already has one and the delta's is ignored. To change an
|
||
existing capability's Purpose - including a leftover `TBD` placeholder -
|
||
edit `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
|
||
directly. `planningHome.root` comes from the `openspec instructions ...
|
||
--json` response. Always use it rather than a repo-relative path: it
|
||
resolves to the store whenever the change lives in one - whether that
|
||
came from `--store`, a project `store:` pointer, or a global default
|
||
store - and to the current repository otherwise. Do not try to work out
|
||
which case applies; the field already has.
|
||
|
||
MODIFIED requirements workflow:
|
||
1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
|
||
2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
|
||
3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
|
||
4. Ensure header text matches exactly (whitespace-insensitive)
|
||
|
||
Common pitfall: Using MODIFIED with partial content loses detail at archive time.
|
||
If adding new concerns without changing existing behavior, use ADDED instead.
|
||
|
||
Compact operation examples:
|
||
ADDED in a new capability: include Purpose.
|
||
Purpose
|
||
Lets users take their data out of the product in a portable format.
|
||
|
||
ADDED Requirements
|
||
Requirement: User can export data
|
||
The system SHALL allow users to export their data in CSV format.
|
||
|
||
Scenario: Successful export
|
||
WHEN user clicks "Export" button
|
||
|
||
THEN system downloads a CSV file with all user data
|
||
|
||
MODIFIED: copy the complete old requirement, then edit it.
|
||
MODIFIED Requirements
|
||
Requirement: Session expiration
|
||
The system MUST reject an expired session and preserve every surviving
|
||
scenario from the main spec.
|
||
|
||
Scenario: Expired session
|
||
WHEN a request uses an expired session
|
||
|
||
THEN the system rejects the request
|
||
|
||
REMOVED requires both fields.
|
||
REMOVED Requirements
|
||
Requirement: Legacy export
|
||
Reason: Replaced by new export system
|
||
Migration: Use new export endpoint at /api/v2/export
|
||
|
||
RENAMED changes only the heading.
|
||
RENAMED Requirements
|
||
FROM: ### Requirement: Old name
|
||
|
||
TO: ### Requirement: New name
|
||
|
||
|
||
Specs должны быть проверяемыми, но scenario не означает автоматический
|
||
unit test: уровень проверки выбирается по риску поведения.
|
||
|
||
Перед записью установи явный approval Proposal из разговора. После
|
||
записи выполни `bash specs/scripts/verify-openspec-planning.sh <change>`
|
||
и исправь технические ошибки до запроса approval Delta Specs. Если
|
||
обнаружено изменение intent, вернись к Proposal и инвалидируй downstream
|
||
approvals вместо скрытого расширения Specs.
|
||
requires:
|
||
- proposal
|
||
|
||
- id: design
|
||
generates: design.md
|
||
description: Architectural implementation approach and delivery decisions
|
||
template: design.md
|
||
instruction: |
|
||
Создай Design, объясняющий, КАК архитектурно выполнить утверждённые
|
||
Delta Specs.
|
||
|
||
Artifact boundary — MUST NOT include:
|
||
- новое observable behavior или invariant, отсутствующие в утверждённых
|
||
Delta Specs: сначала верни изменение в Specs;
|
||
- пересказ Proposal или Specs вместо архитектурных constraints и
|
||
решений, необходимых для выбранного подхода;
|
||
- file-by-file implementation checklist, verification commands или
|
||
пошаговый список правок: это принадлежит Tasks;
|
||
- будущие delivery results, commit identifiers или Completion Evidence:
|
||
они фиксируются только после наблюдаемого выполнения.
|
||
|
||
Обязательные разделы:
|
||
- **Context**: только текущее состояние и ограничения подхода.
|
||
- **Goals / Non-Goals**: технические границы, не пересказ Proposal.
|
||
- **Decisions**: крупные решения, rationale и рассмотренные alternatives.
|
||
- **Delivery Map**: ровно frontend, backend, specs и docs; для каждой
|
||
области `affected` с ожидаемым архитектурным результатом либо `N/A` с
|
||
конкретной причиной. `specs` всегда affected. Здесь же зафиксируй
|
||
Contract Gate Decision для `runtime-openapi`: `required`, только когда
|
||
change затрагивает обе стороны API contract, либо `N/A` с причиной.
|
||
- **Risks / Trade-offs**: риск и mitigation.
|
||
- **Migration Plan**: порядок поставки и rollback, если применимо.
|
||
|
||
Внутри Migration Plan добавь `### Rollback Contract` с table fields.
|
||
Status `required` обязателен для auth/security, data integrity/migration,
|
||
public contract и другого существенно труднообратимого решения и требует
|
||
Trigger, Actions, Data safety и Verification. В остальных случаях Status
|
||
`N/A` требует конкретный Reason. Отдельный rollback artifact не создавай.
|
||
|
||
Добавь **Solution Assessment**, если изменение вводит или существенно
|
||
заменяет auth, security, storage, external integration, observability,
|
||
caching, concurrency или общую infrastructure/tooling либо содержит
|
||
другое дорогостоящее необратимое решение. Сравни зрелые готовые решения
|
||
по fit, maturity, security, operating cost, constraints и migration cost.
|
||
Custom implementation допустима только после фиксации несовместимости
|
||
подходящих alternatives и принятых рисков. Не создавай отдельный artifact.
|
||
|
||
**Open Questions** допустим только для неизвестного, которое не меняет
|
||
Specs, выбранный подход или Tasks. Иначе остановись и запроси решение
|
||
владельца до сохранения Design.
|
||
|
||
Open questions are for genuinely deferrable unknowns, not decisions you
|
||
skipped. If a question would change the specs, the chosen approach, or
|
||
the task breakdown, resolve it now - ask the user instead of guessing.
|
||
|
||
Design формируется только после явного owner approval Delta Specs. После
|
||
записи выполни `bash specs/scripts/verify-openspec-planning.sh <change>`
|
||
и исправь технические ошибки до запроса approval. Если Design показывает
|
||
несовместимость с intent или behavior, остановись, вернись к самому
|
||
раннему затронутому artifact и инвалидируй downstream approvals.
|
||
requires:
|
||
- specs
|
||
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: Implementation checklist with trackable tasks
|
||
template: tasks.md
|
||
instruction: |
|
||
Создай implementation checklist, достаточный для выполнения Design и
|
||
Delta Specs. Это конкретное DO, а не ещё один архитектурный документ.
|
||
|
||
Before writing tasks, check design.md for Open Questions. If any of them
|
||
would change what gets built, resolve them with the user first - do not
|
||
bake an unstated assumption into the task list.
|
||
|
||
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
||
checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
|
||
|
||
Правила:
|
||
- Группируй задачи под numbered `##` headings и располагай по dependencies.
|
||
- Каждая задача MUST иметь формат `- [ ] X.Y [area] action`, быть
|
||
выполнимой за одну рабочую сессию и иметь ровно одного owner из
|
||
`frontend`, `backend`, `specs`, `docs`, `workspace`.
|
||
- Сразу после checkbox добавляй ровно по одной indented metadata line:
|
||
`- **Covers:**` и `- **Verification:**`.
|
||
- `Covers` содержит одну или несколько пар
|
||
`` `capability-path` — `exact Requirement heading` `` либо
|
||
`` `N/A` — concrete reason ``. Каждый Delta Requirement должен быть
|
||
покрыт хотя бы одной task; собственные requirement IDs не вводятся.
|
||
- Owner repository не может иметь статус `N/A` в Delivery Map.
|
||
Cross-repository implementation разделяй; `workspace` используй только
|
||
для orchestration/verification и с конкретным `N/A` Covers rationale.
|
||
- Для каждой `affected` области Delivery Map должна существовать задача
|
||
реализации и её canonical local gate; пустые commits запрещены.
|
||
- Каждая задача MUST указывать planned verification action: команду,
|
||
проверку наблюдаемого поведения или delivered artifact.
|
||
- Автоматические тесты обязательны для security/privacy, денежных
|
||
расчётов, data integrity/migration, concurrency, public contracts,
|
||
critical journeys и подтверждённых regressions.
|
||
- Не требуй отдельный unit test только из-за изменения файла. DTO без
|
||
логики, declarative structures, thin adapters, прямолинейная
|
||
orchestration, hygiene scripts и third-party behavior проверяются
|
||
существующим integration/contract gate, если нет собственного
|
||
branching, transformation, invariant или regression.
|
||
- Перед custom implementation в обязательных областях включи действие по
|
||
утверждённому Solution Assessment из Design.
|
||
|
||
Artifact boundary — MUST NOT include:
|
||
- новое observable behavior или Requirement: сначала верни изменение в
|
||
Specs;
|
||
- новое архитектурное решение или отклонение от утверждённого Design:
|
||
сначала обнови Design;
|
||
- одну задачу с несколькими owner repositories: раздели её по delivery
|
||
areas;
|
||
- vague action без проверяемого результата: сформулируй конкретное DO и
|
||
planned Verification;
|
||
- ещё не наблюдённые результаты как выполненные, предполагаемые commit
|
||
identifiers, archive path или post-archive Completion Evidence: такое
|
||
evidence создаётся только после факта.
|
||
|
||
Example:
|
||
|
||
1. Delivery
|
||
□ 1.1 [backend] Implement session rejection
|
||
Covers: user-authentication — Expired session is rejected
|
||
|
||
Verification: Run the backend canonical gate and the expiry contract test.
|
||
|
||
□ 1.2 [workspace] Run cross-area semantic review
|
||
Covers: N/A — verification only; no independent spec behavior.
|
||
|
||
Verification: Compare delivery against every approved Requirement and Scenario.
|
||
|
||
|
||
Reference specs for what needs to be built, design for how to build it.
|
||
После записи выполни
|
||
`bash specs/scripts/verify-openspec-planning.sh <change>` и исправь
|
||
технические нарушения до запроса approval. Если Tasks требует новое
|
||
behavior или architecture, не расширяй scope: вернись к Specs или Design
|
||
и инвалидируй Tasks approval.
|
||
requires:
|
||
- design
|
||
|
||
apply:
|
||
requires: [ tasks ]
|
||
tracks: tasks.md
|
||
instruction: |
|
||
Сначала проверь exact OpenSpec version contract. Работай только с change в
|
||
canonical store `wealth-ledger-specs` и не создавай parallel planning root.
|
||
Apply допустим только после явных approvals Proposal, Delta Specs, Design и
|
||
Tasks из разговора. До реализации выполни
|
||
`bash specs/scripts/verify-openspec-planning.sh <change>`.
|
||
|
||
Read context files, work through pending tasks, run each planned
|
||
Verification and mark a checkbox complete only after observed success.
|
||
Pause if you hit blockers or need clarification.
|
||
|
||
Feedback routing:
|
||
- intent/scope mismatch → Proposal;
|
||
- observable behavior mismatch → Delta Specs;
|
||
- architecture/rollback mismatch → Design;
|
||
- decomposition/ownership/coverage mismatch → Tasks.
|
||
|
||
Останови downstream work, сообщи наблюдаемое основание и инвалидируй
|
||
approvals начиная с самого раннего затронутого artifact. Только
|
||
механическое syntax/format исправление без изменения intent, behavior,
|
||
decisions или task scope можно исправить и повторно структурно проверить
|
||
без reapproval. Structural validation не заменяет semantic verification и
|
||
independent read-only review.
|
||
|
||
design.md (шаблон)
|
||
## Context
|
||
|
||
<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
<!-- What this design aims to achieve -->
|
||
|
||
**Non-Goals:**
|
||
<!-- What is explicitly out of scope -->
|
||
|
||
## Decisions
|
||
|
||
<!-- Key design decisions with rationale and alternatives considered -->
|
||
|
||
## Delivery Map
|
||
|
||
| Area | Status | Architectural outcome or N/A reason |
|
||
| --- | --- | --- |
|
||
| frontend | `affected` or `N/A` | <!-- concrete result or reason --> |
|
||
| backend | `affected` or `N/A` | <!-- concrete result or reason --> |
|
||
| specs | `affected` | <!-- normative result --> |
|
||
| docs | `affected` or `N/A` | <!-- as-built documentation result or reason --> |
|
||
|
||
### Contract Gate Decision
|
||
|
||
| Gate | Status | Reason |
|
||
| --- | --- | --- |
|
||
| runtime-openapi | `required` or `N/A` | <!-- required only when both API contract sides change; otherwise concrete N/A reason --> |
|
||
|
||
## Solution Assessment
|
||
|
||
<!-- Include only when the change crosses a mandatory build-vs-buy trigger.
|
||
Compare mature options and custom implementation; otherwise remove section. -->
|
||
|
||
## Risks / Trade-offs
|
||
|
||
<!-- Known risks and trade-offs -->
|
||
|
||
## Migration Plan
|
||
|
||
<!-- Delivery order and rollback, when applicable -->
|
||
|
||
### Rollback Contract
|
||
|
||
| Field | Decision |
|
||
| --- | --- |
|
||
| Status | `required` or `N/A` |
|
||
| Reason | <!-- concrete reason when N/A --> |
|
||
| Trigger | <!-- required when Status is required --> |
|
||
| Actions | <!-- required when Status is required --> |
|
||
| Data safety | <!-- required when Status is required --> |
|
||
| Verification | <!-- required when Status is required --> |
|
||
|
||
## Open Questions
|
||
|
||
<!-- Only questions that cannot change Specs, approach or Tasks; otherwise
|
||
resolve with the Change Owner before saving Design. Remove if empty. -->
|
||
|
||
proposal.md (шаблон)
|
||
## Why
|
||
|
||
<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
|
||
|
||
## What Changes
|
||
|
||
<!-- Describe the intended outcome and explicit non-goals without technologies,
|
||
APIs, files, dependencies or implementation decisions. -->
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
|
||
(e.g., user-auth or identity/user-auth) that follow the project's existing
|
||
spec organization. Each creates specs/<capability-path>/spec.md. -->
|
||
- `<capability-path>`: <brief description of what this capability covers>
|
||
|
||
### Modified Capabilities
|
||
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
|
||
Only list here if spec-level behavior changes. Each needs a delta spec file.
|
||
Use the exact existing path under openspec/specs/. Leave empty if no requirement
|
||
changes. A change with no capabilities at all (pure refactor, tooling, docs)
|
||
must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
|
||
a zero-delta change without that marker. Do not invent a requirement just to
|
||
satisfy validation. -->
|
||
- `<existing-capability-path>`: <what requirement is changing>
|
||
|
||
## Impact
|
||
|
||
<!-- Affected users, processes or system areas at scope level only. -->
|
||
|
||
spec.md (шаблон)
|
||
## Purpose
|
||
<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: <!-- requirement name -->
|
||
<!-- requirement text -->
|
||
|
||
#### Scenario: <!-- scenario name -->
|
||
- **WHEN** <!-- condition -->
|
||
- **THEN** <!-- expected outcome -->
|
||
|
||
tasks.md (шаблон)
|
||
## 1. <!-- Dependency-ordered task group -->
|
||
|
||
- [ ] 1.1 [area] <!-- Concrete implementation action -->
|
||
- **Covers:** `<capability-path>` — `<exact Requirement heading>`
|
||
- **Verification:** <!-- Planned command, observable check or delivered artifact -->
|
||
- [ ] 1.2 [area] <!-- Concrete implementation action -->
|
||
- **Covers:** `N/A` — <!-- Concrete reason this task has no spec-level behavior -->
|
||
- **Verification:** <!-- Planned command, observable check or delivered artifact -->
|
||
|
||
## 2. <!-- Affected repository delivery and gates -->
|
||
|
||
- [ ] 2.1 [area] <!-- Affected repository action -->
|
||
- **Covers:** `<capability-path>` — `<exact Requirement heading>`
|
||
- **Verification:** <!-- Canonical local gate -->
|
||
- [ ] 2.2 [workspace] <!-- Cross-area orchestration or verification only -->
|
||
- **Covers:** `N/A` — <!-- Concrete orchestration/verification reason -->
|
||
- **Verification:** <!-- Cross-area gate or semantic review -->
|
||
|
||
2. Анализ обновлённой схемы (v2)
|
||
2.1. Улучшения по сравнению с v1
|
||
Валидация на каждом этапе – добавлен обязательный запуск bash specs/scripts/verify-openspec-planning.sh <change>.
|
||
|
||
Явные артефактные границы – для каждого артефакта чётко перечислено, что нельзя включать, что предотвращает смешение уровней.
|
||
|
||
Утверждение и инвалидация – каждый артефакт требует approval владельца, при обнаружении несоответствия инвалидируются downstream approvals.
|
||
|
||
Трассируемость задач – в tasks.md добавлены поля Covers и Verification, каждая задача привязана к требованию.
|
||
|
||
Роллбэк-контракт – в design.md добавлен обязательный раздел Rollback Contract для критичных изменений.
|
||
|
||
Поддержка многокомпонентности – введены owner‑области (frontend, backend, specs, docs, workspace) с правилами для кросс‑репозиторных изменений.
|
||
|
||
Примеры для всех дельт – в инструкции к specs добавлены компактные примеры для ADDED, MODIFIED, REMOVED, RENAMED.
|
||
|
||
Доработан процесс apply – включает проверку approvals, выполнение скрипта, пошаговую реализацию с верификацией и механизм обратной связи.
|
||
|
||
2.2. Оставшиеся незначительные нюансы
|
||
Инструкции всё ещё достаточно объёмны; можно вынести повторяющиеся части (например, описание planningHome.root) в отдельный общий файл.
|
||
|
||
Отсутствует интеграция с CI/CD для автоматического запуска валидации при создании PR – это уже за рамками схемы, но может быть добавлено.
|
||
|
||
Нет явного механизма версионирования самих изменений (кроме версии схемы).
|
||
|
||
3. Оценка по 100‑балльной шкале
|
||
Критерий Вес Оценка Обоснование
|
||
Полнота жизненного цикла (proposal → specs → design → tasks → apply) 20% 20 Все этапы присутствуют, с явными переходами и зависимостями. Есть обратная связь и инвалидация approval при несоответствиях.
|
||
Чёткость разделения уровней абстракции (why/what/how/do) 15% 15 Артефактные границы жёстко прописаны для каждого этапа. Это предотвращает смешивание intent, поведения, архитектуры и реализации.
|
||
Поведенческая спецификация (формат дельт, сценарии WHEN/THEN) 10% 10 Требования используют SHALL/MUST, сценарии с 4 #, поддерживаются ADDED/MODIFIED/REMOVED/RENAMED. Полное копирование при модификации – безопасно.
|
||
Автоматическая валидация (verify-openspec-planning.sh) 10% 10 Встроенный скрипт на каждом этапе – отличное решение, предотвращающее синтаксические ошибки до ревью.
|
||
Трассируемость (Covers в задачах) 10% 10 Каждая задача явно привязана к требованию или имеет обоснование N/A. Это даёт полную прослеживаемость.
|
||
Управление рисками и решениями (Solution Assessment, Rollback Contract) 10% 9 Оба раздела присутствуют и формализованы. Немного не хватает конкретных критериев, когда Solution Assessment обязателен (хотя области перечислены).
|
||
Поддержка многокомпонентных изменений (owner‑areas, workspace) 10% 9 Введены frontend/backend/specs/docs/workspace с явными правилами. Есть, но не детализирована синхронизация версий и порядок деплоя – это скорее для проектов с несколькими репозиториями.
|
||
Процесс утверждений и инвалидаций 10% 10 Чётко прописано, что каждый артефакт требует approval владельца, а при изменении более раннего артефакта – инвалидируются downstream approvals.
|
||
Инструкции для AI (чёткость, примеры, избегание неоднозначности) 5% 4 Инструкции подробны, есть примеры. Однако всё ещё достаточно объёмны; можно было бы вынести повторяющиеся части в отдельный файл.
|
||
Итого: 20 + 15 + 10 + 10 + 10 + 9 + 9 + 10 + 4 = 94/100
|
||
|
||
|