23 KiB
Анализ 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:
# schema.yaml
- id: review
generates: review.md
description: Checkpoint before design — verify specs completeness and correctness
template: review.md
requires: [specs]
Содержимое review.md:
## 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:
- 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:
## 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):
## 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:
## 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:
# schema.yaml
- id: done
generates: done.md
description: Completion evidence and verification summary
template: done.md
requires: [tasks]
Содержимое done.md:
## 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:
## 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 добавить валидацию:
validation:
dependencies:
check_store: true # проверять, что blocked-by changes завершены
4.6. Добавить sizing в tasks
Convention в tasks.md:
## 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 обязательную секцию:
## Rollback Plan
<!-- Обязательно, если change затрагивает: data migration, public API, auth/security -->
### Rollback Trigger
<!-- При каких условиях откатываем -->
### Rollback Steps
1. <!-- конкретный шаг -->
2. <!-- конкретный шаг -->
### Data Safety
<!-- Что происходит с данными, созданными после деплоя -->
### Rollback Verification
<!-- Как проверить, что откат успешен -->
В schema.yaml добавить условие:
- id: design
# ...
required_sections:
- Rollback Plan # если change трогает migration/api/auth
4.8. Добавить context mapping для multi-repo
Новый артефакт context.yaml (в корне change или в repo):
# .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:
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