14 KiB
Оценка 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
Формат задачи стал строгим:
- [ ] 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 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 tabletasks.md—[area], Covers, Verification- Остальные шаблоны сохранены минималистичными (нагрузка в instructions)
3. Сильные стороны (сохранились и усилились)
- Capabilities как контракт между Proposal и Specs +
skip_specs: trueдля pure refactor. - Строгий порядок proposal → specs → design → tasks (не parallel design).
- Delivery Map (frontend / backend / specs / docs) + Contract Gate
runtime-openapi. - Solution Assessment (build-vs-buy) на auth/security/storage/integration/caching/concurrency.
- Canonical store
wealth-ledger-specs+ запрет parallel planning root. - SHALL/MUST + #### Scenario + полный copy-paste workflow для MODIFIED.
- 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 добавить короткий блок:
instruction: |
## Critical Rules (do not skip)
- ...
- ...
## Details
...
Вынести:
- Artifact boundary (MUST NOT)
- Required sections / format
- Когда остановиться и вернуться назад
- Вызов verify-скрипта
Остальной текст — ниже. Это резко повышает шанс, что модель не пропустит важное.
2. Машиночитаемый approval marker
В конец каждого артефакта (или в .openspec.yaml change) добавить:
## Approval
- Status: pending | approved | invalidated
- By: <owner>
- At: <ISO datetime>
- Notes: ...
Или хотя бы требовать в instruction явную строку Approved-by: ... перед переходом дальше. Тогда verify-скрипт сможет проверять наличие approval.
3. Сделать Delivery Map расширяемым
Разрешить дополнительные rows с обоснованием:
| 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 (идеи, не патч)
- В каждый artifact instruction добавить в самое начало блок
## Critical Rules. - В templates
proposal.md,spec.md,design.md,tasks.mdдобавить в конец:
## Approval
- Status: pending
- By:
- At:
- В Delivery Map instruction заменить «ровно frontend, backend, specs и docs» на «обязательные: frontend, backend, specs, docs; дополнительные области — с обоснованием».
- В 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).
После этих точечных правок схема спокойно может жить как внутренний стандарт без постоянных переделок.