@dzhechkov/keysarium 1.2.0 → 1.3.0

package/templates/docs/feature-adr/05-user-guide.md

@@ -0,0 +1,508 @@
+# Руководство пользователя @dzhechkov/skills-feature-adr
+
+> Полное руководство по использованию адаптивного pipeline для разработки фич любой сложности.
+
+---
+
+## Содержание
+
+1. [Что такое Feature ADR?](#1-что-такое-feature-adr)
+2. [Когда использовать Feature ADR?](#2-когда-использовать-feature-adr)
+3. [Быстрый старт](#3-быстрый-старт)
+4. [Понимание Complexity Tiers](#4-понимание-complexity-tiers)
+5. [Работа с checkpoints](#5-работа-с-checkpoints)
+6. [Понимание артефактов](#6-понимание-артефактов)
+7. [Работа с ADR](#7-работа-с-adr)
+8. [Работа с архитектурой](#8-работа-с-архитектурой)
+9. [Работа с QE отчётом](#9-работа-с-qe-отчётом)
+10. [Советы и best practices](#10-советы-и-best-practices)
+11. [FAQ](#11-faq)
+
+---
+
+## 1. Что такое Feature ADR?
+
+Feature ADR -- это **9-шаговый адаптивный pipeline** для разработки программных фич. Он берёт описание задачи на входе и проводит через полный цикл: от классификации сложности до написания кода и проверки качества.
+
+### Ключевые возможности
+
+- **Автоматическое масштабирование сложности (S/M/L/XL).** Complexity Router анализирует описание фичи по 6 измерениям и определяет оптимальный набор шагов. Простой баг-фикс на 2 файла не будет проходить через DDD-моделирование, а миграция на новый фреймворк не останется без архитектурных решений.
+
+- **ADR-driven архитектурные решения.** Каждое значимое архитектурное решение фиксируется в Architecture Decision Record (ADR) с анализом альтернатив, матрицей принятия решений и описанием последствий. Решения не теряются и прослеживаются до кода.
+
+- **Мульти-агентная проверка качества.** На XL-фичах Step 8 (QE) запускает панель из 3 параллельных ревьюеров: по корректности, безопасности и архитектуре. Каждый работает независимо, результаты синтезируются в единый отчёт.
+
+- **Работает автономно или вместе с Keysarium.** Feature ADR -- самостоятельный pipeline. Он не зависит от исследовательского pipeline `/casarium`, но использует общие скиллы (`explore`, `problem-solver-enhanced`, `frontend-design`) и протоколы (checkpoints, promise tags).
+
+---
+
+## 2. Когда использовать Feature ADR?
+
+| Ситуация | Команда | Почему |
+|----------|---------|--------|
+| Реализация программной фичи | `/feature-adr` | Полный цикл от требований до QE |
+| Исследование AI-кейса для хакатона | `/casarium` | Другой pipeline: discovery, research, presentation |
+| Решение сложной проблемы (без кода) | `/solve` | Фокус на анализе, без реализации |
+| Проектирование архитектуры (без кода) | `/architecture-phase` | Только C4-диаграммы и sequence flows |
+| Создание нового скилла или команды | `/bto-build` | Генерация + мульти-агентная оценка |
+
+**Правило:** если результат вашей работы -- **работающий код в репозитории**, используйте `/feature-adr`. Если результат -- **документ, презентация или анализ** -- используйте соответствующую команду выше.
+
+---
+
+## 3. Быстрый старт
+
+Запустите команду с описанием фичи:
+
+```bash
+/feature-adr Добавить систему уведомлений пользователей
+```
+
+Pipeline запускается автоматически. Вот что происходит на каждом шаге:
+
+### Шаг за шагом
+
+**1. Complexity Router классифицирует фичу -- Checkpoint 0**
+
+Система анализирует описание по 6 измерениям (файлы, домены, интеграции, breaking changes, модели данных, cross-cutting concerns) и определяет tier. Вы видите:
+
+```
+STEP 0/8: Complexity Router Complete
+Tier: M | Active Steps: [0, 1, 3, 5, 6, 7, 8]
+
+Feature classified as M based on: 8 files affected, 2 domains (Orders + Notifications)
+Pipeline: 7 steps, estimated 45 min
+
+* "ок" -- proceed with this tier
+* "повысь" -- bump to next tier
+* "понизь" -- drop to lower tier
+```
+
+Вы подтверждаете tier или корректируете его.
+
+**2. Requirements gathered -- Checkpoint 1**
+
+Собраны функциональные и нефункциональные требования с критериями приёмки (acceptance criteria) для каждого.
+
+**3. (если M+) ADR created -- Checkpoint 3**
+
+Для каждого значимого архитектурного решения создан ADR с альтернативами и обоснованием выбора.
+
+**4. (если M+) Architecture designed -- Checkpoint 5**
+
+Созданы C4-диаграммы (компоненты, контейнеры) и описание API.
+
+**5. Implementation plan -- Checkpoint 6**
+
+Задачи декомпозированы с зависимостями и указанием файлов для каждой задачи.
+
+**6. Code generated -- Checkpoint 7**
+
+Код написан в репозитории. Все изменения задокументированы в `change_manifest.md`.
+
+**7. QE completed -- Checkpoint 8**
+
+Тесты запущены, код отревьюен, acceptance criteria проверены. Вердикт: READY / NEEDS FIXES / CONDITIONAL.
+
+**8. Готово!**
+
+Все артефакты лежат в `features/<slug>/`, код -- в вашем репозитории.
+
+---
+
+## 4. Понимание Complexity Tiers
+
+Tier определяется автоматически суммой баллов по 6 измерениям (от 6 до 24).
+
+### Tier S -- Small (6-8 баллов, ~15 минут)
+
+- **Масштаб:** 1-3 файла, 1 домен, нет новых интеграций
+- **Активные шаги:** 0 -> 1 -> 6 -> 7 -> 8
+- **Примеры:** баг-фикс, изменение конфигурации, утилитарная функция, добавление поля
+- **Особенности:**
+  - Requirements -- 3-5 пунктов, без формального документа
+  - Implementation plan -- inline, без отдельного файла
+  - QE -- только smoke-тесты (компилируется? существующие тесты проходят?)
+
+### Tier M -- Medium (9-13 баллов, ~45 минут)
+
+- **Масштаб:** 4-10 файлов, 1-2 домена, 0-1 интеграция
+- **Активные шаги:** 0 -> 1 -> 3 -> 5(light) -> 6 -> 7 -> 8
+- **Примеры:** новый API-endpoint, UI-компонент, простая фича с фронтом и бэком
+- **Особенности:**
+  - Один ADR для главного архитектурного решения
+  - Architecture light -- только component diagram, без полного C4
+  - QE -- unit-тесты + базовый code review
+
+### Tier L -- Large (14-19 баллов, ~2 часа)
+
+- **Масштаб:** 11-30 файлов, 2-4 домена, 1-3 интеграции
+- **Активные шаги:** все, с параллельными парами [2 || 3], [4 || 5]
+- **Примеры:** новый модуль, мульти-доменная фича, интеграция с внешним сервисом
+- **Особенности:**
+  - Research: анализ паттернов в кодовой базе и внешних аналогов
+  - Несколько ADR для каждого значимого решения
+  - DDD: bounded contexts + ubiquitous language
+  - Полный C4 (Context + Container + Component)
+  - QE: unit + integration тесты + полный code review
+
+### Tier XL -- Extra Large (20-24 баллов, 4+ часов)
+
+- **Масштаб:** 30+ файлов, 4+ доменов, 3+ интеграций
+- **Активные шаги:** все, максимальный параллелизм
+- **Примеры:** новая подсистема, миграция фреймворка, major refactor
+- **Особенности:**
+  - Все шаги на полной глубине
+  - Step 7: несколько параллельных агентов, по одному на модуль
+  - Step 8: полная QE -- unit + integration + e2e + security + performance review
+  - Мульти-агентная панель ревью (3 параллельных ревьюера)
+
+### Правила переопределения
+
+Complexity Router может скорректировать tier вверх:
+
+- Если **любое одно измерение = XL (4 балла)** -- минимальный tier = L
+- Если **breaking changes > 0** -- минимальный tier = M
+- Слова "refactor", "migration", "redesign" в описании -- смещение к L/XL
+- Вы можете **явно указать tier** на Checkpoint 0
+
+---
+
+## 5. Работа с checkpoints
+
+Каждый активный шаг завершается checkpoint -- точкой, где вы проверяете результат и принимаете решение.
+
+### Формат checkpoint
+
+```
+STEP N/8: [Step Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Tier: M | Active Steps: [0, 1, 3, 5, 6, 7, 8]
+
+[Краткое описание: что сделано, 2-3 строки]
+Artifacts: [список файлов]
+
+* "ок" -- next step
+* "углуби [section]" -- elaborate
+* "[feedback]" -- adjust
+```
+
+### Ваши варианты ответа
+
+| Ответ | Что произойдёт |
+|-------|----------------|
+| `ок` | Переход к следующему шагу |
+| `углуби X` | Текущий шаг дорабатывается: раздел X расширяется |
+| `переделай` | Текущий шаг выполняется заново |
+| `повысь` / `понизь` (только Checkpoint 0) | Изменение tier |
+| Конкретная обратная связь | Текущий шаг корректируется по вашим замечаниям |
+
+### Важно
+
+- Pipeline **не переходит** к следующему шагу без вашего подтверждения
+- Вы можете давать обратную связь **несколько раз** на одном checkpoint
+- На **Checkpoint 0** вы можете изменить tier, но после подтверждения tier фиксируется на весь pipeline
+
+---
+
+## 6. Понимание артефактов
+
+Все артефакты создаются в директории `features/<feature-slug>/`. Вот что содержит каждый файл:
+
+### 00_complexity_assessment.md
+**Создаётся:** всегда (Step 0)
+
+Таблица с оценкой по 6 измерениям, итоговый балл, выбранный tier, список активных шагов и time budget. Позволяет понять, почему pipeline был настроен именно так.
+
+### 01_requirements.md
+**Создаётся:** всегда (Step 1, для S-tier -- в упрощённом виде)
+
+Функциональные и нефункциональные требования. Каждое MUST-требование имеет acceptance criteria в формате Given/When/Then. Определяет scope (IN/OUT).
+
+### 02_research.md
+**Создаётся:** только L/XL (Step 2)
+
+Анализ паттернов в кодовой базе проекта и внешних аналогов. Помогает принять обоснованные архитектурные решения на следующем шаге.
+
+### 03_adr/*.md
+**Создаётся:** M+ (Step 3). Для M -- один ADR, для L/XL -- несколько.
+
+Architecture Decision Records. Каждый ADR -- отдельный файл в формате `001-<decision-slug>.md`. Подробнее -- в разделе [Работа с ADR](#7-работа-с-adr).
+
+### 04_domain_model.md
+**Создаётся:** только L/XL (Step 4)
+
+Domain-Driven Design модель: bounded contexts, ubiquitous language, агрегаты, связи. Для XL -- полная карта доменов.
+
+### 05_architecture.md
+**Создаётся:** M+ (Step 5). Для M -- light version.
+
+C4-диаграммы в Mermaid, описание API endpoints, sequence diagrams для ключевых flows. Подробнее -- в разделе [Работа с архитектурой](#8-работа-с-архитектурой).
+
+### 06_implementation_plan.md
+**Создаётся:** всегда (Step 6, для S-tier может быть inline)
+
+Декомпозиция на задачи с зависимостями. Каждая задача указывает: файлы, зависимости, критерий проверки. Задачи группируются в параллельные блоки.
+
+### 07_code_changes/change_manifest.md
+**Создаётся:** всегда (Step 7)
+
+Манифест всех изменённых файлов. Код пишется **непосредственно в репозитории**, а `change_manifest.md` описывает, что и где было изменено.
+
+### 08_qe_report.md
+**Создаётся:** всегда (Step 8)
+
+Отчёт Quality Engineering: результаты тестов, находки ревью, статус acceptance criteria, финальный вердикт. Подробнее -- в разделе [Работа с QE отчётом](#9-работа-с-qe-отчётом).
+
+### diagrams/
+**Создаётся:** M+ (Step 5)
+
+Mermaid-диаграммы: `architecture-c4.mermaid`, `sequence-*.mermaid`, `domain-model.mermaid` (L/XL).
+
+### README.md
+**Создаётся:** всегда (автоматически)
+
+Сводка по фиче: что было реализовано, какой tier, какие решения приняты, ссылки на артефакты.
+
+---
+
+## 7. Работа с ADR
+
+### Что такое ADR?
+
+**Architecture Decision Record** -- это документ, фиксирующий одно конкретное архитектурное решение. ADR отвечает на вопрос: "Почему мы выбрали именно этот подход, а не другой?"
+
+ADR -- не описание архитектуры (для этого есть Step 5). ADR -- это **обоснование выбора** с анализом альтернатив.
+
+### Структура ADR
+
+Каждый ADR содержит 7 секций:
+
+1. **Status** -- Proposed / Accepted / Deprecated / Superseded
+2. **Context** -- Описание проблемы и сил, действующих на решение
+3. **Decision Drivers** -- Факторы, определяющие выбор (техническая экспертиза команды, требования к latency, существующая инфраструктура)
+4. **Considered Options** -- Минимум 2 альтернативы, каждая с плюсами и минусами
+5. **Decision Matrix** -- Взвешенная таблица для нетривиальных решений
+6. **Decision** -- Выбранный вариант с обоснованием в 1-2 предложениях
+7. **Consequences** -- Позитивные, негативные последствия и риски с mitigation
+
+### Пример
+
+```
+ADR-001: Notification Delivery Strategy
+
+Context: Нужно доставлять уведомления email и in-app. Вопрос:
+синхронно или асинхронно?
+
+Option 1: Синхронная отправка
+  + Простая реализация
+  - Замедляет обновление статуса заказа
+  - Сбой email блокирует запрос
+
+Option 2: Асинхронная через job queue
+  + Не блокирует обработку заказов
+  + Retry при сбоях
+  + Использует существующую Bull queue инфраструктуру
+  - Небольшая задержка (допустима по требованиям)
+
+Decision: Option 2 -- соответствует event-driven архитектуре
+и укладывается в SLA 5 минут.
+```
+
+### Когда давать обратную связь на ADR
+
+Проверяйте ADR внимательно -- они определяют всё, что будет дальше (архитектуру, код, тесты). Обращайте внимание:
+
+- **Только 1 альтернатива?** -- Попросите добавить. Решение без альтернатив -- не решение.
+- **Нет негативных последствий?** -- Не бывает решений без trade-offs. Попросите добавить.
+- **Decision Drivers не релевантны?** -- Укажите правильные ограничения вашего проекта.
+- **Контекст не учитывает реальность?** -- Дайте обратную связь о существующей инфраструктуре или ограничениях команды.
+
+### ADR как живые документы
+
+ADR могут быть заменены (`Superseded by ADR-002`), если контекст изменился. Старый ADR не удаляется -- он остаётся как историческая справка.
+
+---
+
+## 8. Работа с архитектурой
+
+### C4 модель
+
+Step 5 использует C4-модель для описания архитектуры на нескольких уровнях абстракции:
+
+| Уровень | Что показывает | Когда создаётся |
+|---------|---------------|-----------------|
+| **System Context** | Ваша система + внешние системы и пользователи | L/XL |
+| **Container** | Приложения, базы данных, очереди внутри системы | L/XL |
+| **Component** | Компоненты внутри одного контейнера | M+ |
+
+Для **M-tier** создаётся только component diagram. Для **L/XL** -- полный C4.
+
+### Чтение Mermaid-диаграмм
+
+Все диаграммы создаются в формате Mermaid и сохраняются в `features/<slug>/diagrams/`. Для просмотра:
+
+- В VS Code: установите расширение "Mermaid Preview"
+- На GitHub: Mermaid рендерится автоматически в `.md` файлах
+- Онлайн: вставьте код в [mermaid.live](https://mermaid.live)
+
+### Sequence diagrams
+
+Для ключевых пользовательских сценариев создаются sequence-диаграммы, показывающие взаимодействие компонентов во времени. Они помогают понять: кто вызывает кого, в каком порядке, и где могут возникнуть проблемы.
+
+---
+
+## 9. Работа с QE отчётом
+
+QE (Quality Engineering) отчёт -- финальный артефакт pipeline. Он определяет, готова ли фича к merge.
+
+### Уровни серьёзности находок
+
+| Символ | Уровень | Значение | Действие |
+|--------|---------|----------|----------|
+| BLOCKER | Блокер | Нельзя мёржить | Обязательно исправить |
+| WARNING | Предупреждение | Нужно исправить | Исправить до следующего релиза |
+| SUGGESTION | Предложение | Хорошо бы сделать | Рассмотреть в будущем |
+| PRAISE | Похвала | Хорошо сделано | Действий не требуется |
+
+### Таблица acceptance criteria
+
+Каждое требование из Step 1 проверяется:
+
+| Статус | Значение |
+|--------|----------|
+| PASS | Требование выполнено, есть доказательство (тест, ручная проверка) |
+| FAIL | Требование не выполнено |
+| PARTIAL | Требование выполнено частично |
+
+### Вердикты
+
+| Вердикт | Что значит | Что делать |
+|---------|-----------|-----------|
+| **READY FOR MERGE** | Все MUST-требования пройдены, нет блокеров | Фича готова. Можно мёржить. |
+| **NEEDS FIXES** | Есть блокеры или непройденные MUST-требования | Исправить указанные проблемы и перезапустить QE |
+| **CONDITIONAL APPROVAL** | Нет блокеров, но есть warnings | Можно мёржить после исправления warnings |
+
+### Глубина QE по tier
+
+| Категория проверок | S | M | L | XL |
+|-------------------|---|---|---|-----|
+| Pre-implementation | -- | Частично | Полностью | Полностью |
+| Correctness | Smoke | Unit | Unit + Integration | Full |
+| Security | -- | Базовые | Полные | Full + Pentest |
+| Performance | -- | -- | Базовые | Full + Load |
+| Maintainability | -- | Базовые | Полные | Полные |
+| Compatibility | Smoke | Базовые | Полные | Полные |
+
+---
+
+## 10. Советы и best practices
+
+### Описание фичи
+
+Чем точнее описание, тем лучше результат. Сравните:
+
+```
+/feature-adr Добавить уведомления
+```
+
+```
+/feature-adr Добавить email и in-app уведомления при изменении
+статуса заказа. Использовать существующий SendGrid и Bull queue.
+Пользователь может настроить типы уведомлений в настройках.
+```
+
+Второй вариант даст Complexity Router больше контекста для точной классификации и лучшие requirements на Step 1.
+
+### Доверяйте Complexity Router
+
+Если Router определил tier L -- скорее всего, фича действительно сложнее, чем кажется на первый взгляд. Пропуск шагов (ADR, DDD, Research) для L/XL фич приводит к техническому долгу и переделкам.
+
+Конечно, вы всегда можете скорректировать tier на Checkpoint 0, если у вас есть основания.
+
+### Ревьюте ADR внимательно
+
+ADR на Step 3 определяют направление для Steps 4-7. Если ADR содержит неверное решение, весь последующий код будет строиться на неверном фундаменте. Лучше потратить 5 минут на обратную связь по ADR, чем переделывать код.
+
+### Используйте checkpoints активно
+
+Checkpoints -- не просто формальность. Это ваш инструмент для управления качеством:
+
+- Видите, что requirements неполные? Скажите "углуби requirements" и укажите, что упущено.
+- Считаете, что архитектура переусложнена? Дайте обратную связь: "упрости, уберите отдельный сервис X".
+- Хотите добавить интеграцию, которая не была учтена? Скажите об этом на Checkpoint 1 или 3.
+
+### Сохраняйте features/ как документацию
+
+Директория `features/<slug>/` -- это не мусор после генерации. Это **живая документация** вашей фичи:
+
+- ADR объясняют "почему" для новых участников команды
+- Architecture diagrams помогают при onboarding
+- QE report показывает, что было проверено
+- Implementation plan полезен при планировании аналогичных фич
+
+---
+
+## 11. FAQ
+
+### Можно ли пропустить шаги?
+
+Нет. Tier определяет, какие шаги активны, и вы не можете пропустить активный шаг. Если вам кажется, что шаг лишний -- скорее всего, нужен другой tier. Скорректируйте его на Checkpoint 0.
+
+### Можно ли изменить tier в процессе?
+
+Нет. Tier фиксируется после подтверждения на Checkpoint 0 и не меняется до конца pipeline. Если scope фичи существенно изменился -- перезапустите pipeline с обновлённым описанием.
+
+### Куда попадают изменения кода?
+
+Код пишется **непосредственно в вашем репозитории**, а не только в `features/`. Директория `features/<slug>/07_code_changes/change_manifest.md` содержит список всех изменённых файлов, но сами изменения -- в вашем рабочем дереве.
+
+### Нужен ли @dzhechkov/keysarium-core?
+
+Нет, Feature ADR работает автономно. Пакет `keysarium-core` предоставляет расширенные протоколы governance (witness chain, reward learning, dream engine), но они не обязательны для работы pipeline.
+
+### Можно ли кастомизировать шаги?
+
+Да. Каждый шаг определён в отдельном модуле (`modules/00-08`). Вы можете отредактировать их, чтобы адаптировать под свой workflow. Например:
+
+- Добавить специфические проверки в Step 8 (QE)
+- Изменить шаблон ADR в `references/adr-template.md`
+- Настроить критерии классификации в `references/complexity-matrix.md`
+
+### Как запускать несколько фич параллельно?
+
+Запускайте отдельные вызовы `/feature-adr` -- каждый создаёт изолированную директорию `features/<slug>/`. Фичи не пересекаются и не конфликтуют на уровне артефактов. Конфликты в коде (Step 7) разрешаются стандартными средствами git.
+
+### Чем Feature ADR отличается от /casarium?
+
+`/casarium` -- это исследовательский pipeline для AI-кейсов на хакатонах (discovery, research, CJM-прототип, презентация). `/feature-adr` -- это pipeline разработки: от требований до кода и тестов. Они используют общие скиллы, но решают разные задачи.
+
+| Свойство | /feature-adr | /casarium |
+|----------|-------------|-----------|
+| Результат | Код в репозитории | Презентация + документы |
+| Артефакты | `features/<slug>/` | `researches/<slug>/` |
+| Шаги | 9 (0-8) | 7 фаз (0-6) |
+| CJM-прототип | Нет | Обязателен (Phase 2.5) |
+| ADR | Да | Нет |
+| QE | Да | Нет |
+
+### Какие скиллы используются внутри?
+
+| Скилл | Где используется | Назначение |
+|-------|-----------------|-----------|
+| `explore` | Step 1 | Кларификация и сбор требований |
+| `problem-solver-enhanced` | Step 3 | Trade-off анализ для ADR (TRIZ + Game Theory) |
+| `frontend-design` | Step 7 | UI-реализация (если фича имеет интерфейс) |
+
+### Что такое promise tags?
+
+Promise tags -- это машиночитаемые маркеры завершения шага. Они используются для формальной валидации: downstream-шаги проверяют, что upstream-шаги завершены. Вам не нужно взаимодействовать с ними напрямую -- система управляет ими автоматически.
+
+| Шаг | Promise Tag |
+|-----|-------------|
+| 0 | `FEATURE_ADR_ROUTED` |
+| 1 | `FEATURE_ADR_REQUIREMENTS_GATHERED` |
+| 2-5 | `FEATURE_ADR_DESIGNED` |
+| 6 | `FEATURE_ADR_PLANNED` |
+| 7 | `FEATURE_ADR_IMPLEMENTED` |
+| 8 | `FEATURE_ADR_VERIFIED` |