# Анализ openspec SDD-схемы: wealth-ledger-sdd

> **Версия схемы:** 1  
> **Автор анализа:** AI-ассистент  
> **Дата:** 2026-08-25

---

## 1. Общая оценка

**B+ / «Готова к использованию, есть куда расти»**

Схема представляет собой зрелый, хорошо структурированный Spec-Driven Development workflow для pet-проектов с multi-repo архитектурой и выделенным specs-store. Pipeline `proposal → specs → design → tasks` с жёстким разделением ответственности между фазами — это правильный фундамент. Схема явно ориентирована на работу с AI-агентом: чёткие prompts, машиночитаемые форматы, парсимый прогресс.

---

## 2. Что сделано сильно

### 2.1. Чёткое разделение ответственности между фазами

Каждая фаза имеет строгое назначение:

| Фаза | Ответственность | Что исключено |
|------|----------------|---------------|
| **Proposal** | «Почему» и «что» — намерение, проблема, scope | Технологии, библиотеки, API, имена файлов |
| **Specs** | Behavior contract — наблюдаемое поведение | Внутренние классы/функции, шаги реализации |
| **Design** | Архитектурные решения и rationale | Построчная инструкция, список правок |
| **Tasks** | Конкретные действия с verification | Архитектурные обоснования |

Это защищает от классической ошибки: выбор технологий на этапе «намерения».

### 2.2. Delta-операции в specs

Поддержка четырёх операций — **ADDED**, **MODIFIED**, **REMOVED**, **RENAMED** — делает specs пригодными для эволюции, а не только для greenfield-разработки. Особенно сильно:

- **MODIFIED** требует полного копирования блока requirement — защита от потери деталей при архивации в openspec.
- **REMOVED** требует **Reason** и **Migration** — забота о обратной совместимости.

### 2.3. Строгие правила формата specs

- **SHALL/MUST** для нормативных требований (исключение `should/may`)
- **#### Scenario** с ровно 4 хэшами — с учётом silent fail это критически важное правило
- **WHEN/THEN** структура — проверяемые сценарии
- **Обязательный `Purpose`** для новых capability (50+ символов под strict-валидацию)

Это делает specs одновременно человекочитаемыми и пригодными для валидации.

### 2.4. Contract Gate Decision в Design

Выделенное внимание к `runtime-openapi` — признак зрелого подхода. В multi-repo setup, где API-контракты разделяют frontend и backend, это предотвращает рассинхронизацию сторон контракта.

### 2.5. Правильная работа с Open Questions

Критерий «если вопрос меняет specs, подход или tasks — решай сейчас, не откладывай» — это ловушка, в которую попадают многие шаблоны. Ты её явно обозначил.

### 2.6. Tasks с обязательным verification

Каждая задача должна иметь **planned verification action** — команда, проверка наблюдаемого поведения или delivered artifact. Это DoD на уровне отдельной задачи.

Также хорошо сформулировано исключение: «Не требуй отдельный unit test только из-за изменения файла». DTO без логики, thin adapters, declarative structures проверяются существующим integration gate.

### 2.7. Apply phase с отслеживанием прогресса

Парсинг checkbox'ов (`- [ ]`) для отслеживания — прагматичное решение для AI-агента. Нет необходимости в сложном state machine.

### 2.8. Интеграция с openspec store

Схема корректно учитывает store-aware пути (`planningHome.root`), не предполагает repo-relative структуру. Это критично для multi-repo setup с выделенным specs-репозиторием.

---

## 3. Области для улучшения

### 3.1. Нет review gates между фазами

В `schema.yaml` есть `requires` (specs требует proposal), но нет явного **checkpoint'а утверждения**.

**Риск:** AI-агент может сгенерировать Design до реального review specs. В pet-проектах, где «владелец продукта» — это сам разработчик, риск ещё выше: нет естественного барьера «кто-то другой должен посмотреть».

**Проявление:**
- Design создаётся с непроверенными предположениями
- Tasks строятся на неверных specs
- Regression: приходится переписывать несколько фаз

### 3.2. Нет traceability между specs и tasks

Нет механизма проверки, что каждый requirement из specs покрыт задачей в tasks.md. Сейчас это держится в голове разработчика (или AI-агента).

**Риск:**
- Пропущенные requirements
- «Лишние» задачи, не связанные с specs
- Невозможность аудита completeness change'а

### 3.3. Spec.md template неполный

