docs: record SDD audit remediation
This commit is contained in:
@@ -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` секциях или терять нить из-за объема контекста), просто примените советы из раздела "Предложения по улучшению", чтобы сделать схему более гибкой.
|
||||
|
||||
Отличная работа!
|
||||
Reference in New Issue
Block a user