Анализ схемы Spec-Driven Development (wealth-ledger-sdd) и рекомендации по улучшению

1. Общий обзор и контекст

Представленная схема wealth-ledger-sdd реализует Spec-Driven Development (SDD) поверх фреймворка openspec. Конфигурация рассчитана на работу AI-агента из общей корневoй директории, объединяющей несколько отдельных репозиториев, с хранением спецификаций в изолированном хранилище (openspec store).

Пайплайн планирования состоит из 4 последовательных этапов:

Proposal (proposal.md) — продуктовое и бизнес-обоснование («Зачем» и «Что меняется на верхнем уровне»).
Specs (specs/**/*.md) — контракты наблюдаемого поведения системы («ЧТО система делает»).
Design (design.md) — техническая архитектура и решения по реализации («КАК сделать»).
Tasks (tasks.md) — атомарный чек-лист задач для выполнения («ЧТО СДЕЛАТЬ конкретно»).

2. Анализ сильных сторон (Strengths)

Строгая синтаксическая дисциплина для LLM: Инструкции к артефакту specs содержат четкие предохранители против специфических багов генерации Markdown у AI-моделей (например, строго 4 хештега #### Scenario: и нормативные глаголы SHALL/MUST). Это гарантирует предсказуемый парсинг артефактов со стороны OpenSpec CLI.
Изоляция планирования от продуктового кода: Использование переменной planningHome.root гарантирует корректную работу с wealth-ledger-specs store. Репозитории сервисов не засоряются промежуточными черновиками и файлами планирования.
Защита от избыточной работы (Build-vs-Buy Control): Обязательный раздел Solution Assessment в design.md предотвращает попытки AI «изобретать велосипед» при добавлении авторизации, кеширования, интеграций или инфраструктурных утилит.
Прагматичная стратегия тестирования: Инструкция к tasks.md явно задает зоны, где тесты обязательны (финансы, безопасность, персистентность, публичные контракты), и запрещает избыточные unit-тесты для DTO, тонких адаптеров и декларативных структур.
Четкое разделение ответственности между этапами: Запрет на упоминание технологий в proposal.md предотвращает преждевременное принятие архитектурных решений до согласования целей бизнеса.

3. Анализ узких мест и рисков в мультирепозиторной среде

Неопределенность адресации файлов в мультирепо (File Path Ambiguity): В текущих шаблонах tasks.md и design.md отсутствуют явные требования указывать имя репозитория. В рабочей директории с десятком сервисов задача вида Modify user.service.ts приведет к ошибкам адресации или поиску файла по всем подпапкам.
Размытый фокус затронутых репозиториев на старте: В proposal.md есть секция Impact, но нет явного списка целевых сервисов. Агент может не рассчитать требуемый контекст и пропустить смежный сервис на этапе проектирования контрактов.
Высокий оверхед на мелкие изменения (Fast-Track overhead): Полный 4-этапный цикл избыточен для локального рефакторинга или точечного багфикса. Хотя параметр skip_specs: true предусмотрен, генерация design.md и proposal.md для однострочных правок влечет лишние затраты токенов и времени.
Риск раздувания контекстного окна (Context Window Bloat): Запуск AI-агента из единого корня открывает ему доступ ко всему коду всех проектов. Без явных ограничений в промпте и конфигурации агент может считывать лишние репозитории, исчерпывая лимит контекста.

4. Предложения по улучшению (Improvement Proposals)

4.1. Внедрение явной мультирепозиторной адресации

А. Секция Target Repositories в `proposal.md`

Добавьте в шаблон proposal.md секцию, фиксирующую список затронутых репозиториев:

## Target Repositories

<!-- Укажите репозитории, в которые будут вноситься изменения -->
- `<repo-name>`: <роль репозитория в данном изменении>

Б. Строгий формат задач в `tasks.md`

Обновите инструкцию артефакта tasks в schema.yaml, обязывая AI указывать путь к репозиторию:

# В инструкции tasks в schema.yaml:
- Каждая задача MUST указывать целевой репозиторий в формате: `- [ ] X.Y [<repo-folder>] <action>`

Пример сгенерированной задачи:

- [ ] 1.1 [auth-service] Add standard JWT validation middleware and verify auth test suite passes
- [ ] 1.2 [frontend-app] Update API client DTO types to align with new contract

4.2. Организация Fast-Track сценария для точечных правок

Для оптимизации работы над некрупными задачами рекомендуется предусмотреть ускоренный пайплайн.

Если изменение не меняет внешнее поведение: В .openspec.yaml устанавливается skip_specs: true.
Сокращенный Design: В инструкцию design добавьте правило: если Delivery Map затрагивает только 1 репозиторий и runtime-openapi равен N/A, разделы Solution Assessment и Migration Plan можно опускать.

4.3. Усиление Contract Gate Decision

В мультирепозиторном окружении изменение контракта API в одном сервисе сразу требует обновления клиента в другом. Уточните таблицу Contract Gate Decision в design.md:

### Contract Gate Decision

| Gate | Status | Affected Repositories | Reason |
| --- | --- | --- | --- |
| runtime-openapi | `required` / `N/A` | `backend-api`, `frontend-web` | <!-- причины --> |
| internal-proto | `required` / `N/A` | `billing-service`, `orders-service` | <!-- причины --> |

4.4. Оптимизация контекста AI-агента

При запуске агента из общего корня настройте файл .aiignore (или .cursorignore / .windsurfignore в зависимости от используемого CLI/IDE) в корневой папке:

Исключите тяжелые бинарники, папки сборки и зависимости (**/node_modules, **/dist, **/target, **/.git).
Запретите агенту просматривать репозитории, не указанные в Target Repositories для текущей задачи.

5. Итоговая оценка качества схемы

Критерий	Оценка (1-5)	Комментарий
LLM-friendly (предсказуемость)	5/5	Отличные предохранители против сбоев синтаксиса и парсинга Markdown.
Архитектурная строгость	5/5	Баланс между бизнес-целями, specs и архитектурным проектированием.
Мультирепозиторная адаптация	3.5/5	Требует добавления явных указателей путей репозиториев в `tasks` и `proposal`.
Эффективность по скорости/токенам	4/5	Отлично для фич, требует Fast-Track сценария для мелких правок.

Вердикт: Схема находится на очень высоком уровне разработки. После внесения точечных правок по мультирепозиторной адресации и фильтрации контекста она станет эталонной для мультисервисной Spec-Driven разработки.

10 KiB Raw Blame History Unescape Escape