docs: record SDD audit remediation
This commit is contained in:
@@ -0,0 +1,530 @@
|
||||
# Анализ 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*
|
||||
Reference in New Issue
Block a user