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

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

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

Пайплайн планирования состоит из 4 последовательных этапов:
1. **Proposal** (`proposal.md`) — продуктовое и бизнес-обоснование («Зачем» и «Что меняется на верхнем уровне»).
2. **Specs** (`specs/**/*.md`) — контракты наблюдаемого поведения системы («ЧТО система делает»).
3. **Design** (`design.md`) — техническая архитектура и решения по реализации («КАК сделать»).
4. **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` секцию, фиксирующую список затронутых репозиториев:

```markdown
## Target Repositories

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

#### Б. Строгий формат задач в `tasks.md`
Обновите инструкцию артефакта `tasks` в `schema.yaml`, обязывая AI указывать путь к репозиторию:

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

Пример сгенерированной задачи:
```markdown
- [ ] 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 сценария для точечных правок

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

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

---

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

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

```markdown
### 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) в корневой папке:

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

---

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

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

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