docs/audits/2026-08-26-wealth-ledger-sdd/qwen-result.md

Анализ и оценка кастомной схемы 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 следующее правило:

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 правила создания явных артефактов вместо простого "паузы":

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:

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:

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

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