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

task_repo_rule: |
  Для каждой задачи указывай целевой репозиторий в квадратных скобках в начале:
  `- [ ] 1.1 [repo: wealth-ledger-api] Создать эндпоинт... и верифицировать...`
  Если задача затрагивает несколько репо, разбей её на подзадачи. 
  Запрещено оставлять таски без указания репозитория.

Внедрить явные "Стоп-кадры" между фазами Добавьте блок остановки в конец инструкций артефактов proposal, specs и design, чтобы принудительно разорвать агентный цикл:

stop_condition: |
  STOP_PROTOCOL: После генерации этого артефакта НЕМЕДЛЕННО ОСТАНОВИСЬ. 
  Не продолжай генерацию следующих артефактов. 
  Выведи ровно одну строку: "[ARTIFACT_ID] готов. Ожидаю approve/reject."
  Возобновление работы возможно только после явного ответа пользователя.

Упростить инструкцию про planningHome.root Текущее описание резолвинга путей занимает 4 предложения. LLM лучше справляются с короткими императивами, чем с логическими объяснениями "почему так". Рекомендуется сократить в specs:

root_path_instruction: |
  Используй ТОЛЬКО абсолютный путь из поля planningHome.root 
  (полученный из ответа `openspec instructions --json`) для чтения существующих спецификаций. 
  Никогда не используй относительные пути вида `./openspec/specs/` для чтения.

Добавить обработку ошибок валидации в apply В текущем блоке apply указано "Сначала проверь exact OpenSpec version contract", но не прописано поведение при ошибке валидации (которая часто бывает из-за кривого markdown от ИИ). Расширьте apply:

apply_error_handling: |
  Если при выполнении `openspec validate` возникает ошибка:
  1. Внимательно прочитай текст ошибки (обычно это неверное количество # или отсутствующий Purpose).
  2. Автоматически исправь сгенерированные файлы согласно ошибке.
  3. Запусти валидацию повторно.
  НЕ проси пользователя исправлять технические ошибки формата OpenSpec вручную.

Итог: Доработав эти 4 аспекта (особенно пункты 1 и 2), вы получите эталонный, полностью автономный и безопасный SDD-движок для разработки через AI.

8.2 KiB Raw Blame History Unescape Escape