В `spec.md` template есть только `## ADDED Requirements`. Но в instruction к specs описаны 4 операции. Для **MODIFIED** и **REMOVED** шаблоны сложнее — их стоит добавить в template с примерами.

**Риск:** AI-агент или разработчик может неправильно оформить MODIFIED (например, внести частичные изменения вместо полного блока), что приведёт к потере деталей при архивации.

### 3.4. Нет «Definition of Done» для change целиком

Когда change считается завершённым? Когда все tasks checked? А кто проверяет, что реализация соответствует specs?

**Риск:**
- Change считается «готовым», но specs не покрыты
- Нет единого артефакта, который можно было бы archive'ить как evidence

### 3.5. Нет управления зависимостями между changes

В multi-repo setup с shared specs store рано или поздно появится change B, который блокируется change A. Сейчас это не выразимо в схеме.

**Риск:**
- Параллельная работа над конфликтующими changes
- Merge-конфликты в specs-store
- Нарушение порядка архивации

### 3.6. Нет приоритизации и sizing'а в tasks

Даже минимальная маркировка `S/M/L` помогает AI-агенту планировать сессии и разработчику — оценивать объём.

### 3.7. Нет явного механизма для «тёплого» отката

Если change реализован, но вызывает regression — как откатить? Схема описывает forward-only flow.

**Риск:**
- Data migration без rollback-стратегии
- Breaking changes в public API без deprecation period
- Security-изменения, которые сложно отменить

### 3.8. Apply phase — неясность с «context files»

В multi-repo setup «read context files» требует понимания, какие именно файлы релевантны. Сейчас это оставлено на усмотрение AI.

**Риск:**
- AI читает лишние файлы — контекст переполняется
- AI пропускает релевантные файлы — решения принимаются на неполных данных

---

## 4. Предложения по улучшению

### 4.1. Добавить review gate между specs и design

**Формат:** Новый артефакт или секция в существующих файлах.

**Вариант A — отдельный артефакт `review.md`:**

```yaml
# schema.yaml
- id: review
  generates: review.md
  description: Checkpoint before design — verify specs completeness and correctness
  template: review.md
  requires: [specs]
```

**Содержимое `review.md`:**

```markdown
## Specs Review Checklist

- [ ] Каждый capability из Proposal имеет соответствующий spec-файл
- [ ] Все requirements используют SHALL/MUST (нет should/may)
- [ ] Каждый requirement имеет хотя бы один scenario
- [ ] Все scenarios используют ровно 4 уровня заголовков (`####`)
- [ ] Для MODIFIED requirements скопирован полный блок (не частично)
- [ ] Для REMOVED requirements указаны Reason и Migration
- [ ] В specs отсутствуют технические детали (имена классов, библиотеки)
- [ ] New capabilities имеют секцию `## Purpose` (50+ символов)
- [ ] `skip_specs: true` установлен только при отсутствии behavior changes

## Review Decision

- [ ] **APPROVED** — переходим к Design
- [ ] **REJECTED** — возврат к Specs, причина:
```

**Вариант B — inline в `schema.yaml`:**

Добавить в `design` артефакт поле `prerequisites`:

```yaml
- id: design
  generates: design.md
  # ...
  prerequisites:
    - type: review
      artifact: specs
      checklist: review.md
```

**Рекомендация:** Вариант A — проще для AI-агента (явный файл, явный checklist).

---

### 4.2. Добавить traceability: specs → tasks

**Формат:** Convention в tasks.md + опциональный артефакт `traceability.md`.

**Convention в tasks.md:**

```markdown
## 2. Core Implementation

- [ ] 2.1 Implement user export  
  **Spec:** `specs/data-export/spec.md#requirement-user-can-export-data`  
  **Verification:** `npm test data-export`

- [ ] 2.2 Add CSV formatting utilities  
  **Spec:** `specs/data-export/spec.md#requirement-export-format`  
  **Verification:** unit tests cover quoting and delimiters
```

**Автоматический артефакт `traceability.md`** (генерируется AI-агентом после tasks):

```markdown
## Traceability Matrix

| Spec Requirement | Task | Status |
|------------------|------|--------|
| data-export#user-can-export-data | 2.1 | ⬜ |
| data-export#export-format | 2.2 | ⬜ |

## Orphan Tasks (no spec link)
- 3.1 Update README — **INFO:** docs-only, no spec required

