docs: record second OpenSpec schema review
This commit is contained in:
@@ -0,0 +1,284 @@
|
||||
# Анализ openspec SDD-схемы v2: wealth-ledger-sdd
|
||||
|
||||
> **Версия схемы:** 2
|
||||
> **Автор анализа:** AI-ассистент
|
||||
> **Дата:** 2026-08-26
|
||||
|
||||
---
|
||||
|
||||
## 1. Общая оценка v2
|
||||
|
||||
**A− / «Зрелая схема, готовая к production-like использованию»**
|
||||
|
||||
Переход с v1 на v2 — качественный скачок. Из 9 рекомендаций из предыдущего анализа **5 полностью или частично учтены**, при этом добавлены 4 новых сильных механизма, которых не было ни в v1, ни в рекомендациях. Схема теперь защищена от основных рисков: каскадных ошибок, scope creep, потери traceability и неконтролируемого rollback.
|
||||
|
||||
---
|
||||
|
||||
## 2. Сравнение v1 → v2: что изменилось
|
||||
|
||||
### 2.1. Schema.yaml — структурные улучшения
|
||||
|
||||
| Аспект | v1 | v2 | Оценка |
|
||||
|--------|-----|-----|--------|
|
||||
| **Версия** | 1 | 2 | — |
|
||||
| **Фазы** | 4 (proposal→specs→design→tasks) | 5 (+apply) | ✅ |
|
||||
| **Artifact boundaries** | Общие запреты | Структурированные MUST NOT include для каждой фазы | ✅✅ |
|
||||
| **Approval gates** | Неявные («только после approval») | Explicit approval + verify script для каждой фазы | ✅✅ |
|
||||
| **Invalidation** | Нет | Downstream approvals инвалидируются при mismatch | ✅✅ |
|
||||
| **Feedback routing** | Нет | Чёткое указание: intent→Proposal, behavior→Specs, architecture→Design, decomposition→Tasks | ✅✅ |
|
||||
| **Verify script** | Нет | `verify-openspec-planning.sh <change>` на каждой фазе | ✅ |
|
||||
| **Spec examples** | Только ADDED | Все 4 операции (ADDED, MODIFIED, REMOVED, RENAMED) | ✅ |
|
||||
| **Traceability** | Нет | `Covers: capability-path — exact Requirement heading` | ✅✅ |
|
||||
| **Task owner** | Нет | `[frontend\|backend\|specs\|docs\|workspace]` | ✅ |
|
||||
| **Rollback** | Generic Migration Plan | Rollback Contract с conditional required/N/A | ✅✅ |
|
||||
|
||||
### 2.2. Design.md — Rollback Contract
|
||||
|
||||
В v1 Migration Plan был generic. В v2 добавлена структурированная таблица:
|
||||
- `Status`: `required` или `N/A`
|
||||
- `Trigger`, `Actions`, `Data safety`, `Verification` — обязательны при `required`
|
||||
- `Reason` — обязателен при `N/A`
|
||||
|
||||
Это превращает rollback из «пожелания» в «контракт».
|
||||
|
||||
### 2.3. Tasks.md — Traceability + Ownership
|
||||
|
||||
В v1 задачи были plain text. В v2:
|
||||
- **Owner area**: `[frontend]`, `[backend]`, `[specs]`, `[docs]`, `[workspace]`
|
||||
- **Covers**: явная ссылка `capability-path — exact Requirement heading`
|
||||
- **N/A rationale**: для `workspace` tasks — обязательное обоснование, почему нет spec-ссылки
|
||||
- **Verification**: осталась, но теперь в строгом формате
|
||||
|
||||
### 2.4. Apply phase — новая фаза
|
||||
|
||||
В v1 apply был неявным. В v2 — explicit phase:
|
||||
- Требует approvals **всех 4 предыдущих фаз**
|
||||
- Работает только с canonical store
|
||||
- Feedback routing при mismatch
|
||||
- Трекинг через checkbox'ы tasks.md
|
||||
|
||||
---
|
||||
|
||||
## 3. Какие рекомендации из v1-анализа учтены
|
||||
|
||||
### ✅ Рекомендация #2: Traceability (specs → tasks)
|
||||
**Реализация:** `Covers` metadata в tasks.md
|
||||
**Качество:** Отлично. Не просто convention, а обязательный формат. Каждый Delta Requirement должен быть покрыт хотя бы одной task. Собственные requirement IDs не вводятся — защита от «фантомных» требований.
|
||||
|
||||
### ✅ Рекомендация #3: Полный spec template с examples
|
||||
**Реализация:** Compact operation examples в schema.yaml instruction
|
||||
**Качество:** Хорошо. Все 4 операции (ADDED, MODIFIED, REMOVED, RENAMED) с примерами. Небольшой минус: template-файл `spec.md` всё ещё содержит только ADDED, но AI-агент читает instruction из schema.yaml, так что это компенсируется.
|
||||
|
||||
### ✅ Рекомендация #7: Rollback Plan
|
||||
**Реализация:** Rollback Contract в design.md + conditional logic в schema.yaml
|
||||
**Качество:** Отлично. Не просто секция, а structured table с обязательностью полей, зависящей от типа change. `required` для auth/security/migration/public contract, `N/A` с reason для остального.
|
||||
|
||||
### ✅ Рекомендация #1: Review gate (частично)
|
||||
**Реализация:** Explicit approval из разговора + `verify-openspec-planning.sh` + «structural success ≠ approval»
|
||||
**Качество:** Хорошо, но иначе, чем предлагалось. Вместо отдельного `review.md` — approval + verify script. Это меньше артефактов, но тот же контроль. Потенциальный риск: AI-агент может «считать», что approval получен, если не строго интерпретировать «explicit approval из разговора». Но verify script добавляет технический барьер.
|
||||
|
||||
### ⚠️ Рекомендация #4: Definition of Done
|
||||
**Статус:** Не реализовано.
|
||||
**Комментарий:** Apply phase частично закрывает этот gap (требует approvals всех фаз + verification), но нет единого артефакта `done.md` с completion evidence.
|
||||
|
||||
### ❌ Рекомендация #5: Зависимости между changes
|
||||
**Статус:** Не реализовано.
|
||||
**Комментарий:** В multi-repo с shared store это всё ещё риск. Но для pet-проекта — приемлемо.
|
||||
|
||||
### ❌ Рекомендация #6: Sizing задач
|
||||
**Статус:** Не реализовано.
|
||||
**Комментарий:** Для AI-агента полезно, но не критично.
|
||||
|
||||
### ❌ Рекомендация #8: Context mapping
|
||||
**Статус:** Не реализовано.
|
||||
**Комментарий:** Apply phase говорит «Read context files», но не указывает, какие именно. В multi-repo setup это может привести к переполнению контекста.
|
||||
|
||||
### ❌ Рекомендация #9: Convention для commit messages
|
||||
**Статус:** Не реализовано.
|
||||
**Комментарий:** Nice to have.
|
||||
|
||||
---
|
||||
|
||||
## 4. Новые сильные моменты (не были в рекомендациях)
|
||||
|
||||
### 4.1. Artifact Boundaries
|
||||
|
||||
В каждой фазе теперь явный список **MUST NOT include**:
|
||||
- Proposal не может содержать технологии, API signatures, task decomposition
|
||||
- Specs не может содержать intent вне утверждённого Proposal, internal components, test procedures
|
||||
- Design не может содержать новое observable behavior, пересказ Specs, future commit identifiers
|
||||
- Tasks не может содержать новое behavior, архитектурные отклонения, vague actions
|
||||
|
||||
Это **scope creep protection** на уровне инструкций. AI-агент, следуя этим границам, физически не сможет «подсунуть» решение на неправильной фазе.
|
||||
|
||||
### 4.2. Feedback Routing + Invalidation
|
||||
|
||||
В apply phase:
|
||||
|
||||
intent/scope mismatch → Proposal
|
||||
observable behavior mismatch → Delta Specs
|
||||
architecture/rollback mismatch → Design
|
||||
decomposition/ownership/coverage mismatch → Tasks
|
||||
|
||||
|
||||
При обнаружении mismatch — **остановить downstream work, инвалидировать approvals начиная с самого раннего затронутого artifact**.
|
||||
|
||||
Это **каскадная защита**: если на этапе apply обнаружилось, что Design несовместим с Specs, не пытаться «подправить» Tasks — вернуться к Specs и начать заново.
|
||||
|
||||
### 4.3. Structural vs Semantic Validation
|
||||
|
||||
Явное разделение:
|
||||
- **Structural validation**: `verify-openspec-planning.sh` — проверяет формат, headers, completeness
|
||||
- **Semantic verification**: approval Change Owner — проверяет смысл
|
||||
|
||||
«Structural success не означает approval Change Owner» — критически важное различие для AI-агента.
|
||||
|
||||
### 4.4. Workspace Owner
|
||||
|
||||
`[workspace]` — отдельный owner для cross-area orchestration/verification. Защищает от смешивания implementation и orchestration в одной задаче. `N/A` Covers с concrete reason — защита от «пустых» workspace tasks.
|
||||
|
||||
---
|
||||
|
||||
## 5. Оставшиеся риски
|
||||
|
||||
### 5.1. Нет Definition of Done
|
||||
|
||||
Apply phase требует approvals, но не фиксирует **completion evidence** в виде артефакта. Нет единого места, где собраны:
|
||||
- результаты всех verification actions
|
||||
- proof of regression check
|
||||
- confirmation of archive
|
||||
|
||||
**Mitigation:** Tasks.md с checkbox'ами частично играет эту роль, но это tracking, не evidence.
|
||||
|
||||
### 5.2. Нет управления зависимостями между changes
|
||||
|
||||
В shared specs store может возникнуть ситуация:
|
||||
- Change A модифицирует capability X
|
||||
- Change B зависит от нового behavior X
|
||||
|
||||
Сейчас это не выразимо в схеме. Риск параллельной работы над конфликтующими changes.
|
||||
|
||||
**Mitigation:** Для pet-проекта — ручной контроль. Для роста — добавить `Dependencies` в proposal.md.
|
||||
|
||||
### 5.3. Context mapping для multi-repo
|
||||
|
||||
Apply phase: «Read context files». Но какие? Все репозитории? Только affected? AI-агент может:
|
||||
- Читать лишнее → переполнение контекста
|
||||
- Пропускать релевантное → решения на неполных данных
|
||||
|
||||
**Mitigation:** Для pet-проекта — manageable. Для роста — `.openspec/context.yaml` с `relevant_paths`.
|
||||
|
||||
### 5.4. Spec.md template всё ещё неполный
|
||||
|
||||
Template-файл `spec.md` содержит только `## ADDED Requirements`. Examples для MODIFIED/REMOVED/RENAMED есть в schema.yaml instruction, но template — это то, что AI «видит» первым. Риск неправильного формата при генерации.
|
||||
|
||||
**Mitigation:** Низкий — AI читает instruction перед template (в зависимости от реализации агента).
|
||||
|
||||
---
|
||||
|
||||
## 6. Итоговая таблица оценок v2
|
||||
|
||||
| Критерий | v1 | v2 | Δ | Комментарий |
|
||||
|----------|-----|-----|---|-------------|
|
||||
| **Разделение concerns** | A | A | → | Границы стали явными (Artifact boundaries) |
|
||||
| **Проверяемость specs** | A | A | → | Examples для всех 4 операций |
|
||||
| **Защита от деградации** | B+ | A− | ↑↑ | Approval gates + verify + invalidation |
|
||||
| **Traceability** | C+ | A | ↑↑↑ | Covers с capability-path + exact Requirement |
|
||||
| **Полнота workflow** | B | B+ | ↑ | +apply phase + rollback contract |
|
||||
| **AI-агент friendliness** | A | A+ | ↑ | Feedback routing + artifact boundaries |
|
||||
| **Интеграция с openspec** | A− | A | ↑ | Store-aware + verify script |
|
||||
| **Multi-repo поддержка** | B | B+ | ↑ | Workspace owner + cross-area orchestration |
|
||||
| **Эволюционность** | B+ | A− | ↑↑ | Invalidation + 4 delta-ops |
|
||||
| **Документированность** | A | A+ | ↑ | Artifact boundaries + structured examples |
|
||||
|
||||
---
|
||||
|
||||
## 7. Заключение
|
||||
|
||||
**v2 — качественный скачок.** Основные болевые точки v1 закрыты:
|
||||
|
||||
- ✅ Traceability: `Covers` связывает tasks и specs
|
||||
- ✅ Rollback: `Rollback Contract` делает откат предсказуемым
|
||||
- ✅ Scope creep protection: `Artifact boundaries` на каждой фазе
|
||||
- ✅ Каскадная защита: `Feedback routing` + `invalidation`
|
||||
- ✅ Approval discipline: explicit approvals + verify script + structural≠semantic
|
||||
|
||||
**Что делает схему зрелой:**
|
||||
1. **Self-correcting**: при mismatch есть чёткий путь назад (feedback routing)
|
||||
2. **Self-documenting**: artifact boundaries делают границы очевидными
|
||||
3. **Self-validating**: verify script + approval gates создают контрольные точки
|
||||
|
||||
**Что можно добавить в v3 (по мере роста проекта):**
|
||||
1. `done.md` — Definition of Done с completion evidence
|
||||
2. `Dependencies` в proposal.md — для cross-change coordination
|
||||
3. `.openspec/context.yaml` — для точного контекста в multi-repo
|
||||
4. Sizing (`S/M/L`) в tasks — для планирования сессий
|
||||
|
||||
**Вердикт:** Схема готова к использованию в pet-проекте любой сложности и может масштабироваться на small-team setup без существенных изменений.
|
||||
|
||||
---
|
||||
|
||||
## 8. План доработок v2 → v3 (чеклист)
|
||||
|
||||
> Скопируй этот раздел в отдельный файл и отмечай прогресс.
|
||||
|
||||
### 8.1. Definition of Done (`done.md`)
|
||||
|
||||
- [ ] Добавить артефакт `done.md` в `schema.yaml`
|
||||
- [ ] Создать template `done.md` с секциями:
|
||||
- Completion Evidence (verification results)
|
||||
- Regression Check
|
||||
- Archive Confirmation
|
||||
- [ ] Обновить `apply` phase: `requires: [tasks, done]`
|
||||
|
||||
### 8.2. Зависимости между changes
|
||||
|
||||
- [ ] Добавить в `proposal.md` template секцию `## Dependencies`
|
||||
- [ ] Поля: `Blocked By`, `Blocks`, `Related`
|
||||
- [ ] В `schema.yaml` добавить валидацию: проверять, что `Blocked By` changes завершены
|
||||
|
||||
### 8.3. Context mapping для multi-repo
|
||||
|
||||
- [ ] Создать `.openspec/context.yaml` в корне workspace
|
||||
- [ ] Маппинг: `repo name → path → relevant_paths → ignore_paths`
|
||||
- [ ] Обновить `apply` instruction: читать context mapping перед `Read context files`
|
||||
|
||||
### 8.4. Sizing задач
|
||||
|
||||
- [ ] Добавить в `tasks.md` template поле `**Size:** S/M/L/XL`
|
||||
- [ ] В `schema.yaml` instruction для tasks добавить правило sizing
|
||||
- [ ] Определить границы: S≤1ч, M=2-4ч, L=1-2д, XL=декомпозировать
|
||||
|
||||
### 8.5. Commit convention
|
||||
|
||||
- [ ] Добавить в `schema.yaml` apply instruction:
|
||||
- Формат: `[openspec:<change-id>] <type>: <description>`
|
||||
- Примеры для spec-commits и code-commits
|
||||
- `Refs:` ссылка на change artifact
|
||||
|
||||
### 8.6. Spec.md template — полная версия
|
||||
|
||||
- [ ] Обновить `spec.md` template: добавить `## MODIFIED`, `## REMOVED`, `## RENAMED` с placeholder'ами
|
||||
- [ ] Убедиться, что AI-агент генерирует все 4 операции корректно
|
||||
|
||||
---
|
||||
|
||||
## 9. 100-балльная оценка v2
|
||||
|
||||
| Критерий | Вес | Баллы | Почему не максимум |
|
||||
|----------|-----|-------|-------------------|
|
||||
| **Разделение concerns** | 15 | 14 | spec.md template неполный |
|
||||
| **Проверяемость specs** | 15 | 14 | verify script — внешний инструмент |
|
||||
| **Защита от деградации** | 15 | 14 | approval «из разговора» — нет механического proof |
|
||||
| **Traceability** | 10 | **10** | Полная |
|
||||
| **Полнота workflow** | 10 | 8 | Нет DoD, нет зависимостей |
|
||||
| **AI-агент friendliness** | 10 | **10** | Отлично |
|
||||
| **Интеграция с openspec** | 10 | 9 | Нет commit convention |
|
||||
| **Multi-repo поддержка** | 10 | 7 | Нет context mapping |
|
||||
| **Эволюционность** | 5 | **5** | Полная |
|
||||
|
||||
**Итого: 91 / 100**
|
||||
|
||||
---
|
||||
|
||||
*Анализ подготовлен на основе сравнения v1 и v2 файлов: schema.yaml, proposal.md, spec.md, design.md, tasks.md*
|
||||
Reference in New Issue
Block a user