docs: record SDD audit remediation
This commit is contained in:
@@ -4,16 +4,36 @@ status: accepted
|
||||
|
||||
# Native OpenSpec SDD и минимальная local orchestration
|
||||
|
||||
WealthLedger использует project-local schema `wealth-ledger-sdd` OpenSpec 1.10 с последовательностью `Proposal → Delta Specs → Design → Tasks → Apply` и тонкий dispatcher существующих repository gates. Это сохраняет один lifecycle authority в `specs/openspec`, выражает проектные approval boundaries нативными extension points и не вводит второй workflow engine или monorepo control plane для четырёх независимых Git-репозиториев.
|
||||
WealthLedger использует project-local schema `wealth-ledger-sdd` version 2 с
|
||||
последовательностью `Proposal → Delta Specs → Design → Tasks → Apply`, один exact
|
||||
OpenSpec CLI contract из `.cli-version` и тонкие non-mutating verifiers. Это
|
||||
сохраняет один lifecycle authority в `specs/openspec`, выражает approval
|
||||
boundaries нативными extension points и не вводит второй workflow engine или
|
||||
monorepo control plane для четырёх независимых Git-репозиториев.
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
- Встроенная `spec-driven` schema отклонена: она не выражает обязательный переход Specs перед Design и не задаёт Delivery Map или проектные роли артефактов.
|
||||
- Отдельный workflow engine или custom generator отклонён: он создал бы конкурирующий формат и lifecycle authority.
|
||||
- Nx, Turborepo, Bazel, Make или just отклонены для текущего масштаба: workspace не имеет общего dependency graph, build cache или CI, а репозитории уже владеют canonical gates.
|
||||
- Patch-only, programmatic generator и symlink для root agent projection
|
||||
отклонены из-за upstream text fragility, второго transformation engine либо
|
||||
tool/filesystem portability. Выбран committed canonical source tree с
|
||||
explicit atomic sync и exact drift check.
|
||||
|
||||
## Последствия
|
||||
|
||||
OpenSpec CLI закреплён exact version contract, а upgrade требует staged generation и проверки generated root `.opencode` projection. Dispatcher знает четыре workspace area, но не реализует build или test logic: он только валидирует Delivery Map и делегирует в repo-owned commands. Approval identity остаётся человеческим workflow constraint, потому что schema моделирует порядок артефактов, но не личность утвердившего.
|
||||
OpenSpec CLI закреплён exact version contract; новая stable release не включает
|
||||
auto-upgrade, а смена contract является отдельным SDD change со staged
|
||||
compatibility fixtures. Project-owned commands и skills имеют versioned source
|
||||
в `specs`, root `.opencode` является derived projection. Planning verifier до
|
||||
approval проверяет только детерминированную структуру: capability set, Delivery
|
||||
Map, rollback, task area и Requirement coverage.
|
||||
|
||||
Dispatcher знает четыре workspace area, но не реализует build или test logic:
|
||||
он делегирует repo-owned commands. Approval identity остаётся человеческим
|
||||
workflow constraint, потому что schema моделирует порядок артефактов, но не
|
||||
личность утвердившего. Semantic review по-прежнему не заменяется structural
|
||||
checks.
|
||||
|
||||
Решение пересматривается, если OpenSpec перестанет поддерживать нужный artifact graph, появится обязательный общий CI/build graph или стоимость последовательной локальной orchestration станет существенной. В этих случаях новый ADR сравнивает native evolution с внешним engine либо monorepo platform.
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Multi-source assessment схемы WealthLedger SDD
|
||||
|
||||
Дата фиксации snapshot: 2026-08-26.
|
||||
|
||||
Этот каталог — неизменяемый source snapshot пяти независимых внешних
|
||||
модельных оценок schema `wealth-ledger-sdd`. Отчёты содержат claims и
|
||||
рекомендации внешних моделей, но не являются authority проекта и не заменяют
|
||||
OpenSpec requirements, engineering governance, ADR или проверенное as-built
|
||||
состояние. Принятые решения и текущая remediation находятся только в
|
||||
[live registry](../../development/audit-remediation.md).
|
||||
|
||||
Исходные файлы перенесены byte-for-byte из unversioned workspace folder
|
||||
`sdd-audit`. До удаления исходной папки для каждого файла были сопоставлены
|
||||
byte count, `cmp` и SHA-256; все пять сравнений прошли.
|
||||
|
||||
| Source report | Bytes | SHA-256 |
|
||||
| --- | ---: | --- |
|
||||
| [DeepSeek](deepseek-result.md) | 19,319 | `2d50f4c195507ceb079d69489c03f1ea8a81185e2594dd51ff6a293ab8198db8` |
|
||||
| [Gemini](gemini-result.md) | 10,371 | `af95a4c208c993621a6c15102a1e26684eee6c2966b166f6ba23b600d0e33696` |
|
||||
| [Kimi](kimi-result.md) | 23,100 | `31d423903cde2d7c1feb711cc625c77864964bb66cfd0cacb734c5c6bbdddd17` |
|
||||
| [Qwen](qwen-result.md) | 11,035 | `1b6582efe55b7044d2bebc9c1a146df1963e4103c5517c259ccf617d6d2b4f14` |
|
||||
| [Z.AI](zai-result.md) | 8,391 | `0bdb7785087c8d1b6fe532d578804aa498bfc90935623d79c1003cd1899d5bad` |
|
||||
|
||||
Суммарный размер raw evidence: 72,216 bytes. Snapshot files не редактируются
|
||||
при изменении triage или remediation status; новый аудит создаёт новый каталог
|
||||
и обновляет тот же live registry.
|
||||
@@ -0,0 +1,178 @@
|
||||
# Анализ схемы Spec‑Driven Development (openspec) для pet‑проектов
|
||||
|
||||
## 1. Введение
|
||||
|
||||
Данный документ содержит оценку пользовательской схемы `schema.yaml`, предназначенной для организации процесса **Spec‑Driven Development (SDD)** с использованием фреймворка `openspec`. Схема описывает жизненный цикл изменения: от формулирования намерения (`proposal`) до реализации (`tasks`) и выполнения (`apply`). Анализ выполнен на основе предоставленных артефактов (`proposal.md`, `spec.md`, `design.md`, `tasks.md`) и самой схемы.
|
||||
|
||||
**Общая оценка:** схема **качественная, продуманная и функциональная**. Она соответствует лучшим практикам SDD, обеспечивает чёткое разделение уровней абстракции и поддерживает эволюционное развитие спецификаций. Однако присутствуют области, которые можно улучшить для повышения удобства работы, автоматизации и снижения когнитивной нагрузки на AI‑агента.
|
||||
|
||||
---
|
||||
|
||||
## 2. Сильные стороны схемы
|
||||
|
||||
- **Чёткое разделение артефактов**
|
||||
Каждый артефакт решает свою задачу:
|
||||
- `proposal` — *почему* и *что* (бизнес‑намерение);
|
||||
- `specs` — *какое наблюдаемое поведение* (контракт);
|
||||
- `design` — *как архитектурно* (решения);
|
||||
- `tasks` — *что конкретно сделать* (реализация).
|
||||
Это предотвращает смешивание уровней и упрощает коммуникацию между участниками.
|
||||
|
||||
- **Поведенческий фокус в спецификациях**
|
||||
Требования формулируются с использованием `SHALL/MUST` и сопровождаются сценариями в формате **WHEN‑THEN**, что делает их проверяемыми и независимыми от реализации.
|
||||
|
||||
- **Поддержка дельт**
|
||||
Операции `ADDED`, `MODIFIED`, `REMOVED` и `RENAMED` позволяют аккуратно эволюционировать существующие возможности, сохраняя историю изменений.
|
||||
|
||||
- **Учёт архитектурных решений**
|
||||
В `design` присутствуют обязательные разделы: `Delivery Map` (привязка к областям), `Contract Gate Decision` (для API), `Solution Assessment` (для сравнения готовых решений). Это способствует принятию обоснованных технических решений.
|
||||
|
||||
- **Практичные задачи**
|
||||
`tasks` разбиты на выполнимые шаги с указанием верификации (команды, наблюдаемые результаты). Задачи привязаны к областям из Delivery Map, что обеспечивает покрытие всех affected‑зон.
|
||||
|
||||
- **Интеграция с `openspec`**
|
||||
Использование `store`, `planningHome.root`, флага `skip_specs` и явной инструкции по архивации показывает глубокое понимание инструмента и его особенностей.
|
||||
|
||||
---
|
||||
|
||||
## 3. Замечания и области для улучшения
|
||||
|
||||
### 3.1. Избыточная детализация инструкций
|
||||
Инструкции для каждого артефакта содержат много пояснений (повторяющиеся правила, подробное описание `planningHome.root`, форматирования). Это усложняет восприятие AI и увеличивает вероятность ошибок при генерации.
|
||||
|
||||
**Риск:** AI может пропустить важное правило из‑за большого объёма текста.
|
||||
|
||||
### 3.2. Отсутствие машинной валидации формата
|
||||
Хотя инструкции описывают правильный синтаксис (например, ровно 4 `#` для сценариев), нет автоматической проверки на этапе генерации. AI может случайно отклониться от ожидаемого формата, и ошибка обнаружится только при валидации `openspec validate`.
|
||||
|
||||
**Риск:** увеличение итераций на исправление.
|
||||
|
||||
### 3.3. Недостаточная поддержка многокомпонентных изменений
|
||||
В схеме не указано, как обрабатывать изменения, затрагивающие **несколько репозиториев** (например, синхронизация API‑контрактов между бэкендом и фронтендом). Упоминается только `Delivery Map` с областями, но нет явных разделов для координации версий, порядка деплоя или обратной совместимости.
|
||||
|
||||
**Риск:** несогласованность при параллельной разработке.
|
||||
|
||||
### 3.4. Размытые критерии для `Solution Assessment`
|
||||
Требуется включать этот раздел, когда изменение вводит или существенно заменяет "дорогостоящее необратимое решение". Однако триггеры перечислены в скобках (auth, storage, external integration и т.п.), но они не формализованы. AI может пропустить необходимость анализа, если не распознает ситуацию.
|
||||
|
||||
**Риск:** принятие неоптимальных технических решений без сравнения альтернатив.
|
||||
|
||||
### 3.5. Отсутствие явного этапа утверждения спецификаций
|
||||
После создания `specs` нет артефакта или флага, обозначающего их утверждение владельцем (например, `status: draft | approved`). В `proposal` требуется утверждение, но для `specs` – нет. Это может привести к тому, что `design` будет писаться по неутверждённым требованиям.
|
||||
|
||||
**Риск:** переделки при изменении требований на поздних этапах.
|
||||
|
||||
### 3.6. Избыточность при модификации требований
|
||||
Инструкция требует копировать **полное** содержание существующего требования (включая все сценарии) в секцию `MODIFIED`. Это увеличивает объём дельты и риск рассинхронизации (например, если в исходном требовании позже появится изменение, а дельта этого не отразит). Хотя такой подход безопасен для архивации, он громоздкий.
|
||||
|
||||
**Риск:** ошибки копирования и потери изменений.
|
||||
|
||||
### 3.7. Отсутствие примеров для сложных сценариев
|
||||
В инструкции приведён только простой пример для нового требования. Нет примеров для `MODIFIED` (с полным копированием), для `RENAMED`, для `design` с заполненным `Solution Assessment` или для `tasks` с перекрёстными зависимостями.
|
||||
|
||||
**Риск:** AI может неправильно интерпретировать формат, особенно для модификаций.
|
||||
|
||||
### 3.8. Неполное описание процесса `apply`
|
||||
В секции `apply` указано "работать с pending tasks и отмечать выполненные", но не описаны завершающие шаги: проверка всех задач, запуск тестов, обновление документации, создание коммита/PR, архивация изменения в `openspec` store. Это оставляет пространство для неполного завершения.
|
||||
|
||||
**Риск:** незавершённые изменения, потерянные артефакты.
|
||||
|
||||
### 3.9. Слабая трассируемость между артефактами
|
||||
Хотя в `tasks` сказано "ссылаться на specs и design", нет явного механизма привязки задач к конкретным требованиям или архитектурным решениям. Например, не указано, какая задача реализует какой requirement.
|
||||
|
||||
**Риск:** сложно проверить полноту покрытия и проследить impact изменения.
|
||||
|
||||
---
|
||||
|
||||
## 4. Предложения по улучшению
|
||||
|
||||
### 4.1. Упростить инструкции, вынеся общие правила в отдельный файл
|
||||
- Создать `_rules.md` (или `.openspec-rules.md`) в корне проекта, где описать:
|
||||
- общие требования к форматированию;
|
||||
- правила работы с `planningHome.root`;
|
||||
- пояснения по `skip_specs` и дельта‑операциям.
|
||||
- В `schema.yaml` для каждого артефакта оставить только **специфичные** для него инструкции, ссылаясь на общие правила.
|
||||
|
||||
**Плюсы:** уменьшение объёма инструкций, снижение когнитивной нагрузки на AI, централизованное обновление правил.
|
||||
|
||||
### 4.2. Добавить машинную валидацию формата при генерации
|
||||
- Интегрировать проверку сгенерированных файлов через `openspec validate --strict` (или внешний валидатор) перед сохранением.
|
||||
- В инструкции добавить шаг: "После генерации выполни `openspec validate <change> --strict` и исправь ошибки".
|
||||
|
||||
**Плюсы:** автоматическое обнаружение синтаксических ошибок, сокращение циклов доработки.
|
||||
|
||||
### 4.3. Явно определить процесс для кросс‑репозиторных изменений
|
||||
- В `design` добавить раздел **Cross‑repo Dependencies**, где перечислять:
|
||||
- затронутые репозитории и их версии;
|
||||
- необходимый порядок деплоя;
|
||||
- требования к обратной совместимости (если применимо).
|
||||
- При необходимости создать отдельный артефакт `integration-plan.md`, который включается в change.
|
||||
|
||||
**Плюсы:** синхронизация разработки, снижение риска несовместимости.
|
||||
|
||||
### 4.4. Формализовать критерии для включения `Solution Assessment`
|
||||
- Сделать раздел обязательным для всех изменений, кроме тех, что помечены как `trivial` (например, исправление опечаток, рефакторинг без изменения поведения).
|
||||
- В инструкции перечислить **конкретные области**, требующие анализа, в виде чек‑листа:
|
||||
- [ ] Аутентификация/авторизация
|
||||
- [ ] Хранилище данных (схема, миграции)
|
||||
- [ ] Внешние интеграции (новые API, сторонние сервисы)
|
||||
- [ ] Кэширование
|
||||
- [ ] Конкурентность
|
||||
- [ ] Наблюдаемость (логи, метрики, трейсинг)
|
||||
- [ ] Инфраструктура (новые компоненты, изменение конфигурации)
|
||||
- Если ни один пункт не затронут, раздел можно пропустить с пометкой `N/A` и кратким обоснованием.
|
||||
|
||||
**Плюсы:** единообразие, предотвращение пропусков.
|
||||
|
||||
### 4.5. Добавить этап утверждения спецификаций
|
||||
- Ввести артефакт `approval.md` или поле `status` в начале каждого `spec.md` (например, `## Status: Draft | Approved`).
|
||||
- В цепочке зависимостей указать, что `design` может начинаться только после того, как все дельта‑спецификации помечены как `Approved` (владельцем продукта или техническим лидом).
|
||||
- Это можно реализовать через ручную проверку или через CI‑шаг, требующий комментария.
|
||||
|
||||
**Плюсы:** прозрачность, снижение риска переделок.
|
||||
|
||||
### 4.6. Оптимизировать модификацию требований (альтернатива копированию)
|
||||
- Вместо полного копирования разрешить указывать **изменения** в формате diff (например, с использованием маркеров `<<<` / `>>>` или просто явное описание изменений).
|
||||
- При архивации автоматически применять эти изменения к базовому `spec.md` с помощью скрипта слияния.
|
||||
- Однако это требует более сложной обработки. Если такой возможности нет, то сохранить текущий подход, но добавить рекомендацию использовать **внешние инструменты** для поиска и копирования (например, `openspec show`).
|
||||
|
||||
**Плюсы:** уменьшение дублирования, снижение ошибок.
|
||||
|
||||
### 4.7. Добавить примеры для всех типов дельт и сложных ситуаций
|
||||
- В инструкцию или в отдельный файл `_examples.md` включить примеры:
|
||||
- **MODIFIED** с полным копированием существующего требования и его изменением.
|
||||
- **RENAMED** с указанием FROM/TO.
|
||||
- **REMOVED** с Reason и Migration.
|
||||
- **design** с заполненным `Solution Assessment` (например, выбор между готовым и кастомным решением).
|
||||
- **tasks** с перекрёстными зависимостями между репозиториями.
|
||||
|
||||
**Плюсы:** уменьшение неоднозначности для AI, повышение качества генерируемых артефактов.
|
||||
|
||||
### 4.8. Дополнить процесс `apply` завершающими шагами
|
||||
- В секцию `apply` добавить:
|
||||
- После завершения всех задач: запустить полный набор тестов (CI‑пайплайн).
|
||||
- Проверить, что все артефакты соответствуют актуальному состоянию кода.
|
||||
- Создать коммит с изменениями в коде и обновлёнными спецификациями.
|
||||
- Выполнить `openspec archive <change>` для переноса дельт в основной `specs` store.
|
||||
- Удалить директорию изменения или обновить статус в системе отслеживания задач.
|
||||
|
||||
**Плюсы:** гарантированное завершение, предотвращение потери изменений.
|
||||
|
||||
### 4.9. Ввести трассируемость через мета‑данные в задачах
|
||||
- Добавить в каждую задачу поля (в виде комментариев или меток), например:
|
||||
- `implements: <requirement-id>` – ссылка на конкретное требование.
|
||||
- `related-to: <decision-id>` – ссылка на решение в design.
|
||||
- Это можно сделать через формат: `- [ ] 1.1 Implement export feature (implements: export-data, related: design#cache-decision)`
|
||||
- Или вынести в отдельную колонку, если используется система управления задачами.
|
||||
|
||||
**Плюсы:** прослеживаемость, упрощение ревью и аудита.
|
||||
|
||||
---
|
||||
|
||||
## 5. Заключение
|
||||
|
||||
Предоставленная схема является **надёжной и работоспособной** основой для SDD в pet‑проектах и даже в небольших командах. Она грамотно использует возможности `openspec` и обеспечивает дисциплину в разработке. Предложенные улучшения направлены на **снижение когнитивной нагрузки, повышение автоматизации и устранение потенциальных пробелов** при работе с несколькими репозиториями и сложными изменениями.
|
||||
|
||||
Рекомендуется внедрять улучшения поэтапно, начиная с наиболее критичных (например, добавление валидации и формализация `Solution Assessment`), а затем дорабатывать процесс по мере накопления опыта.
|
||||
|
||||
Данный анализ может быть использован как руководство по дальнейшему развитию вашей SDD‑системы.
|
||||
@@ -0,0 +1,117 @@
|
||||
# Анализ схемы Spec-Driven Development (wealth-ledger-sdd) и рекомендации по улучшению
|
||||
|
||||
## 1. Общий обзор и контекст
|
||||
|
||||
Представленная схема **wealth-ledger-sdd** реализует Spec-Driven Development (SDD) поверх фреймворка `openspec`. Конфигурация рассчитана на работу AI-агента из общей корневoй директории, объединяющей несколько отдельных репозиториев, с хранением спецификаций в изолированном хранилище (`openspec store`).
|
||||
|
||||
Пайплайн планирования состоит из 4 последовательных этапов:
|
||||
1. **Proposal** (`proposal.md`) — продуктовое и бизнес-обоснование («Зачем» и «Что меняется на верхнем уровне»).
|
||||
2. **Specs** (`specs/**/*.md`) — контракты наблюдаемого поведения системы («ЧТО система делает»).
|
||||
3. **Design** (`design.md`) — техническая архитектура и решения по реализации («КАК сделать»).
|
||||
4. **Tasks** (`tasks.md`) — атомарный чек-лист задач для выполнения («ЧТО СДЕЛАТЬ конкретно»).
|
||||
|
||||
---
|
||||
|
||||
## 2. Анализ сильных сторон (Strengths)
|
||||
|
||||
* **Строгая синтаксическая дисциплина для LLM:**
|
||||
Инструкции к артефакту `specs` содержат четкие предохранители против специфических багов генерации Markdown у AI-моделей (например, строго 4 хештега `#### Scenario:` и нормативные глаголы `SHALL`/`MUST`). Это гарантирует предсказуемый парсинг артефактов со стороны OpenSpec CLI.
|
||||
* **Изоляция планирования от продуктового кода:**
|
||||
Использование переменной `planningHome.root` гарантирует корректную работу с `wealth-ledger-specs` store. Репозитории сервисов не засоряются промежуточными черновиками и файлами планирования.
|
||||
* **Защита от избыточной работы (Build-vs-Buy Control):**
|
||||
Обязательный раздел `Solution Assessment` в `design.md` предотвращает попытки AI «изобретать велосипед» при добавлении авторизации, кеширования, интеграций или инфраструктурных утилит.
|
||||
* **Прагматичная стратегия тестирования:**
|
||||
Инструкция к `tasks.md` явно задает зоны, где тесты обязательны (финансы, безопасность, персистентность, публичные контракты), и запрещает избыточные unit-тесты для DTO, тонких адаптеров и декларативных структур.
|
||||
* **Четкое разделение ответственности между этапами:**
|
||||
Запрет на упоминание технологий в `proposal.md` предотвращает преждевременное принятие архитектурных решений до согласования целей бизнеса.
|
||||
|
||||
---
|
||||
|
||||
## 3. Анализ узких мест и рисков в мультирепозиторной среде
|
||||
|
||||
* **Неопределенность адресации файлов в мультирепо (File Path Ambiguity):**
|
||||
В текущих шаблонах `tasks.md` и `design.md` отсутствуют явные требования указывать имя репозитория. В рабочей директории с десятком сервисов задача вида `Modify user.service.ts` приведет к ошибкам адресации или поиску файла по всем подпапкам.
|
||||
* **Размытый фокус затронутых репозиториев на старте:**
|
||||
В `proposal.md` есть секция `Impact`, но нет явного списка целевых сервисов. Агент может не рассчитать требуемый контекст и пропустить смежный сервис на этапе проектирования контрактов.
|
||||
* **Высокий оверхед на мелкие изменения (Fast-Track overhead):**
|
||||
Полный 4-этапный цикл избыточен для локального рефакторинга или точечного багфикса. Хотя параметр `skip_specs: true` предусмотрен, генерация `design.md` и `proposal.md` для однострочных правок влечет лишние затраты токенов и времени.
|
||||
* **Риск раздувания контекстного окна (Context Window Bloat):**
|
||||
Запуск AI-агента из единого корня открывает ему доступ ко всему коду всех проектов. Без явных ограничений в промпте и конфигурации агент может считывать лишние репозитории, исчерпывая лимит контекста.
|
||||
|
||||
---
|
||||
|
||||
## 4. Предложения по улучшению (Improvement Proposals)
|
||||
|
||||
### 4.1. Внедрение явной мультирепозиторной адресации
|
||||
|
||||
#### А. Секция Target Repositories в `proposal.md`
|
||||
Добавьте в шаблон `proposal.md` секцию, фиксирующую список затронутых репозиториев:
|
||||
|
||||
```markdown
|
||||
## Target Repositories
|
||||
|
||||
<!-- Укажите репозитории, в которые будут вноситься изменения -->
|
||||
- `<repo-name>`: <роль репозитория в данном изменении>
|
||||
```
|
||||
|
||||
#### Б. Строгий формат задач в `tasks.md`
|
||||
Обновите инструкцию артефакта `tasks` в `schema.yaml`, обязывая AI указывать путь к репозиторию:
|
||||
|
||||
```yaml
|
||||
# В инструкции tasks в schema.yaml:
|
||||
- Каждая задача MUST указывать целевой репозиторий в формате: `- [ ] X.Y [<repo-folder>] <action>`
|
||||
```
|
||||
|
||||
Пример сгенерированной задачи:
|
||||
```markdown
|
||||
- [ ] 1.1 [auth-service] Add standard JWT validation middleware and verify auth test suite passes
|
||||
- [ ] 1.2 [frontend-app] Update API client DTO types to align with new contract
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2. Организация Fast-Track сценария для точечных правок
|
||||
|
||||
Для оптимизации работы над некрупными задачами рекомендуется предусмотреть ускоренный пайплайн.
|
||||
|
||||
1. **Если изменение не меняет внешнее поведение:**
|
||||
В `.openspec.yaml` устанавливается `skip_specs: true`.
|
||||
2. **Сокращенный Design:**
|
||||
В инструкцию `design` добавьте правило: если `Delivery Map` затрагивает только 1 репозиторий и `runtime-openapi` равен `N/A`, разделы `Solution Assessment` и `Migration Plan` можно опускать.
|
||||
|
||||
---
|
||||
|
||||
### 4.3. Усиление Contract Gate Decision
|
||||
|
||||
В мультирепозиторном окружении изменение контракта API в одном сервисе сразу требует обновления клиента в другом. Уточните таблицу `Contract Gate Decision` в `design.md`:
|
||||
|
||||
```markdown
|
||||
### Contract Gate Decision
|
||||
|
||||
| Gate | Status | Affected Repositories | Reason |
|
||||
| --- | --- | --- | --- |
|
||||
| runtime-openapi | `required` / `N/A` | `backend-api`, `frontend-web` | <!-- причины --> |
|
||||
| internal-proto | `required` / `N/A` | `billing-service`, `orders-service` | <!-- причины --> |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4. Оптимизация контекста AI-агента
|
||||
|
||||
При запуске агента из общего корня настройте файл `.aiignore` (или `.cursorignore` / `.windsurfignore` в зависимости от используемого CLI/IDE) в корневой папке:
|
||||
|
||||
1. Исключите тяжелые бинарники, папки сборки и зависимости (`**/node_modules`, `**/dist`, `**/target`, `**/.git`).
|
||||
2. Запретите агенту просматривать репозитории, не указанные в `Target Repositories` для текущей задачи.
|
||||
|
||||
---
|
||||
|
||||
## 5. Итоговая оценка качества схемы
|
||||
|
||||
| Критерий | Оценка (1-5) | Комментарий |
|
||||
| --- | --- | --- |
|
||||
| **LLM-friendly (предсказуемость)** | **5/5** | Отличные предохранители против сбоев синтаксиса и парсинга Markdown. |
|
||||
| **Архитектурная строгость** | **5/5** | Баланс между бизнес-целями, specs и архитектурным проектированием. |
|
||||
| **Мультирепозиторная адаптация** | **3.5/5** | Требует добавления явных указателей путей репозиториев в `tasks` и `proposal`. |
|
||||
| **Эффективность по скорости/токенам** | **4/5** | Отлично для фич, требует Fast-Track сценария для мелких правок. |
|
||||
|
||||
**Вердикт:** Схема находится на очень высоком уровне разработки. После внесения точечных правок по мультирепозиторной адресации и фильтрации контекста она станет эталонной для мультисервисной Spec-Driven разработки.
|
||||
@@ -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*
|
||||
@@ -0,0 +1,118 @@
|
||||
# Анализ и оценка кастомной схемы OpenSpec SDD (`wealth-ledger-sdd`)
|
||||
|
||||
## Общее резюме
|
||||
Ваша кастомная схема `wealth-ledger-sdd` — это **великолепный, глубоко проработанный артефакт**. Видно, что вы прошли через реальные боли работы с AI-агентами в парадигме SDD (Spec-Driven Development) и решили их не на уровне "магии промптов", а на уровне строгой архитектуры и контрактов.
|
||||
|
||||
Особенно впечатляет то, как вы учли специфику работы LLM: защита от галлюцинаций, предотвращение смешения слоев абстракции и жесткие требования к форматированию.
|
||||
|
||||
**Общая оценка: 9.5 / 10**
|
||||
|
||||
Вы создали **Enterprise-grade SDD фреймворк для AI-агентов**. То, как вы проработали edge-cases (форматирование хэшей, копирование блоков, разделение store и repo) — это уровень senior-архитектора, который уже "набил шишки" в продакшене.
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Сильные стороны (Что сделано блестяще)
|
||||
|
||||
### 1. Защита от типичных галлюцинаций и ошибок LLM
|
||||
* **Правило `#### Scenario`:** Вы явно указали, что сценарии должны использовать ровно 4 хэша, иначе валидация упадет. Это спасает от молчаливых ошибок парсинга.
|
||||
* **Правило `MODIFIED Requirements`:** Требование копировать *весь* блок требования, а не переписывать его частично, решает огромную проблему LLM, которые любят "терять" контекст или сценарии при модификации.
|
||||
* **Запрет на технологии в Proposal:** Жесткое ограничение "MUST NOT включать технологии... Эти решения появляются только после Delta Specs". Это не дает AI-агенту преждевременно скатиться в написание кода или выбор фреймворков.
|
||||
|
||||
### 2. Идеальная трассируемость (Traceability)
|
||||
Секция `Capabilities` в `proposal.md` — это **сердце вашей схемы**. Она создает жесткий контракт между "Зачем/Что" (Proposal) и "Как себя ведет" (Specs). AI не сможет написать спецификацию для фичи, которая не была заявлена в намерениях.
|
||||
|
||||
### 3. Учет вашей архитектуры (Multi-repo + Store)
|
||||
Инструкции в `specs` и `apply` явно оперируют понятием `<planningHome.root>` и каноническими путями. Это критически важно для вашего сценария с отдельным репозиторием под спеки и `openspec store`. Вы заранее решили проблему того, куда агент должен писать файлы, исключая путаницу между рабочими директориями.
|
||||
|
||||
### 4. Разделение "Что" (Specs) и "Как" (Design)
|
||||
* `specs` описывают только наблюдаемое поведение (контракт).
|
||||
* `design` описывает архитектуру, Delivery Map и риски.
|
||||
Это классический SDD, но реализованный так, что AI физически не может смешать их в одну кучу из-за разных шаблонов и инструкций.
|
||||
|
||||
### 5. Верификация в `tasks.md`
|
||||
Требование указывать `planned verification action` для каждой задачи — это киллер-фича. AI-агенты часто пишут задачи в стиле "Сделать Х", а потом не знают, как проверить, что Х сделано. Ваша схема заставляет его сразу думать о тестах или командах проверки.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Точки роста и потенциальные проблемы
|
||||
|
||||
Несмотря на высочайшее качество, схема имеет несколько мест, которые могут стать "бутылочным горлышком" или избыточными в контексте пет-проектов.
|
||||
|
||||
### 1. Избыточность (Over-engineering) для пет-проектов
|
||||
В `design.md` есть секции: `Solution Assessment`, `Contract Gate Decision`, `Migration Plan`.
|
||||
* **Проблема:** Для небольших фич в пет-проектах AI будет тратить огромное количество токенов, генерируя заглушки вроде "N/A, так как это не затрагивает API" или выдумывая несуществующие риски миграции. Это замедляет работу и засоряет контекст.
|
||||
|
||||
### 2. Отсутствие явного цикла итераций (Feedback Loop)
|
||||
Схема линейна: `proposal` → `specs` → `design` → `tasks` → `apply`.
|
||||
* **Проблема:** Что если на этапе `design` архитектор (или AI) поймет, что требования из `specs` технически невозможны или слишком дороги? Или что если во время `apply` выяснится, что `specs` были неполными?
|
||||
|
||||
### 3. Обработка блокеров в фазе `apply`
|
||||
В `apply` написано: *"Pause if you hit blockers or need clarification."*
|
||||
* **Проблема:** AI-агент может просто остановиться и вывести текст в консоль, но как вам (владельцу) отследить этот блокер? Как агент поймет, что он должен делать дальше?
|
||||
|
||||
### 4. Токенозатратность инструкций
|
||||
Инструкции в `schema.yaml` очень подробные. Это отлично для точности, но при передаче в системный промпт или контекст LLM они могут съедать тысячи токенов на каждый вызов.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Предложения по улучшению
|
||||
|
||||
Ниже приведены конкретные правки, которые можно внести в `schema.yaml` и шаблоны, чтобы сделать схему еще более устойчивой и экономичной.
|
||||
|
||||
### 1. Сделайте энтерпрайз-секции в `design.md` условными
|
||||
Чтобы AI не тратил токены на отписки, добавьте в `instruction` для `design` следующее правило:
|
||||
|
||||
```text
|
||||
Include `Solution Assessment` ONLY if the change introduces auth, storage,
|
||||
or external integrations. Include `Migration Plan` ONLY if it breaks backward
|
||||
compatibility. Include `Contract Gate Decision` ONLY if both API contract
|
||||
sides change. Otherwise, omit these sections entirely or mark them as N/A
|
||||
with a single word reason to save context.
|
||||
```
|
||||
|
||||
### 2. Введите механизм артефактов для блокеров и ревизий
|
||||
Добавьте в `apply` и `design` правила создания явных артефактов вместо простого "паузы":
|
||||
|
||||
```text
|
||||
In `apply`: If blocked, DO NOT guess or just pause. Create a `blocker.md`
|
||||
in the change directory detailing the exact error, the task that failed,
|
||||
and proposed solutions. Then halt execution.
|
||||
|
||||
In `design` or `apply`: If a spec-level behavior change is required because
|
||||
the original specs were technically impossible or incomplete, STOP. Generate
|
||||
a `revision-request.md` explaining why specs must change, and pause for
|
||||
owner approval before modifying specs.
|
||||
```
|
||||
|
||||
### 3. Уточните правила тестирования в `tasks.md`
|
||||
Вы написали: "Автоматические тесты обязательны для security/privacy...". Сделайте это правило более предсказуемым для AI:
|
||||
|
||||
```text
|
||||
If a task modifies existing logic, it MUST include a regression test.
|
||||
If it adds new logic, it MUST include a happy-path test.
|
||||
Do not write tests for DTOs without logic, declarative structures,
|
||||
or thin adapters unless they contain branching or transformation.
|
||||
```
|
||||
|
||||
### 4. Добавьте "Definition of Done" для фазы `apply`
|
||||
Чтобы агент четко понимал, когда он закончил работу, добавьте в конец `instruction` для `apply`:
|
||||
|
||||
```text
|
||||
The `apply` phase is complete ONLY when all tasks in `tasks.md` are marked
|
||||
`[x]`, all planned verification actions have passed, and a brief
|
||||
`Completion Summary` (listing executed verifications and final state)
|
||||
is appended to the bottom of `tasks.md`.
|
||||
```
|
||||
|
||||
### 5. Оптимизация токенов (Advanced)
|
||||
Если вы используете это через API, попробуйте вынести общие правила (например, "никогда не пиши код в specs", "используй SHALL/MUST") в отдельный базовый системный промпт (System Prompt), а в `schema.yaml` оставьте только уникальные для каждого артефакта дельты и специфичные правила форматирования.
|
||||
|
||||
---
|
||||
|
||||
## Заключение
|
||||
|
||||
Ваш подход с выделенным репозиторием под спеки и `openspec store` в связке с этой кастомной схемой — это **передовой край (bleeding edge)** использования AI для разработки.
|
||||
|
||||
Единственное, за чем нужно следить по мере развития пет-проектов — это **баланс между строгостью и оверхедом**. Если вы заметите, что AI-агент начинает "уставать" (генерировать отписки в `N/A` секциях или терять нить из-за объема контекста), просто примените советы из раздела "Предложения по улучшению", чтобы сделать схему более гибкой.
|
||||
|
||||
Отличная работа!
|
||||
@@ -0,0 +1,85 @@
|
||||
# Анализ SDD-схемы WealthLedger (OpenSpec)
|
||||
|
||||
## Общая оценка
|
||||
|
||||
Схема представляет собой **зрелый, продакшн-готовный пайплайн** управления AI-ассистентом. Конфигурация решает главную проблему применения LLM в разработке — преждевременное погружение в имплементацию и галлюцинации. Выстроен идеальный конвейер: от бизнес-намерения (Proposal) через поведенческий контракт (Specs) к архитектуре (Design) и чеклисту (Tasks), с жесткой защитой границ каждого этапа.
|
||||
|
||||
---
|
||||
|
||||
## Сильные стороны (Уровень "A+")
|
||||
|
||||
### 1. Защита от смешивания уровней (Level Slippage)
|
||||
Директивы вида `MUST NOT включать технологии...` в Proposal и `Не включай в specs: Internal class/function names` — золотой стандарт промпт-инжиниринга для SDD. LLM обожают смешивать *Why*, *What* и *How*. В данной схеме уровни изолированы максимально жестко.
|
||||
|
||||
### 2. Глубокое понимание квирков OpenSpec
|
||||
Конфигурация написана человеком, который реально дебажил поведение агента с фреймворком:
|
||||
- Требование ровно 4 решеток (`####`) для сценариев (критично для парсинга).
|
||||
- Грамотная работа с `planningHome.root` вместо хардкода путей (правильный подход для работы со store).
|
||||
- Разделение логики для `## Purpose` (добавляется только для новых capability, запрещается для дельт).
|
||||
- Корректная обработка флага `skip_specs: true`.
|
||||
|
||||
### 3. Эвристика "Solution Assessment"
|
||||
Ограничение триггеров для создания раздела (auth, security, storage, observability и т.д.) — отличное архитектурное решение. Оно не дает ИИ писать бесполезные простыни текста для тривиальных фич, но принуждает к глубокому анализу там, где цена ошибки высока.
|
||||
|
||||
### 4. Анти-галлюцинации в фазе Apply
|
||||
Правило `MUST NOT записывать ещё не наблюдённые результаты как выполненные` спасает от классической ошибки агентов, когда они ставят галочку `- [x]` и пишут "Created file X", хотя файла еще нет в файловой системе.
|
||||
|
||||
---
|
||||
|
||||
## Потенциальные риски и узкие места
|
||||
|
||||
### 1. Переполнение контекста (Context Window Bleed)
|
||||
Инструкции к артефактам `specs` и `design` очень объемны и содержат много edge-cases. При сложной фиче ИИ будет удерживать в контексте исходники репозиториев, Proposal и эти инструкции. Есть риск, что в конце генерации он "забудет" форматирование (например, начнет использовать `###` вместо `####` для сценариев).
|
||||
|
||||
### 2. Неявная мультирепозиторность в Tasks
|
||||
Агент запускается из папки с несколькими репозиториями, однако в инструкциях к `tasks.md` нет требования указывать целевой репозиторий. ИИ может сгенерировать таск "Создать модель User", не уточнив, идет ли это в `wealth-ledger-api`, `wealth-ledger-shared` или фронтенд.
|
||||
|
||||
### 3. Отсутствие механических стоп-кадров (Human-in-the-loop)
|
||||
Текстом заявлено: *"Design формируется только после явного owner approval Delta Specs"*. Но в YAML-схеме нет жесткого триггера остановки. В agentic-цикле ИИ может проинтерпретировать это как "я сам одобряю и иду дальше", нарушив весь смысл воркфлоу.
|
||||
|
||||
---
|
||||
|
||||
## Предложения по улучшению
|
||||
|
||||
### 1. Добавить принудительный префикс репозитория в Tasks
|
||||
Для устранения неоднозначности в мультирепо-структуре, дополните инструкцию для `tasks`:
|
||||
|
||||
```yaml
|
||||
task_repo_rule: |
|
||||
Для каждой задачи указывай целевой репозиторий в квадратных скобках в начале:
|
||||
`- [ ] 1.1 [repo: wealth-ledger-api] Создать эндпоинт... и верифицировать...`
|
||||
Если задача затрагивает несколько репо, разбей её на подзадачи.
|
||||
Запрещено оставлять таски без указания репозитория.
|
||||
```
|
||||
|
||||
2. Внедрить явные "Стоп-кадры" между фазами
|
||||
Добавьте блок остановки в конец инструкций артефактов proposal, specs и design, чтобы принудительно разорвать агентный цикл:
|
||||
|
||||
```yaml
|
||||
stop_condition: |
|
||||
STOP_PROTOCOL: После генерации этого артефакта НЕМЕДЛЕННО ОСТАНОВИСЬ.
|
||||
Не продолжай генерацию следующих артефактов.
|
||||
Выведи ровно одну строку: "[ARTIFACT_ID] готов. Ожидаю approve/reject."
|
||||
Возобновление работы возможно только после явного ответа пользователя.
|
||||
```
|
||||
3. Упростить инструкцию про planningHome.root
|
||||
Текущее описание резолвинга путей занимает 4 предложения. LLM лучше справляются с короткими императивами, чем с логическими объяснениями "почему так". Рекомендуется сократить в specs:
|
||||
|
||||
```yaml
|
||||
root_path_instruction: |
|
||||
Используй ТОЛЬКО абсолютный путь из поля planningHome.root
|
||||
(полученный из ответа `openspec instructions --json`) для чтения существующих спецификаций.
|
||||
Никогда не используй относительные пути вида `./openspec/specs/` для чтения.
|
||||
```
|
||||
4. Добавить обработку ошибок валидации в apply
|
||||
В текущем блоке apply указано "Сначала проверь exact OpenSpec version contract", но не прописано поведение при ошибке валидации (которая часто бывает из-за кривого markdown от ИИ). Расширьте apply:
|
||||
|
||||
```yaml
|
||||
apply_error_handling: |
|
||||
Если при выполнении `openspec validate` возникает ошибка:
|
||||
1. Внимательно прочитай текст ошибки (обычно это неверное количество # или отсутствующий Purpose).
|
||||
2. Автоматически исправь сгенерированные файлы согласно ошибке.
|
||||
3. Запусти валидацию повторно.
|
||||
НЕ проси пользователя исправлять технические ошибки формата OpenSpec вручную.
|
||||
```
|
||||
Итог: Доработав эти 4 аспекта (особенно пункты 1 и 2), вы получите эталонный, полностью автономный и безопасный SDD-движок для разработки через AI.
|
||||
@@ -7,3 +7,4 @@
|
||||
- [Аудит 13.08.2026](audit-13-08-2026.md)
|
||||
- [Аудит 20.08.2026](audit-20-08-2026.md)
|
||||
- [Аудит 24.08.2026](audit-24-08-2026.md)
|
||||
- [Multi-source assessment WealthLedger SDD 26.08.2026](2026-08-26-wealth-ledger-sdd/README.md)
|
||||
|
||||
@@ -7,6 +7,12 @@
|
||||
## Правила работы
|
||||
|
||||
- Каждая audit-derived запись имеет один статус: `planned`, `active`, `done`, `deferred` или `accepted`.
|
||||
- Каждое уникальное external claim дополнительно имеет независимый triage
|
||||
disposition: `confirmed`, `already-covered`, `rejected` или `deferred`.
|
||||
Повтор одного underlying claim в нескольких reports получает один Audit ID со
|
||||
ссылкой на каждый source. Disposition не является remediation status:
|
||||
`confirmed` ещё может быть active, а `rejected` — accepted как проверенное
|
||||
решение ничего не внедрять.
|
||||
- Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change.
|
||||
- `done` требует даты, archive path OpenSpec change, commit для каждого затронутого Git-репозитория и точных non-mutating verification commands с observed results.
|
||||
- `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца.
|
||||
@@ -16,18 +22,68 @@
|
||||
|
||||
- Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID.
|
||||
- Последний завершённый audit remediation change: [`2026-08-24-harden-agent-sdd-governance`](../../specs/openspec/changes/archive/2026-08-24-harden-agent-sdd-governance/) — `archived`; AUD24-01 и AUD24-03–AUD24-09, а также A-14–A-16 и A-18 закрыты.
|
||||
- Единственный active change: отсутствует.
|
||||
- Единственный active change: [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/) для SDD26-01–SDD26-03, SDD26-09, SDD26-12, SDD26-17, SDD26-21 и SDD26-28–SDD26-30.
|
||||
|
||||
## Текущая задача
|
||||
|
||||
Создать `assess-auth-platform-options` для AUD24-02.
|
||||
Завершить `harden-openspec-sdd-quality` без параллельного remediation change.
|
||||
|
||||
## Следующая рекомендуемая задача
|
||||
|
||||
`assess-auth-platform-options` для AUD24-02. Change применяет Solution Assessment к существующей реализации и зрелым auth platforms, включая Better Auth, и не предрешает миграцию.
|
||||
После terminal completion текущего active change вернуть
|
||||
`assess-auth-platform-options` для AUD24-02. Change применяет Solution
|
||||
Assessment к существующей реализации и зрелым auth platforms, включая Better
|
||||
Auth, и не предрешает миграцию.
|
||||
|
||||
## Реестр findings
|
||||
|
||||
### Multi-source assessment WealthLedger SDD 26.08.2026
|
||||
|
||||
Raw external reports и checksums находятся в
|
||||
[immutable snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md).
|
||||
Сокращения источников: [D] — DeepSeek, [G] — Gemini, [K] — Kimi, [Q] — Qwen,
|
||||
[Z] — Z.AI. Ни одна внешняя рекомендация сама по себе не является project
|
||||
authority.
|
||||
|
||||
| Audit ID | Нормализованный claim | Sources | Disposition | Remediation status | Evidence, rationale или review trigger |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| SDD26-01 | Снизить instruction bloat и устранить конкурирующих владельцев общих правил. | [D], [G], [Q], [Z] | confirmed | active | [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/): schema v2 владеет semantics, templates — shape, config — только facts/language, scripts — hard invariants; отдельный `_rules.md` не вводится. |
|
||||
| SDD26-02 | Проверять planning format машинно до approval и автоматически исправлять технические ошибки. | [D], [Z] | confirmed | active | Текущий change поставляет stage-aware non-mutating verifier, controlled-invalid fixtures и format-only retry path. |
|
||||
| SDD26-03 | Каждая task должна иметь однозначную delivery area; multi-repo implementation нужно разделять. | [D], [G], [Z] | confirmed | active | Schema v2 использует `[frontend\|backend\|specs\|docs\|workspace]`; planning verifier отклоняет owner из `N/A` area. |
|
||||
| SDD26-04 | Добавить `Target Repositories` уже в Proposal. | [G] | rejected | accepted | 2026-08-26; Proposal остаётся owner-readable intent без implementation topology. Полный scope repositories определяется позже через обязательную Design Delivery Map. |
|
||||
| SDD26-05 | Явно координировать порядок и совместимость multi-repository delivery. | [D], [G] | already-covered | accepted | 2026-08-26; Delivery Map, Contract Gate Decision, Migration Plan и workspace dispatcher уже задают owners, порядок, совместимость API и canonical gates. |
|
||||
| SDD26-06 | Формализовать trigger для Solution Assessment. | [D] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#build-versus-buy) и schema перечисляют auth, security, storage, integrations, observability, caching, concurrency и shared tooling. |
|
||||
| SDD26-07 | Не допускать Design/Apply по неутверждённым artifacts. | [D], [K], [Z] | already-covered | accepted | 2026-08-26; human approval хранится в разговоре, one-artifact entrypoints останавливаются, downstream approvals каскадно инвалидируются. Фиктивный `approval.md` или status field не создаётся. |
|
||||
| SDD26-08 | Разрешить partial/diff `MODIFIED` вместо полного requirement block. | [D] | rejected | accepted | 2026-08-26; native OpenSpec archive semantics требуют полного `MODIFIED`; собственный merge format создал бы второй transformation engine и риск потери scenarios. |
|
||||
| SDD26-09 | Дать компактные примеры сложных delta operations. | [D], [K] | confirmed | active | Schema v2 добавляет `MODIFIED`, `REMOVED` и `RENAMED` examples, сохраняя minimal ADDED-first template. |
|
||||
| SDD26-10 | Генерировать в `spec.md` placeholders всех delta sections. | [K] | rejected | accepted | 2026-08-26; пустые sections повышают шум и риск неверной операции. Complex forms принадлежат instructions/examples, а template остаётся минимальным. |
|
||||
| SDD26-11 | Явно определить DoD, verification и archive после Apply. | [D], [K], [Q] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#verify-archive-и-completion-evidence), workspace dispatcher, semantic verification, independent review и hard archive blockers уже образуют terminal protocol. Completion Evidence создаётся после факта, не в Tasks. |
|
||||
| SDD26-12 | Связать каждую task с точными Delta Requirements и отклонять uncovered requirements. | [D], [K] | confirmed | active | Schema v2 использует native identity `capability path — exact Requirement heading`; planning verifier проверяет ссылки и полное покрытие без собственного ID namespace. |
|
||||
| SDD26-13 | Добавить Fast Track или сокращённую вторую schema для мелких fixes. | [G] | rejected | accepted | 2026-08-26; один lifecycle сохраняет предсказуемые approvals и archive blockers. Пропорциональность обеспечивают `skip_specs`, conditional assessment/rollback и узкие tasks. |
|
||||
| SDD26-14 | Ограничивать agent context через tool-specific `.aiignore` и список repos из Proposal. | [G] | rejected | accepted | 2026-08-26; это не portable OpenSpec invariant. Context ограничивается Delivery Map, task owner и targeted reads; dependencies/build outputs уже исключаются локальными tool/repository rules. Пересмотреть при наблюдаемом context exhaustion. |
|
||||
| SDD26-15 | Ввести общий `blocked_by`/`blocks` graph между changes. | [K] | deferred | deferred | Review trigger: первый реальный случай двух одновременно необходимых changes с доказанной ordering dependency, которую нельзя выразить текущим single-active-remediation rule. |
|
||||
| SDD26-16 | Добавить priority и sizing в Tasks. | [K] | rejected | accepted | 2026-08-26; Tasks уже dependency-ordered и ограничены одной рабочей сессией. Оценочные points не защищают observable invariant и создают неподтверждённую точность. |
|
||||
| SDD26-17 | Для труднообратимых changes нужен проверяемый rollback contract. | [K] | confirmed | active | Design template и planning verifier требуют trigger/actions/data safety/verification для risk cases либо конкретный `N/A` reason. |
|
||||
| SDD26-18 | Добавить отдельный multi-repo context mapping file. | [K] | already-covered | accepted | 2026-08-26; native `openspec instructions ... --json` уже возвращает `planningHome`, `contextFiles`, `artifactPaths` и config context. Второй context map дублировал бы CLI state. |
|
||||
| SDD26-19 | Зафиксировать commit-message convention в schema. | [K] | rejected | accepted | 2026-08-26; commit style не меняет artifact correctness и принадлежит repository delivery policy только при появлении отдельного проверяемого требования. |
|
||||
| SDD26-20 | Сделать enterprise sections условными, чтобы снизить overhead. | [Q] | already-covered | accepted | 2026-08-26; Solution Assessment уже conditional, rollback допускает содержательный `N/A`; Delivery Map и Contract Gate Decision остаются обязательными, потому что защищают multi-repo scope. |
|
||||
| SDD26-21 | Добавить явный feedback loop из Design/Apply в ранний затронутый artifact. | [Q] | confirmed | active | Schema v2 и agent entrypoints маршрутизируют intent→Proposal, behavior→Specs, architecture/rollback→Design, decomposition→Tasks и инвалидируют downstream approvals. |
|
||||
| SDD26-22 | Создавать `blocker.md` и `revision-request.md` при каждом blocker/revision. | [Q] | rejected | accepted | 2026-08-26; новые workflow artifacts не поддерживаются native schema и быстро устаревают. Наблюдаемое основание сообщается Change Owner в разговоре; durable artifact добавится только при реальном повторяемом trigger. |
|
||||
| SDD26-23 | Требовать regression test для любой изменённой логики и happy-path test для любой новой. | [Q] | already-covered | accepted | 2026-08-26; [risk-based testing](engineering-governance.md#risk-based-testing) требует tests для существенных рисков и regressions, но осознанно отклоняет универсальные малоценные tests ради каждого logic/file change. |
|
||||
| SDD26-24 | Добавлять Completion Summary в конец Tasks. | [Q] | rejected | accepted | 2026-08-26; Tasks содержат только planned work. Observed results и commits появляются после выполнения в verification/archive evidence, иначе checklist смешивает план и факты. |
|
||||
| SDD26-25 | Требовать точный текстовый `STOP_PROTOCOL` после каждого artifact. | [Z] | rejected | accepted | 2026-08-26; обязательная остановка и явный approval уже enforced entrypoints. Фиксация одной строки ответа хрупка и не усиливает identity или semantic approval. |
|
||||
| SDD26-26 | Сократить explanation `planningHome.root` до короткого imperative. | [Z] | rejected | accepted | 2026-08-26; пояснение предотвращает ошибочное вычисление path при store-backed и local modes OpenSpec 1.10. После удаления duplicate config rules instruction source остаётся приемлемым; пересмотреть при измеренном context regression. |
|
||||
| SDD26-27 | Добавить дополнительные contract gates вроде `internal-proto`. | [G] | deferred | deferred | Review trigger: появление второго реального межсервисного committed contract, для которого `runtime-openapi` и repository gates недостаточны. До этого generic gate будет speculative. |
|
||||
| SDD26-28 | Root project-owned agent projection должна восстанавливаться из versioned authority. | local triage | confirmed | active | Обнаружено локально: root `.opencode` не принадлежит Git repository. Текущий change добавляет canonical source, atomic sync и exact drift verifier в `specs`. |
|
||||
| SDD26-29 | Exact OpenSpec version должна быть единым compatibility contract, а не вечным literal в scripts/fixtures. | local triage | confirmed | active | `.cli-version` остаётся единственным current contract; markers/verifiers выводят expected value из него, новая stable не включает auto-upgrade. |
|
||||
| SDD26-30 | Raw multi-source evidence и triage должны быть versioned раздельно. | local triage | confirmed | active | Пять reports сохранены byte-for-byte в [snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md); этот live registry хранит dispositions и statuses отдельно. |
|
||||
|
||||
[D]: ../audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md
|
||||
[G]: ../audits/2026-08-26-wealth-ledger-sdd/gemini-result.md
|
||||
[K]: ../audits/2026-08-26-wealth-ledger-sdd/kimi-result.md
|
||||
[Q]: ../audits/2026-08-26-wealth-ledger-sdd/qwen-result.md
|
||||
[Z]: ../audits/2026-08-26-wealth-ledger-sdd/zai-result.md
|
||||
|
||||
### Аудит 13.08.2026
|
||||
|
||||
| Audit ID | Текущий статус | Связь и следующее действие | Terminal evidence или trigger |
|
||||
|
||||
@@ -14,6 +14,10 @@
|
||||
|
||||
**Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.
|
||||
|
||||
**Planning structural gate** — stage-aware проверка доступной формы и ссылочной
|
||||
целостности текущего planning artifact до запроса approval. Она не оценивает
|
||||
качество rationale и не является semantic approval.
|
||||
|
||||
## Последовательность SDD
|
||||
|
||||
Каждый versioned change проходит один граф:
|
||||
@@ -25,10 +29,21 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
|
||||
- Proposal формулирует намерение, границы и ожидаемый результат без технологий, API, файлов и зависимостей.
|
||||
- Delta Specs описывают изменение наблюдаемого поведения и инвариантов без изменений кода.
|
||||
- Design объясняет архитектурный способ реализации крупными частями, риски и альтернативы; он не является построчной инструкцией.
|
||||
- Tasks — implementation checklist, достаточный для выполнения Design и Specs. Он содержит планируемые проверки, но не будущие результаты, commits или post-archive bookkeeping.
|
||||
- Tasks — implementation checklist, достаточный для выполнения Design и Specs.
|
||||
Каждый checkbox объявляет ровно одну area, `Covers` ссылается на native
|
||||
identity `capability path — exact Requirement heading` либо объясняет `N/A`,
|
||||
а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
|
||||
результаты, commits или post-archive bookkeeping.
|
||||
|
||||
AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно.
|
||||
|
||||
До запроса approval агент запускает доступный stage planning gate и сам
|
||||
исправляет технические ошибки формата. Полный change validation не объявляется
|
||||
успешным, пока downstream artifacts отсутствуют. Форматное исправление без
|
||||
изменения intent, behavior, decisions или task scope не требует reapproval;
|
||||
семантическое изменение возвращает workflow к самому раннему затронутому
|
||||
artifact.
|
||||
|
||||
Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.
|
||||
|
||||
## Delivery Map и multi-repository delivery
|
||||
@@ -42,6 +57,12 @@ Design каждого change оценивает все четыре област
|
||||
|
||||
Change остаётся active, пока каждая affected область не реализована и не прошла свой canonical gate. Design содержит Contract Gate Decision: `runtime-openapi` имеет статус `required`, когда изменение затрагивает frontend и backend стороны API contract, иначе `N/A` с конкретной причиной. Успех одного репозитория не компенсирует отсутствие или failure другого.
|
||||
|
||||
Task owner выбирается только из `frontend`, `backend`, `specs`, `docs` и
|
||||
`workspace`. Repository owner нельзя использовать для area со статусом `N/A`;
|
||||
cross-repository implementation разбивается на отдельные tasks. `workspace`
|
||||
владеет только orchestration и verification, но не подменяет repository-owned
|
||||
implementation или canonical gates.
|
||||
|
||||
## Risk-based testing
|
||||
|
||||
Автоматизированный тест обязателен, когда изменение затрагивает хотя бы один существенный риск:
|
||||
@@ -75,6 +96,17 @@ Solution Assessment сравнивает применимые варианты
|
||||
|
||||
Собственная реализация допустима, только если подходящего решения нет или доказана существенная несовместимость. Тогда Design фиксирует проверенные варианты, конкретные gaps, принятые риски и trigger повторного рассмотрения. Для обратимого изменения вне перечисленных областей отдельная формальная оценка не создаётся ради процесса.
|
||||
|
||||
## Rollback contract
|
||||
|
||||
Design фиксирует status `required`, trigger, actions, data safety и verification,
|
||||
если change меняет auth/security behavior, data integrity или migration, public
|
||||
contract либо другое существенно труднообратимое решение. Contract учитывает
|
||||
данные и compatibility, созданные после delivery, и не может зависеть от нового
|
||||
неутверждённого архитектурного решения.
|
||||
|
||||
Для обратимого change вне этих рисков status `N/A` содержит конкретную причину.
|
||||
Отдельный rollback artifact не создаётся ради процесса.
|
||||
|
||||
## Single Source of Truth
|
||||
|
||||
| Вид знания | Authoritative location |
|
||||
@@ -85,6 +117,7 @@ Solution Assessment сравнивает применимые варианты
|
||||
| Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
|
||||
| Устойчивые архитектурные решения и причины | `docs/adr` |
|
||||
| Инженерная policy и completion evidence | `docs/development` |
|
||||
| Canonical source project-owned agent commands и skills | `specs/agent-projection/opencode` |
|
||||
| Компактная маршрутизация AI-агентов | root и repository-local `AGENTS.md` |
|
||||
|
||||
`docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.
|
||||
@@ -104,6 +137,17 @@ CI пока отсутствует, поэтому обязательные gate
|
||||
|
||||
Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.
|
||||
|
||||
Root `.opencode/commands` и `.opencode/skills` являются derived projection.
|
||||
Изменения вносятся в versioned source под `specs`, распространяются explicit
|
||||
atomic sync и проверяются exact file/content comparison; package manifests,
|
||||
dependencies и machine-local state не являются authority inputs.
|
||||
|
||||
Текущая exact OpenSpec CLI version читается только из
|
||||
`specs/openspec/.cli-version`. Новая stable release не меняет contract
|
||||
автоматически. Upgrade выполняется отдельным SDD change после isolated проверки
|
||||
schema, agent projection, canonical store и positive/negative fixtures;
|
||||
историческое evidence сохраняет фактическую прежнюю version.
|
||||
|
||||
## Verify, archive и Completion Evidence
|
||||
|
||||
Structural validation OpenSpec проверяет schema и форму артефактов, но не соответствие реализации. До archive обязательны:
|
||||
|
||||
@@ -19,10 +19,15 @@ bash specs/scripts/verify-openspec-version.sh
|
||||
```
|
||||
|
||||
Несовпадение version блокирует операцию до чтения или изменения store.
|
||||
Публикация новой stable версии не меняет этот contract автоматически. Upgrade
|
||||
выполняется отдельным SDD change после staged проверки schema, instructions,
|
||||
project-owned projection, store resolution и hard blockers; historical archives
|
||||
не переписываются.
|
||||
|
||||
## Project-local schema
|
||||
|
||||
Новые changes по умолчанию используют schema `wealth-ledger-sdd` из `specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
|
||||
Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 2 из
|
||||
`specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
|
||||
|
||||
```text
|
||||
proposal → specs → design → tasks → apply
|
||||
@@ -30,6 +35,18 @@ proposal → specs → design → tasks → apply
|
||||
|
||||
OpenSpec обеспечивает structural order, а явное решение Change Owner — переход между артефактами. Agent создаёт один текущий artifact и останавливается для approval. Роли артефактов и cascade rules определены в governance policy; исполняемые templates и instructions принадлежат schema.
|
||||
|
||||
До запроса approval выполняется доступная stage-aware проверка:
|
||||
|
||||
```bash
|
||||
bash specs/scripts/verify-openspec-planning.sh <change>
|
||||
```
|
||||
|
||||
Proposal проверяется без ложного объявления полного change success; по мере
|
||||
появления Specs, Design и Tasks добавляются strict validation, Delivery Map,
|
||||
rollback, area ownership и exact Requirement coverage. Технический format
|
||||
failure исправляется и проверяется повторно; structural success не означает
|
||||
approval.
|
||||
|
||||
Project-local schema проверяется из `specs`:
|
||||
|
||||
```bash
|
||||
@@ -41,9 +58,30 @@ openspec schema which wealth-ledger-sdd --json
|
||||
|
||||
## Agent entrypoints и обновление OpenSpec
|
||||
|
||||
Root `.opencode` — generated local projection OpenSpec 1.10 с минимальными WealthLedger overlays: fixed store, one-artifact-at-a-time и hard archive blockers. Она не является SSOT, потому что workspace root не versioned.
|
||||
Canonical source WealthLedger-owned OpenCode commands и skills находится в
|
||||
`specs/agent-projection/opencode`. Root `.opencode/commands` и
|
||||
`.opencode/skills` — derived local projection с минимальными overlays: fixed
|
||||
store, one-artifact-at-a-time, stage planning gate, Apply feedback routing и
|
||||
hard archive blockers. Package manifests, installed dependencies и machine-local
|
||||
state не входят в source.
|
||||
|
||||
`openspec update` не запускается напрямую из workspace root. Новую upstream version сначала генерируют в isolated staging, сравнивают с projection, переносят upstream delta и повторно накладывают project overlays. После этого обязательно выполняют authority fixtures; permissive archive, conditional store selection и второй `openspec` root считаются failures.
|
||||
Projection восстанавливается и проверяется из workspace root:
|
||||
|
||||
```bash
|
||||
bash specs/scripts/sync-agent-projection.sh
|
||||
bash specs/scripts/verify-agent-projection.sh
|
||||
```
|
||||
|
||||
Sync выполняет verified cutover и восстанавливает прежнее local state при
|
||||
ошибке. Verifier non-mutating сравнивает required file set и contents и получает
|
||||
expected `generatedBy` marker из `.cli-version`.
|
||||
|
||||
`openspec update` не запускается напрямую из workspace root. Новую upstream
|
||||
version сначала генерируют в isolated staging, сравнивают с canonical source,
|
||||
переносят upstream delta и повторно накладывают минимальные project overlays.
|
||||
После этого sync обновляет derived root, а authority fixtures проверяют marker,
|
||||
missing/content drift, permissive archive, conditional store selection и второй
|
||||
`openspec` root как failures.
|
||||
|
||||
## Реализация и проверка change
|
||||
|
||||
@@ -55,10 +93,16 @@ bash specs/scripts/verify-workspace-change.sh <change>
|
||||
|
||||
`specs` проверяется всегда. Dispatcher читает явный Contract Gate Decision из Design и сравнивает backend runtime OpenAPI с committed frontend snapshot только при `runtime-openapi: required`; этот status допустим лишь при affected frontend и backend. Child failure блокирует общий результат; fallback и auto-fix отсутствуют.
|
||||
|
||||
Перед affected-area gates dispatcher повторяет planning verifier. Tasks имеют
|
||||
формат `X.Y [area] action` и indented `Covers`/`Verification`; каждый Delta
|
||||
Requirement покрывается точной ссылкой хотя бы один раз, а `workspace` остаётся
|
||||
только owner orchestration/verification.
|
||||
|
||||
Перед archive отдельно подтверждаются structural и semantic gates:
|
||||
|
||||
```bash
|
||||
bash specs/scripts/verify-openspec-authority.sh
|
||||
bash specs/scripts/verify-agent-projection.sh
|
||||
openspec validate <change> --type change --strict --store wealth-ledger-specs
|
||||
openspec validate --specs --strict --store wealth-ledger-specs
|
||||
```
|
||||
|
||||
+1
-1
@@ -7,7 +7,7 @@
|
||||
},
|
||||
"scripts": {
|
||||
"runtime:check": "node scripts/verify-node-version.mjs",
|
||||
"lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
|
||||
"lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#audits/2026-08-26-wealth-ledger-sdd/*-result.md\"",
|
||||
"verify": "npm run runtime:check && npm run lint && git diff --check"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
||||
Reference in New Issue
Block a user