## Uncovered Requirements
- data-export#error-handling — **WARNING:** no task linked
```

**Рекомендация:** Начать с convention (ручная ссылка в tasks), затем добавить автоматическую генерацию traceability.md.

---

### 4.3. Дополнить spec.md template примерами для всех delta-операций

**Текущий template** (`spec.md`) содержит только `## ADDED Requirements`.

**Предлагаемый полный template:**

```markdown
## Purpose
<!-- New capabilities only: 50+ characters. Delete for existing capabilities. -->

## ADDED Requirements

### Requirement: <!-- requirement name -->
<!-- requirement text using SHALL/MUST -->

#### Scenario: <!-- scenario name -->
- **WHEN** <!-- condition -->
- **THEN** <!-- expected outcome -->

## MODIFIED Requirements

### Requirement: <!-- exact existing requirement name -->
<!-- FULL updated requirement text -->

#### Scenario: <!-- updated scenario name -->
- **WHEN** <!-- updated condition -->
- **THEN** <!-- updated expected outcome -->

## REMOVED Requirements

### Requirement: <!-- requirement name -->
**Reason:** <!-- why removed -->
**Migration:** <!-- how to migrate -->

## RENAMED Requirements

### Requirement: <!-- old name -->
**FROM:** <!-- old exact name -->
**TO:** <!-- new exact name -->
```

**Почему это важно:** AI-агент, следуя template, будет генерировать корректные MODIFIED-блоки. Без примера риск частичного копирования высок.

---

### 4.4. Добавить Definition of Done для change целиком

**Новый артефакт `done.md`:**

```yaml
# schema.yaml
- id: done
  generates: done.md
  description: Completion evidence and verification summary
  template: done.md
  requires: [tasks]
```

**Содержимое `done.md`:**

```markdown
## Completion Evidence

### Specs Coverage
- [ ] All requirements from delta specs have corresponding tasks
- [ ] All tasks are completed and verified
- [ ] Traceability matrix has no uncovered requirements

### Verification Summary
| Area | Gate | Status | Evidence |
|------|------|--------|----------|
| Backend | `npm test` | ✅ | All tests pass |
| Frontend | `npm run build` | ✅ | Build succeeds |
| API Contract | `runtime-openapi` | ✅ | Schema matches implementation |

### Regression Check
- [ ] Existing specs не нарушены (`openspec validate`)
- [ ] Existing tests не сломаны

### Archive Ready
- [ ] All artifacts saved in canonical store
- [ ] `.openspec.yaml` обновлён
```

**Альтернатива:** Добавить как секцию в `tasks.md` в конце, но отдельный артефакт лучше для AI-агента (явный финальный checkpoint).

---

### 4.5. Добавить управление зависимостями между changes

**Добавить в proposal.md template:**

```markdown
## Dependencies

### Blocked By
<!-- Changes that must be completed before this one -->
- [ ] `change-id-1`: <!-- reason -->

### Blocks
<!-- Changes that cannot start until this one is done -->
- `change-id-2`: <!-- reason -->

### Related
<!-- Changes that are related but not blocking -->
- `change-id-3`: <!-- reason -->
```

**В `schema.yaml` добавить валидацию:**

```yaml
validation:
  dependencies:
    check_store: true  # проверять, что blocked-by changes завершены
```

---

### 4.6. Добавить sizing в tasks

**Convention в tasks.md:**

```markdown
## 2. Core Implementation

- [ ] 2.1 Implement user export  
  **Size:** M (2-4 часа)  
  **Spec:** `specs/data-export#user-can-export-data`  
  **Verification:** `npm test data-export`
```

**Размеры:**
- **S** — до 1 часа (config change, DTO, простой adapter)
- **M** — 2-4 часа (новая feature, refactoring с тестами)
- **L** — 1-2 дня (сложная интеграция, data migration)
- **XL** — требует декомпозиции

**Польза:** AI-агент может планировать сессии (не брать L-задачу в конце дня), разработчик — оценивать объём change.

---

### 4.7. Усилить rollback-стратегию

**Добавить в design.md template обязательную секцию:**

```markdown
## Rollback Plan

<!-- Обязательно, если change затрагивает: data migration, public API, auth/security -->

### Rollback Trigger
<!-- При каких условиях откатываем -->

### Rollback Steps
1. <!-- конкретный шаг -->
2. <!-- конкретный шаг -->

### Data Safety
<!-- Что происходит с данными, созданными после деплоя -->

### Rollback Verification
<!-- Как проверить, что откат успешен -->
```

**В `schema.yaml` добавить условие:**

```yaml
- id: design
  # ...
  required_sections:
    - Rollback Plan  # если change трогает migration/api/auth
