# Анализ и оценка кастомной схемы 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` секциях или терять нить из-за объема контекста), просто примените советы из раздела "Предложения по улучшению", чтобы сделать схему более гибкой.

Отличная работа!