531 lines
23 KiB
Markdown
531 lines
23 KiB
Markdown
# Анализ 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*
|