```

---

### 4.8. Добавить context mapping для multi-repo

**Новый артефакт `context.yaml` (в корне change или в repo):**

```yaml
# .openspec/context.yaml
repositories:
  - name: backend
    path: ../backend
    relevant_paths:
      - src/api/**
      - src/domain/**
      - src/infrastructure/**
    ignore_paths:
      - src/api/__tests__/**

  - name: frontend
    path: ../frontend
    relevant_paths:
      - src/components/**
      - src/services/**

  - name: specs-store
    path: ../wealth-ledger-specs
    relevant_paths:
      - openspec/specs/**
      - openspec/changes/**
```

**Интеграция в schema.yaml:**

```yaml
apply:
  requires: [tasks]
  tracks: tasks.md
  context_source: .openspec/context.yaml
  instruction: |
    Read context files according to context.yaml mapping.
    Prioritize files matching relevant_paths of affected repositories.
```

**Польза:** AI-агент знает, какие файлы читать, а не сканирует всё подряд. Экономия токенов и точность контекста.

---

### 4.9. Добавить convention для commit messages

При архивации change в specs-store и реализации в code repos полезна связь через commit messages.

**Convention:**

```
[openspec:<change-id>] <type>: <description>

Refs: specs/<change-id>/proposal.md
```

Примеры:
```
[openspec:wl-42] feat: add CSV export for user data

Refs: specs/wl-42/proposal.md
```

```
[openspec:wl-42] spec: update export format requirements

Refs: specs/wl-42/specs/data-export/spec.md
```

**Польза:** Git history связывает код с specs. При `git blame` можно найти обоснование изменения.

---

## 5. Итоговая таблица оценок

| Критерий | Оценка | Комментарий |
|----------|--------|-------------|
| **Разделение concerns** | A | Отлично, 4 фазы с чёткими границами |
| **Проверяемость specs** | A | WHEN/THEN, SHALL/MUST, 4-level headers |
| **Защита от деградации** | B+ | Хорошие правила, но нет review gates |
| **Traceability** | C+ | Нет связи specs→tasks, нет completeness check |
| **Полнота workflow** | B | Нет DoD, rollback, cross-change deps |
| **AI-агент friendliness** | A | Чёткие prompts, парсимый формат, чёткие границы |
| **Интеграция с openspec** | A− | Хорошо, но store-aware пути требуют ручного контекста |
| **Multi-repo поддержка** | B | Есть store, но нет context mapping и cross-repo deps |
| **Эволюционность** | B+ | Delta-ops хороши, но нет dependency management |
| **Документированность** | A | Подробные instructions в schema.yaml |

---

## 6. Топ-3 приоритета для доработки

### 🥇 Приоритет 1: Добавить review gate между specs и design
**Почему:** Самый дешёвый способ предотвратить каскадные ошибки. Без него AI-агент может построить Design на неверных specs, и переделывать придётся всё.
**Сложность:** Низкая (новый template-файл + одна строка в schema.yaml)
**ROI:** Очень высокий

### 🥈 Приоритет 2: Дополнить spec.md template примерами MODIFIED/REMOVED/RENAMED
**Почему:** Сейчас это «незаявленная функциональность» — AI-агент может генерировать неверный формат. При архивации в openspec это приведёт к потере деталей.
**Сложность:** Очень низкая (расширить template)
**ROI:** Высокий

### 🥉 Приоритет 3: Добавить traceability (convention specs→tasks)
**Почему:** Гарантирует, что ни один requirement не потерян. Для pet-проекта — это главный способ держать качество без полноценного QA.
**Сложность:** Средняя (convention + опциональная автоматизация)
**ROI:** Высокий

---

## 7. Заключение

Схема **wealth-ledger-sdd** — это продуманный, прагматичный SDD-фреймворк, явно выросший из реальных потребностей multi-repo pet-проекта. Основные сильные стороны — разделение concerns, проверяемость specs и ориентация на AI-агента.

Главные риски — отсутствие review gates и traceability — не критичны для pet-проекта, но станут болевыми точками при росте сложности или переходе к командной работе. Три предложенных приоритета (review gate, полный spec template, traceability) решают 80% рисков при минимальных затратах.

Схема готова к использованию «как есть» и имеет чёткий путь эволюции.

---

*Анализ подготовлен на основе файлов: schema.yaml, proposal.md, spec.md, design.md, tasks.md*