86 lines
8.2 KiB
Markdown
86 lines
8.2 KiB
Markdown
# Анализ 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.
|