# Анализ 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.