docs: record SDD audit remediation
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
# Анализ схемы 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 разработки.
|
||||
Reference in New Issue
Block a user