docs: record second OpenSpec schema review
This commit is contained in:
@@ -0,0 +1,278 @@
|
||||
# Оценка OpenSpec-схемы `wealth-ledger-sdd` (v2)
|
||||
|
||||
**Дата:** 2025-08-25
|
||||
**Схема:** `wealth-ledger-sdd` version 2
|
||||
**Контекст:** multi-repo pet-проекты, выделенный specs-store (`wealth-ledger-specs`), AI-агент с доступом ко всем репозиториям, SDD через OpenSpec.
|
||||
|
||||
---
|
||||
|
||||
## 1. Краткий вердикт
|
||||
|
||||
| Метрика | Оценка |
|
||||
|--------|--------|
|
||||
| Общая зрелость | **9.2 / 10** |
|
||||
| Соответствие multi-repo + AI-агенту | Отличное |
|
||||
| Дисциплина границ артефактов | Отличная |
|
||||
| Практичность для ledger/финансов | Высокая |
|
||||
| Поддерживаемость instructions | Средняя (главный риск) |
|
||||
| Сравнение со стандартным `spec-driven` | Существенно сильнее |
|
||||
|
||||
Версия 2 — заметный шаг вперёд относительно v1. Вы закрыли почти все критические замечания предыдущей оценки и добавили механизмы, которые реально нужны в multi-repo + agent setup: **Artifact boundary**, **Covers → Requirement traceability**, **Rollback Contract**, **verify-скрипт на каждой стадии**, **Feedback routing** и явные owner-approvals.
|
||||
|
||||
Это уже не «кастомный fork», а production-grade internal engineering workflow.
|
||||
|
||||
---
|
||||
|
||||
## 2. Что изменилось с v1 → v2 (ключевые улучшения)
|
||||
|
||||
### 2.1. Artifact boundary (MUST NOT include)
|
||||
|
||||
В каждой инструкции теперь явно перечислено, чего **нельзя** писать в данном артефакте, и куда возвращаться, если агент «вылез» за границу:
|
||||
|
||||
| Артефакт | Запрещено | Куда возвращаться |
|
||||
|----------|-----------|-------------------|
|
||||
| Proposal | технологии, API, файлы, implementation steps | — |
|
||||
| Specs | intent вне Proposal, internal names, libraries, test procedures | Proposal |
|
||||
| Design | новое behavior, file-by-file checklist, commit IDs | Specs |
|
||||
| Tasks | новое behavior/architecture, multi-owner задачи, ненаблюдаемые results | Specs / Design |
|
||||
|
||||
Это решает главную болезнь AI-агентов — смешивание Why/What/How/Do.
|
||||
|
||||
### 2.2. Rollback Contract в Design
|
||||
|
||||
Добавлена обязательная таблица внутри Migration Plan:
|
||||
|
||||
```
|
||||
Status | Reason | Trigger | Actions | Data safety | Verification
|
||||
```
|
||||
|
||||
`required` для auth/security, data integrity/migration, public contracts и других труднообратимых решений. Для ledger-системы это критично.
|
||||
|
||||
### 2.3. Tasks: area + Covers + Verification
|
||||
|
||||
Формат задачи стал строгим:
|
||||
|
||||
```markdown
|
||||
- [ ] 1.1 [backend] Implement session rejection
|
||||
- **Covers:** `user-authentication` — `Expired session is rejected`
|
||||
- **Verification:** Run the backend canonical gate and the expiry contract test.
|
||||
```
|
||||
|
||||
- Ровно один owner из `{frontend, backend, specs, docs, workspace}`
|
||||
- Каждый Delta Requirement должен быть покрыт ≥1 task
|
||||
- `workspace` только для orchestration/verification
|
||||
- Пустые commits запрещены
|
||||
|
||||
Это даёт **traceability Requirement → Task** и делает apply-фазу проверяемой.
|
||||
|
||||
### 2.4. Structural verifier на каждой стадии
|
||||
|
||||
После записи каждого артефакта:
|
||||
|
||||
```bash
|
||||
bash specs/scripts/verify-openspec-planning.sh <change>
|
||||
```
|
||||
|
||||
Плюс явные owner-approvals перед переходом дальше. Structural success ≠ semantic approval.
|
||||
|
||||
### 2.5. Apply: Feedback routing + invalidation
|
||||
|
||||
```
|
||||
intent/scope mismatch → Proposal
|
||||
observable behavior mismatch → Delta Specs
|
||||
architecture/rollback mismatch → Design
|
||||
decomposition/ownership/coverage mismatch → Tasks
|
||||
```
|
||||
|
||||
Агент обязан остановить downstream work и инвалидировать approvals начиная с самого раннего затронутого артефакта. Механические syntax-фиксы можно чинить без reapproval.
|
||||
|
||||
### 2.6. Templates стали точнее
|
||||
|
||||
- `design.md` — Rollback Contract table
|
||||
- `tasks.md` — `[area]`, **Covers**, **Verification**
|
||||
- Остальные шаблоны сохранены минималистичными (нагрузка в instructions)
|
||||
|
||||
---
|
||||
|
||||
## 3. Сильные стороны (сохранились и усилились)
|
||||
|
||||
1. **Capabilities как контракт** между Proposal и Specs + `skip_specs: true` для pure refactor.
|
||||
2. **Строгий порядок** proposal → specs → design → tasks (не parallel design).
|
||||
3. **Delivery Map** (frontend / backend / specs / docs) + Contract Gate `runtime-openapi`.
|
||||
4. **Solution Assessment** (build-vs-buy) на auth/security/storage/integration/caching/concurrency.
|
||||
5. **Canonical store** `wealth-ledger-specs` + запрет parallel planning root.
|
||||
6. **SHALL/MUST + #### Scenario** + полный copy-paste workflow для MODIFIED.
|
||||
7. **Purpose ≥ 50 символов** для новых capabilities (защита от TBD после archive).
|
||||
|
||||
---
|
||||
|
||||
## 4. Сравнение со стандартным OpenSpec `spec-driven`
|
||||
|
||||
| Аспект | Стандартный | wealth-ledger-sdd v2 |
|
||||
|--------|-------------|----------------------|
|
||||
| Порядок | proposal → (specs ∥ design) → tasks | proposal → specs → design → tasks |
|
||||
| Границы артефактов | слабые | Artifact boundary + Feedback routing |
|
||||
| Traceability | почти нет | Covers → Requirement |
|
||||
| Multi-repo | нет | Delivery Map + area + workspace + store |
|
||||
| Rollback | опционально | Rollback Contract table |
|
||||
| Approvals | нет | explicit owner approval на каждой стадии |
|
||||
| Verify | нет / слабый | verify-openspec-planning.sh после каждого артефакта |
|
||||
| Apply discipline | базовая | Feedback routing + invalidation rules |
|
||||
|
||||
Для финансового/ledger-домена и multi-repo setup ваша схема объективно лучше дефолтной.
|
||||
|
||||
---
|
||||
|
||||
## 5. Оставшиеся риски и слабые места
|
||||
|
||||
### 5.1. Длина и плотность instructions (главный риск)
|
||||
|
||||
`schema.yaml` ≈ 18.5 KB / 349 строк. Критические правила размазаны по длинным абзацам на смеси RU/EN.
|
||||
|
||||
Риски:
|
||||
- Агент «пропускает» пункт в середине instruction.
|
||||
- Сложно diff’ить и поддерживать.
|
||||
- При смене модели качество следования может упасть.
|
||||
|
||||
### 5.2. Delivery Map жёстко фиксирует 4 области
|
||||
|
||||
`frontend / backend / specs / docs` (+ `workspace` в tasks).
|
||||
При появлении mobile, workers, data-pipelines, infra-as-code придётся расширять схему.
|
||||
|
||||
### 5.3. Approval — только в тексте instruction
|
||||
|
||||
Нет машиночитаемого статуса (`Approved-by`, `Approved-at`) в артефактах. Агент может «забыть» спросить approval, если prompt длинный.
|
||||
|
||||
### 5.4. Нет отдельной verify / archive кастомизации
|
||||
|
||||
Apply есть, а явной post-apply verify-фазы или правил archive (особенно для денежных миграций) — нет. Скрипт `verify-openspec-planning.sh` покрывает structural, но не semantic/runtime.
|
||||
|
||||
### 5.5. Templates всё ещё минималистичны
|
||||
|
||||
Почти вся дисциплина живёт в instructions. При fork/обновлении OpenSpec или смене модели это может стать хрупким.
|
||||
|
||||
### 5.6. Строгая последовательность specs → design
|
||||
|
||||
Повышает качество, но замедляет exploratory-работу, когда нужно быстро проверить техническую feasibility до фиксации behavior.
|
||||
|
||||
---
|
||||
|
||||
## 6. Предложения по улучшению
|
||||
|
||||
### Высокий приоритет
|
||||
|
||||
**1. Структурировать instructions: Critical Rules сверху**
|
||||
|
||||
В начале каждой instruction добавить короткий блок:
|
||||
|
||||
```yaml
|
||||
instruction: |
|
||||
## Critical Rules (do not skip)
|
||||
- ...
|
||||
- ...
|
||||
|
||||
## Details
|
||||
...
|
||||
```
|
||||
|
||||
Вынести:
|
||||
- Artifact boundary (MUST NOT)
|
||||
- Required sections / format
|
||||
- Когда остановиться и вернуться назад
|
||||
- Вызов verify-скрипта
|
||||
|
||||
Остальной текст — ниже. Это резко повышает шанс, что модель не пропустит важное.
|
||||
|
||||
**2. Машиночитаемый approval marker**
|
||||
|
||||
В конец каждого артефакта (или в `.openspec.yaml` change) добавить:
|
||||
|
||||
```markdown
|
||||
## Approval
|
||||
- Status: pending | approved | invalidated
|
||||
- By: <owner>
|
||||
- At: <ISO datetime>
|
||||
- Notes: ...
|
||||
```
|
||||
|
||||
Или хотя бы требовать в instruction явную строку `Approved-by: ...` перед переходом дальше. Тогда verify-скрипт сможет проверять наличие approval.
|
||||
|
||||
**3. Сделать Delivery Map расширяемым**
|
||||
|
||||
Разрешить дополнительные rows с обоснованием:
|
||||
|
||||
```markdown
|
||||
| mobile | affected | ... |
|
||||
| workers | N/A | no background jobs in this change |
|
||||
```
|
||||
|
||||
Сейчас «ровно frontend, backend, specs и docs» — хрупко.
|
||||
|
||||
### Средний приоритет
|
||||
|
||||
**4. Унифицировать язык**
|
||||
|
||||
Либо полностью русский, либо английский с русскими комментариями только в Critical Rules. Сейчас смесь усложняет и человеку, и модели.
|
||||
|
||||
**5. Лёгкая verify-фаза после tasks (опционально)**
|
||||
|
||||
Даже не отдельный artifact, а секция в apply или отдельный checklist:
|
||||
|
||||
- все local gates зелёные;
|
||||
- Covers 100% покрыты;
|
||||
- Rollback Contract (если required) проверен;
|
||||
- Completion Evidence зафиксирован.
|
||||
|
||||
**6. Solution Assessment как условный артефакт**
|
||||
|
||||
Сейчас секция внутри design. При частых build-vs-buy решениях удобнее отдельный `solution-assessment.md` (requires: specs), чтобы его можно было переиспользовать и ревьюить отдельно.
|
||||
|
||||
**7. Явный rule для cross-repo verification**
|
||||
|
||||
В tasks уже есть `workspace`. Стоит добавить в Critical Rules:
|
||||
|
||||
> После всех affected areas — одна `workspace`-задача на semantic review против каждого approved Requirement/Scenario.
|
||||
|
||||
### Низкий приоритет / nicety
|
||||
|
||||
**8. Success Metrics / Observable Outcomes в Proposal**
|
||||
|
||||
1–3 пункта «как поймём, что изменение достигло цели». Помогает писать scenarios и Acceptance в apply.
|
||||
|
||||
**9. Сократить примеры в instructions**
|
||||
|
||||
Сейчас примеры (особенно в specs) занимают много места. Можно вынести в отдельный `examples/` или оставить только один компактный.
|
||||
|
||||
**10. Versioning schema + changelog**
|
||||
|
||||
У вас уже `version: 2`. Имеет смысл вести короткий CHANGELOG рядом со schema, чтобы при обновлении агента/команды было видно, что изменилось в дисциплине.
|
||||
|
||||
---
|
||||
|
||||
## 7. Рекомендуемый минимальный diff (идеи, не патч)
|
||||
|
||||
1. В каждый artifact instruction добавить в самое начало блок `## Critical Rules`.
|
||||
2. В templates `proposal.md`, `spec.md`, `design.md`, `tasks.md` добавить в конец:
|
||||
|
||||
```markdown
|
||||
## Approval
|
||||
- Status: pending
|
||||
- By:
|
||||
- At:
|
||||
```
|
||||
|
||||
3. В Delivery Map instruction заменить «ровно frontend, backend, specs и docs» на «обязательные: frontend, backend, specs, docs; дополнительные области — с обоснованием».
|
||||
4. В apply instruction оставить Feedback routing, но вынести его в Critical Rules.
|
||||
|
||||
Эти четыре изменения дадут максимум пользы при минимальном усложнении.
|
||||
|
||||
---
|
||||
|
||||
## 8. Итог
|
||||
|
||||
**v2 — сильная, зрелая схема.**
|
||||
Вы закрыли основные дыры v1 (границы артефактов, rollback, traceability Requirement→Task, structural verify, feedback routing). Для multi-repo ledger-проекта с AI-агентом это один из лучших кастомных OpenSpec workflow, которые можно собрать на текущем API схем.
|
||||
|
||||
Главный оставшийся рычаг улучшения — **не добавлять ещё правил, а сделать существующие правила короче, заметнее и машиночитаемее** (Critical Rules сверху + approval markers + расширяемый Delivery Map).
|
||||
|
||||
После этих точечных правок схема спокойно может жить как внутренний стандарт без постоянных переделок.
|
||||
Reference in New Issue
Block a user