Specification review: analyze specs for gaps, inconsistencies, and scope estimation

GitHub stars
17

Install

/plugin install spec-reviewer@dapi

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dapi/claude-code-marketplace.

Contents

Discovered from source

Skills 1

Spec Review Skill

Роутер для ревью спецификаций. Определяет источник и уровень глубины, затем ВЫЗЫВАЕТ команду /spec-review через Skill tool.

КРИТИЧЕСКИ ВАЖНО

Эта skill — роутер. Твоя задача:

  1. Извлечь источник (URL, path, #number) из ОРИГИНАЛЬНОГО сообщения пользователя
  2. Определить уровень глубины (флаги или ключевые слова)
  3. Вызвать Skill tool с skill: "spec-review" и корректным args

НЕ выводи текст описывающий вызов. ВЫПОЛНИ вызов через Skill tool. НЕ теряй URL/path из оригинального сообщения пользователя.

Алгоритм

1. Извлечь источник из сообщения пользователя

Найди в ОРИГИНАЛЬНОМ сообщении пользователя (до загрузки этого скилла) один из:

ТипПаттернПример args
Google Docdocs.google.com/document/d/...https://docs.google.com/document/d/1abc123/edit
GitHub Issuegithub.com/.../issues/N или #N с ревью-контекстомhttps://github.com/org/repo/issues/42
Docmosthttps://{domain}/p/{pageId}https://docs.company.com/p/3f6f2b9d
Локальный файлпуть к файлуdocs/spec.md
Текст в сообщениибольшой блок текста (>500 символов)(пустая строка)

GitHub Issue: активируй ТОЛЬКО при ревью-контексте (слова: "проверь", "ревью", "review", "analyze", "проанализируй", "спеку", "ТЗ"). Без ревью-контекста — это github-issues или task-routing.

2. Определить уровень глубины

Явные флаги (приоритет):

ФлагСиноним
--quick-q
--standard-s
--deep-d
--exhaustive-e
--no-ask(доп. флаг, совместим с любым уровнем)

Ключевые слова (если нет флага):

  • "быстро", "только критичное", "только блокеры" -> --quick
  • "тщательно", "подробно", "глубоко", "детально" -> --deep
  • "полный аудит", "исчерпывающий", "всё проверить" -> --exhaustive

3. Собрать args и вызвать Skill tool

Формат args: [depth_flag] [--no-ask] <source>

Примеры готовых args:

  • https://github.com/org/repo/issues/42
  • --quick #42
  • --deep docs/spec.md
  • --exhaustive https://docs.google.com/document/d/xxx
  • --no-ask #42
  • (пустая строка, если текст спецификации в сообщении)

Теперь вызови Skill tool с skill: "spec-review" и собранным args.

Commands 1

Spec Review Command

Комплексное ревью спецификации с параллельным техническим, бизнес и scope-анализом. Итеративный процесс до устранения всех критичных и высоких замечаний.

┌───────────────────────────────────────────────────────────────────────────┐
│                              /spec-review                                  │
│             [--quick|-q|--standard|-s|--deep|-d|--exhaustive|-e|--no-ask]  │
└─────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
                       ┌─────────────────────┐
                       │   Фаза 0.5:         │
                       │   Уровень глубины   │
                       │   (flags/keywords)  │
                       └──────────┬──────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
                    ▼             ▼             ▼
             ┌───────────┐ ┌───────────┐ ┌───────────┐
             │  quick    │ │ standard/ │ │exhaustive │
             │ 2 агента  │ │   deep    │ │ 9 агентов │
             │ skip cls  │ │ classifier│ │ все безусл│
             └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
                   │             │             │
                   └─────────────┼─────────────┘
                                 │
                                 ▼
                       ┌─────────────────────┐
                       │   Фаза 1.5:         │
                       │   spec-classifier   │
                       │   (haiku, ~500 tok) │
                       │   [skip if quick]   │
                       └──────────┬──────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    │  1. Какие агенты нужны    │
                    │  2. Quick scope: влезает? │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    │   too_large/borderline?   │
                    └─────────────┬─────────────┘
                           ДА    │    НЕТ
                    ┌────────────┴────────────┐
                    ▼                         ▼
          ┌─────────────────┐      ┌─────────────────┐
          │ Спросить юзера: │      │ Продолжить      │
          │ разбить/продолж │      │ Фазу 2          │
          └─────────────────┘      └─────────────────┘
                                  │
    ┌─────────┬─────────┬─────────┼─────────┬─────────┬─────────┬─────────┐
    │         │         │         │         │         │         │         │
    ▼         ▼         ▼         ▼         ▼         ▼         ▼         ▼
┌───────┐┌───────┐┌───────┐┌───────┐┌───────┐┌───────┐┌───────┐┌─────────┐
│ data  ││  api  ││ infra ││analyst││scoper ││ test  ││ risk  ││   ux    │
│ DAT-* ││ API-* ││ INF-* ││ BIZ-* ││ scope ││ TST-* ││ RSK-* ││  UX-*   │
│ усл.  ││ усл.  ││ усл.  ││ВСЕГДА ││ВСЕГДА ││ВСЕГДА ││ усл.  ││  усл.   │
└───┬───┘└───┬───┘└───┬───┘└───┬───┘└───┬───┘└───┬───┘└───┬───┘└────┬────┘
    │        │        │        │        │        │        │         │
    │        │   ПАРАЛЛЕЛЬНО (2 обязат. + 0-8 условных)   │         │
    └────────┴────────┴────────┴────────┴────────┴────────┴─────────┘
                                     │
                                     ▼
                          ┌─────────────────┐
                          │   Объединение   │
                          │   результатов   │
                          └────────┬────────┘
                                   │
          ┌────────────────────────┴────────────────────────┐
          │                                                 │
          ▼                                                 ▼
   ┌─────────────┐                                  ┌─────────────┐
   │  Проблемы   │                                  │   Scope     │
   │  качества   │                                  │  (разбиение)│
   └──────┬──────┘                                  └──────┬──────┘
          │                                                │
          └────────────────────┬───────────────────────────┘
                               │
                               ▼
                    ┌─────────────────┐
                    │    Фаза 6:      │◄──────────────────────────┐
                    │    Аппрув       │                           │
                    └────────┬────────┘                           │
                             │                                    │
                             ▼                                    │
                    ┌─────────────────┐                           │
                    │   GATE CHECK    │                           │
                    │ critical/high?  │                           │
                    └────────┬────────┘                           │
                             │                                    │
               ┌─────────────┴─────────────┐                      │
               │                           │                      │
               ▼                           ▼                      │
        ┌───────────┐              ┌───────────┐                  │
        │  ✅ НЕТ   │              │  ⚠️ ДА    │                  │
        │  (чисто)  │              │  (есть)   │                  │
        └─────┬─────┘              └─────┬─────┘                  │
              │                          │                        │
              ▼                          ▼                        │
        ┌───────────┐         ┌──────────────────┐                │
        │  Фаза 7   │         │  AskUserQuestion │                │
        │  ФИНАЛ    │         │  4 варианта      │                │
        └───────────┘         └────────┬─────────┘                │
                                       │                          │
              ┌────────────────┬───────┴───────┬──────────────┐   │
              │                │               │              │   │
              ▼                ▼               ▼              ▼   │
        ┌───────────┐   ┌───────────┐   ┌───────────┐  ┌─────────┐│
        │ Обработ.│   │ Полный  │   │✅ Принять │  │❌ Отмена││
        │индивидуал.│   │ре-анализ  │   │ как есть  │  │         ││
        └─────┬─────┘   └─────┬─────┘   └─────┬─────┘  └─────────┘│
              │               │               │                   │
              │               │               ▼                   │
              │               │         ┌───────────┐             │
              │               │         │  Фаза 7   │             │
              │               │         │ + warning │             │
              │               │         └───────────┘             │
              │               │                                   │
              │               └──────► Фаза 2 ◄───────────────────┘
              │                      (re-analyze)
              │
              └──────────────────────────► Фаза 6 ─────────────────┘
                                         (для каждой проблемы)

Критерии качества

КритерийСимволЧто проверяем
Гапы️Отсутствующая информация
Нестыковки⚡Противоречия между разделами
НеоднозначностьДвойные толкования
НепроверяемостьСубъективные критерии
НереализуемостьТехнически невозможно
НетестируемостьНевозможно написать тесты

Переменные состояния

VERSION = "1.11.0"                # Версия команды (синхронизирована с frontmatter)
iteration = 1                    # Текущая итерация (начинаем с 1)
spec_content = ""                # Текст спецификации
issues_history = []              # История проблем по итерациям

# Уровни глубины (NEW in 1.9.0)
depth_level = "standard"         # quick | standard | deep | exhaustive
min_severity = "high"            # critical | high | medium | low
no_ask = False                   # True если указан --no-ask
max_iterations = {               # Зависит от уровня
  "quick": 1,
  "standard": 2,
  "deep": 3,
  "exhaustive": 3
}

# Маппинг уровней
DEPTH_CONFIG = {
  "quick": {
    "min_severity": "critical",
    "max_iterations": 1,
    "run_classifier": False,
    "gate_check": False,
    "scope_analysis": False,
    "agents": "mandatory_only"  # 2 агента
  },
  "standard": {
    "min_severity": "high",
    "max_iterations": 2,
    "run_classifier": True,
    "gate_check": True,
    "scope_analysis": True,
    "agents": "by_classifier"
  },
  "deep": {
    "min_severity": "medium",
    "max_iterations": 3,
    "run_classifier": True,
    "gate_check": True,
    "scope_analysis": True,
    "agents": "by_classifier"
  },
  "exhaustive": {
    "min_severity": "low",
    "max_iterations": 3,
    "run_classifier": True,
    "gate_check": True,
    "scope_analysis": True,
    "agents": "all"  # все 9 агентов
  }
}

Фаза 0.5: Определение уровня глубины (NEW in 1.9.0)

Парсинг аргументов

# $ARGUMENTS = "--quick https://docs.google.com/..." или "-d #42" и т.д.

# 1. Извлечь флаги уровня
flags = extract_flags($ARGUMENTS)  # --quick, -q, --deep, -d, --exhaustive, -e, --no-ask

# 2. Проверить флаги
if unknown_flag in flags:
    # EH-1: Неизвестный флаг
    error("❌ Неизвестный уровень {flag}. Доступные: --quick, --standard, --deep, --exhaustive")
    if levenshtein_distance(flag, known_flags) <= 2:
        hint(" Возможно вы имели в виду {closest_flag}?")
    return

if multiple_depth_flags(flags):
    # EH-1: Несколько флагов
    warning("⚠️ Указано несколько уровней, используется {deepest_flag}")
    depth_level = get_deepest(flags)  # quick < standard < deep < exhaustive

# 3. Проверить --no-ask
no_ask = "--no-ask" in flags

# 4. Убрать флаги из аргументов, оставить только источник
source_arg = remove_flags($ARGUMENTS)

Определение уровня

# Приоритет 1: Явный флаг
if "--quick" in flags or "-q" in flags:
    depth_level = "quick"
elif "--standard" in flags or "-s" in flags:
    depth_level = "standard"
elif "--deep" in flags or "-d" in flags:
    depth_level = "deep"
elif "--exhaustive" in flags or "-e" in flags:
    depth_level = "exhaustive"

# Приоритет 2: Ключевые слова в промпте (если нет флага)
elif depth_level is None:
    keywords_quick = ["быстро", "quick", "только критичное", "блокеры", "только блокеры"]
    keywords_deep = ["тщательно", "подробно", "deep", "детально", "глубоко", "глубокий анализ"]
    keywords_exhaustive = ["полный аудит", "exhaustive", "исчерпывающий", "всё проверить", "проверить всё"]

    prompt_text = user_message.lower()

    if any(kw in prompt_text for kw in keywords_exhaustive):
        depth_level = "exhaustive"
    elif any(kw in prompt_text for kw in keywords_deep):
        depth_level = "deep"
    elif any(kw in prompt_text for kw in keywords_quick):
        depth_level = "quick"
    elif has_conflicting_keywords(prompt_text):
        # EH-4: "быстро и тщательно" → спросить
        depth_level = None  # будет AskUserQuestion

# Приоритет 3: AskUserQuestion (если не определено и не --no-ask)
if depth_level is None and not no_ask:
    depth_level = ask_depth_level()  # см. ниже

# Приоритет 4: Default (если --no-ask или timeout)
if depth_level is None:
    depth_level = "standard"
    if no_ask:
        info(" Используется стандартный уровень (--no-ask)")

AskUserQuestion: Выбор уровня глубины

## Выбери уровень глубины ревью

Варианты:

  1. ⚡ Быстрый — только критические блокеры (~2 мин, 2 агента)
  2. ** Стандартный (рекомендуется)** — критические + высокие
  3. ** Глубокий** — все проблемы включая средние
  4. ** Исчерпывающий** — полный аудит с рекомендациями (все 9 агентов)

Обработка ответа:

  • Таймаут 60 сек → использовать standard
  • Невалидный ответ → переспросить до 2 раз → standard
  • Отмена/закрытие → standard с warning

Применение конфигурации уровня

config = DEPTH_CONFIG[depth_level]
min_severity = config["min_severity"]
max_iterations = config["max_iterations"]
run_classifier = config["run_classifier"]
gate_check_enabled = config["gate_check"]
scope_analysis_enabled = config["scope_analysis"]
agent_mode = config["agents"]

# Показать выбранный уровень
info(f"️ Уровень: {depth_level} | Показываются: severity ≥ {min_severity}")

Фаза 1: Получение спецификации

Источники

ИсточникКак получить
Google DocMCP: mcp__google_workspace__get_doc_content
Google SpreadsheetMCP: mcp__google_workspace__read_sheet_values
GitHub IssueCLI: gh issue view <number> --json body,title
Docmost pageMCP: mcp__docmost__docmost-get_page (primary), fallback mcp__docmost__docmost-search
Локальный файлTool: Read

Аргумент команды: $ARGUMENTS

  • Если пусто — спроси: "Укажи ссылку на Google Doc / Docmost, номер GitHub issue или путь к файлу"

Извлечение ID:

  • Google Doc: https://docs.google.com/document/d/{DOCUMENT_ID}/edit → {DOCUMENT_ID}
  • GitHub Issue: https://github.com/{owner}/{repo}/issues/{number} → gh issue view {number}
  • Docmost:
    • если URL на известном Docmost-домене и содержит /p/{pageId} или /pages/{pageId} → извлечь {pageId} и вызвать mcp__docmost__docmost-get_page
    • если pageId не извлекается → попытаться найти страницу через mcp__docmost__docmost-search (по slug/title из URL), затем mcp__docmost__docmost-get_page
    • если тип URL сомнителен → открыть ссылку и проверить, что это Docmost, после чего читать через MCP Docmost

Фаза 1.5: Классификация + Quick Scope (haiku)

Цель:

  1. Определить какие субагенты нужны
  2. Быстро оценить объём — влезает ли в одну сессию

Экономия: Вместо 8 агентов запускаем 2-7 в среднем.

Условие запуска (зависит от depth_level)

if depth_level == "quick":
    # Пропустить classifier полностью
    agents_to_run = ["spec-analyst", "spec-test"]  # только 2 обязательных
    skip_to_phase_2()

elif depth_level == "exhaustive":
    # Запустить classifier для scope analysis, но агенты = все
    run_classifier_for_scope_only = True
    agents_to_run = ALL_9_AGENTS  # все агенты безусловно

else:  # standard или deep
    # Полный classifier
    run_classifier()

Запуск classifier

Task:
  subagent_type: "spec-reviewer:spec-classifier"
  model: "haiku"
  description: "Классификация спецификации"
  prompt: |
    Проанализируй спецификацию и определи:
    1. Какие аспекты присутствуют (для выбора агентов)
    2. Предварительную оценку объёма (quick scope)

    Верни ТОЛЬКО JSON без markdown formatting.

    Критерии классификации:
    - has_data_model: есть модели данных, БД, сущности, миграции
    - has_api: есть API, endpoints, интеграции, webhooks
    - has_infra_requirements: есть требования к deployment, безопасности, производительности
    - has_risks: критичная фича, миграции, внешние зависимости, новые технологии
    - has_ui: есть UI, экраны, формы, user flows

    Критерии оценки объёма:
    - verdict: "fits" (1-3 модели), "borderline" (4-6), "too_large" (7+)
    - complexity: S/M/L/XL

    При сомнении в классификации — ставь true.
    При сомнении в объёме — ставь более крупный verdict.

    === СПЕЦИФИКАЦИЯ ===
    {spec_content}
    === КОНЕЦ ===

Результат классификации

{
  "classification": {
    "has_data_model": true,
    "has_api": true,
    "has_infra_requirements": false,
    "has_risks": true,
    "has_ui": false
  },
  "quick_scope": {
    "verdict": "fits",
    "complexity": "M",
    "estimated_elements": { "models": 2, "endpoints": 5 },
    "scope_reasoning": "Две модели с CRUD — стандартная задача"
  },
  "agents_to_run": ["spec-data", "spec-api", "spec-risk"]
}

Обработка Quick Scope

IF quick_scope.verdict == "too_large":
    → Показать пользователю оценку
    → AskUserQuestion: разбить на части или продолжить?
    → Если разбить → запустить spec-scoper (sonnet) для детального breakdown
    → Если продолжить → добавить warning и перейти к Фазе 2

ELIF quick_scope.verdict == "borderline":
    → Показать предупреждение
    → Спросить: нужен ли детальный breakdown?
    → Если да → запустить spec-scoper
    → Если нет → продолжить Фазу 2

ELSE (verdict == "fits"):
    → Сразу перейти к Фазе 2
    → НЕ запускать spec-scoper

AskUserQuestion: Scope слишком большой

## ⚠️ Спецификация слишком большая для одной сессии

**Оценка:** {complexity} ({estimated_elements.models} моделей, {estimated_elements.endpoints} endpoints)
**Причина:** {scope_reasoning}

Варианты:

  1. ** Получить детальный breakdown и разбить** → Запустить spec-scoper (sonnet) для детального анализа → Предложить план разбиения на части

  2. ⚡ Продолжить без разбиения (риск!) → Добавить warning в отчёт → Продолжить ревью целиком

  3. ❌ Отменить ревью → Пользователь сам разобьёт спецификацию

Маппинг classification → agents

ФлагАгентКогда true
has_data_modelspec-dataМодели, БД, миграции
has_apispec-apiAPI, endpoints, интеграции
has_infra_requirementsspec-infraDeployment, безопасность
has_risksspec-riskКритичность, зависимости
has_uispec-uxUI, экраны, формы
has_ai_executionspec-ai-readinessAI/LLM агенты, боты, автоматизация

Всегда запускаются (не зависят от классификации):

  • spec-analyst — бизнес-логика есть в любой спеке
  • spec-test — тестируемость универсально полезна

Опционально (только по запросу):

  • spec-scoper — детальный breakdown (если quick_scope != "fits")

Условный standard+ (не зависит от classifier):

  • spec-axes -- проверка покрытия по трём осям (standard, deep, exhaustive)

Фаза 2: Параллельный анализ

КРИТИЧЕСКИ ВАЖНО: Запуск субагентов

Используй Task tool для запуска агентов ОДНОВРЕМЕННО в ОДНОМ сообщении.

Запускать на основе результатов Фазы 1.5:

  • 2 обязательных агента (всегда)
  • 0-1 условных standard+ (spec-axes, если depth_level != "quick")
  • 0-6 условных агентов (по результатам classifier)
  • spec-scoper (только если quick_scope != "fits")

Обязательные агенты (ВСЕГДА запускать — 2 штуки):
Task: spec-analyst (ОБЯЗАТЕЛЬНЫЙ)
  subagent_type: "spec-reviewer:spec-analyst"
  description: "Бизнес-анализ спецификации"
  prompt: |
    Проанализируй спецификацию с бизнес точки зрения:
    user stories, acceptance criteria, роли, права доступа.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-test (ОБЯЗАТЕЛЬНЫЙ)
  subagent_type: "spec-reviewer:spec-test"
  description: "Анализ тестируемости спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения тестируемости:
    можно ли написать тесты, какие test cases очевидны,
    что сложно протестировать, где неоднозначности.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Условный standard+ агент (запускать если depth_level >= standard):
Task: spec-axes (если depth_level != "quick")
  subagent_type: "spec-reviewer:spec-axes"
  description: "Проверка покрытия по трём осям"
  prompt: |
    Проанализируй спецификацию и для каждой фичи/функции
    проверь покрытие по трём осям:
    1. Что строим (User Story, AC, бизнес-контекст)
    2. Как строим (ERD, API, архитектура, C4)
    3. Как проверяем (Test Plan, test cases, AC с метриками)
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Условные агенты (запускать по результатам classifier):
Task: spec-data (если has_data_model == true)
  subagent_type: "spec-reviewer:spec-data"
  description: "Анализ данных спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения данных:
    модели, схемы БД, миграции, связи, валидация.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-api (если has_api == true)
  subagent_type: "spec-reviewer:spec-api"
  description: "Анализ API спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения API:
    endpoints, контракты, интеграции, webhooks, error handling.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-infra (если has_infra_requirements == true)
  subagent_type: "spec-reviewer:spec-infra"
  description: "Анализ инфраструктуры спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения инфраструктуры:
    безопасность, производительность, deployment, мониторинг.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-risk (если has_risks == true)
  subagent_type: "spec-reviewer:spec-risk"
  description: "Анализ рисков спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения рисков:
    технические, бизнес, операционные риски,
    что может пойти не так, mitigation strategies.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-ux (если has_ui == true)
  subagent_type: "spec-reviewer:spec-ux"
  description: "UX/UI анализ спецификации"
  prompt: |
    Проанализируй спецификацию с точки зрения UX/UI:
    user flows, UI states, edge cases в интерфейсе,
    accessibility, responsive design.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-ai-readiness (если has_ai_execution == true)
  subagent_type: "spec-reviewer:spec-ai-readiness"
  description: "Анализ готовности спецификации для AI-агентов"
  prompt: |
    Проанализируй спецификацию с точки зрения готовности
    к выполнению AI-агентами: достаточность контекста,
    наличие примеров, границы автономности, точки эскалации,
    критерии успеха, обработка ошибок.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Task: spec-scoper (если quick_scope.verdict != "fits")
  subagent_type: "spec-reviewer:spec-scoper"
  description: "Детальный breakdown спецификации"
  prompt: |
    Оцени объём работы по спецификации.
    Предложи разбиение на части с зависимостями.
    Верни результат в формате JSON.

    === СПЕЦИФИКАЦИЯ ===
    {полный текст спецификации}
    === КОНЕЦ СПЕЦИФИКАЦИИ ===

Все Task вызовы должны быть в ОДНОМ сообщении для параллельного выполнения! Минимум 2 агента (обязательные), максимум 10 (все).

Пример: какие агенты запускать

Quick ScopeClassificationЗапускаемые агентыВсего
fits, всё false-analyst, test2
fits, has_api=true-analyst, test, api3
fits, has_data+api-analyst, test, data, api4
fits, has_ai_execution-analyst, test, ai-readiness3
borderline, всё trueнужен breakdownanalyst, test, axes, data, api, infra, risk, ux, ai-readiness, scoper10
too_large, всё trueнужен breakdownanalyst, test, axes, data, api, infra, risk, ux, ai-readiness, scoper10

Фаза 3: Объединение результатов

После получения JSON от всех запущенных субагентов (2-10):

3.1 Парсинг результатов

data_result = JSON.parse(data_output)       # DAT-TYPE-XXX issues
api_result = JSON.parse(api_output)         # API-TYPE-XXX issues
infra_result = JSON.parse(infra_output)     # INF-TYPE-XXX issues
analyst_result = JSON.parse(analyst_output) # BIZ-TYPE-XXX issues
scoper_result = JSON.parse(scoper_output)   # scope analysis
test_result = JSON.parse(test_output)       # TST-TYPE-XXX issues
risk_result = JSON.parse(risk_output)       # RSK-TYPE-XXX issues
ux_result = JSON.parse(ux_output)           # UX-TYPE-XXX issues (если запускался)
ai_result = JSON.parse(ai_output)           # AI-TYPE-XXX issues (если запускался)
axes_result = JSON.parse(axes_output)     # AXS-TYPE-XXX issues (если запускался)

3.2 Объединение issues (качество)

all_issues = data_result.issues
           + api_result.issues
           + infra_result.issues
           + analyst_result.issues
           + test_result.issues
           + risk_result.issues
           + (ux_result.issues если запускался spec-ux)
           + (ai_result.issues если запускался spec-ai-readiness)
           + (axes_result.issues если запускался spec-axes)

3.2.1 Фильтрация ранее обработанных issues (NEW in 1.11.0)

# При повторных итерациях — исключить issues, уже обработанные пользователем.
# Это предотвращает повторный показ rejected/deferred/fixed issues в следующих итерациях.
if iteration > 1:
    previously_resolved_ids = {
        issue.id
        for issue in issues_history
        if issue.status in ["rejected", "deferred", "fixed", "reclassified"]
    }
    # Удалить из all_issues — агенты не знают о решениях предыдущих итераций
    all_issues = [i for i in all_issues if i.id not in previously_resolved_ids]

    # Для reclassified — сохранить issue, но взять severity из issues_history
    # (агент мог вернуть старый severity после ре-анализа)
    reclassified = {
        issue.id: issue.severity
        for issue in issues_history
        if issue.status == "reclassified"
    }
    for issue in all_issues:
        if issue.id in reclassified:
            issue.severity = reclassified[issue.id]  # сохранить пониженный severity

3.3 Сортировка по severity

Порядок: critical → high → medium → low

3.3.1 Фильтрация по уровню глубины (NEW in 1.9.0)

# Фильтрация по min_severity
severity_order = ["critical", "high", "medium", "low"]
min_index = severity_order.index(min_severity)

# Разделение на показываемые и скрытые
filtered_issues = [i for i in all_issues
                   if severity_order.index(i.severity) <= min_index]
hidden_issues = [i for i in all_issues
                 if severity_order.index(i.severity) > min_index]

# Подсчёт скрытых по severity
hidden_by_severity = {
    sev: count(hidden_issues where severity == sev)
    for sev in severity_order[min_index + 1:]
}

3.4 Формирование сводки качества

quality_summary = {
  critical: count(severity == "critical"),
  high: count(severity == "high"),
  medium: count(severity == "medium"),
  low: count(severity == "low")
}

3.5 Анализ scope

scope_verdict = scoper_result.verdict  // "fits" | "borderline" | "too_large"
breakdown = scoper_result.breakdown
suggested_plan = scoper_result.suggested_plan

Фаза 4: Обработка Scope (если too_large/borderline)

Если verdict: "too_large" или verdict: "borderline"

Показать пользователю breakdown и запросить решение:

##  Оценка объёма спецификации

**Verdict:** ⚠️ Слишком большая / ⚡ На грани
**Estimated complexity:** XL
**Элементы:** N моделей, M endpoints, K компонентов

### Предлагаемое разбиение

| # | Часть | Сложность | Зависит от | Рекомендация |
|---|-------|-----------|------------|--------------|
| 1 | {title} | M | - | ✅ Фаза 1 |
| 2 | {title} | L | #1 | ✅ Фаза 2 |
| 3 | {title} | XL | #1, #2 |  Sub-issue |

### Граф зависимостей

PART-001 ──► PART-002 ──► PART-003
                └──────────► PART-004

AskUserQuestion: Что делать со scope?

  1. ✅ Принять разбиение → Создать sub-issues для out_of_scope частей → Обновить спецификацию с планом фаз

  2. ** Скорректировать вручную** → Запросить какие части перенести/оставить

  3. ⏭️ Игнорировать (риск!) → Продолжить без разбиения → Добавить warning в отчёт

Создание Sub-issues для out_of_scope частей

Для каждой части с recommendation: "out_of_scope_subissue":

gh issue create \
  --repo {owner}/{repo} \
  --title "[Part {id}] {title}" \
  --body "$(cat <<'EOF'
## Контекст
Выделено из спецификации: {ссылка на основную спеку}
Parent issue: #{parent_issue_number}

## Scope
{список элементов из scope}

## Сложность: {complexity}

## Зависимости
{depends_on или "Нет"}

## Описание
{description}

---
_Spec Review | {дата}_
EOF
)"

Обновление основной спецификации

Если пользователь принял разбиение, добавить в документ:

## План реализации

### Фаза 1 (текущая задача)
- [ ] {PART-001 title}
- [ ] {PART-002 title}

### Вынесено в отдельные задачи
- [ ] {PART-003 title} → #{issue_number}
- [ ] {PART-004 title} → #{issue_number}

Фаза 5: Презентация результатов

Формат отчёта

##  Результаты ревью спецификации

**Документ:** [название/ссылка]
**Дата ревью:** [дата]
**Уровень:** ⚡ Quick |  Standard |  Deep |  Exhaustive
**Показаны проблемы:** severity ≥ {min_severity}
**Итерация:** {iteration} из {max_iterations}
**Агентов запущено:** {agents_count} из 10
**Статус:** ⏳ Требует доработки / ✅ Готова к аппруву

---

###  Оценка объёма

| Verdict | Complexity | Модели | Endpoints | Компоненты |
|---------|------------|--------|-----------|------------|
| ✅ Влезает / ⚠️ На грани / ❌ Слишком большая | S/M/L/XL | N | N | N |

**План реализации:** [Фаза 1: X, Фаза 2: Y] | [Sub-issues: #N, #M]

---

### Покрытие по трём осям (если запускался spec-axes)

| Фича | Что (PRD/US/AC) | Как (ERD/API/C4) | Проверка (Tests/AC) |
|------|-----------------|-------------------|---------------------|
| {feature.name} | {[OK]/[!]} {artifacts} | {[OK]/[!]} {artifacts} | {[OK]/[!]} {artifacts} |

**Полностью покрыты:** {fully_covered}/{total_features} ({percent}%)
**Частично:** {partially_covered}/{total_features}
**Без покрытия:** {not_covered}/{total_features}

---

###  Качество спецификации

| Источник |  Крит. |  Выс. |  Сред. |  Низ. |
|----------|----------|---------|----------|---------|
| ️ Data (DAT-*) | N | N | N | N |
|  API (API-*) | N | N | N | N |
| ️ Infra (INF-*) | N | N | N | N |
|  Analyst (BIZ-*) | N | N | N | N |
|  Test (TST-*) | N | N | N | N |
| ⚠️ Risk (RSK-*) | N | N | N | N |
|  UX (UX-*) | N | N | N | N |
|  AI-Readiness (AI-*) | N | N | N | N |
| Axes (AXS-*) | N | N | N | N |
| **Итого** | **N** | **N** | **N** | **N** |

*UX и AI-Readiness показываются только если соответствующие агенты были запущены*
*Axes показывается только если depth_level >= standard*

###  Критичные проблемы
[список]

###  Высокие проблемы
[список]

###  Средние проблемы
[список]

###  Рекомендации
[список]

### ℹ️ Скрыто на текущем уровне (если есть hidden_issues)
-  Medium: {N} проблем
-  Low: {M} рекомендаций

<details>
<summary>Заголовки скрытых проблем</summary>

- [{id}] {title}
- ...
</details>

> Для полного списка используй `--deep` или `--exhaustive`

Empty state (если filtered_issues пуст)

✅ На уровне {depth_level} проблем категории {min_severity} и выше не найдено.

Для более детального анализа используйте:
- `--standard` — покажет высокие проблемы
- `--deep` — покажет все проблемы включая средние
- `--exhaustive` — полный аудит с рекомендациями

Если iteration > 1: Показать прогресс

---

###  Прогресс между итерациями

| Итерация |  Крит. |  Выс. |  Сред. |  Низ. | Δ |
|----------|----------|---------|----------|---------|---|
| #1 | 3 | 5 | 4 | 2 | - |
| #2 | 1 | 2 | 4 | 2 | ✅ -5 |
| #3 (текущая) | 0 | 0 | 3 | 2 | ✅ -3 |

**Устранено за все итерации:** 8 критичных/высоких проблем

Фаза 6: Процесс аппрува

Для каждого замечания (начиная с критичных)

Используй AskUserQuestion с вариантами:

  1. ✅ Принять и учесть в ТЗ → Сформулировать изменения → внести в документ

  2. ** Вынести в отдельную задачу** → Создать GitHub issue через gh issue create

  3. ** Свое решение** → Пользователь формулирует кастомное решение → Зафиксировать rationale в спецификации/отчёте → Сопоставить с одним из статусов: fixed | deferred | reclassified | rejected

  4. ⏭️ Отклонить → Запросить причину → добавить комментарий в спецификацию

Создание GitHub issue для отложенного замечания

gh issue create \
  --repo {owner}/{repo} \
  --title "[Spec Review] {title}" \
  --body "$(cat <<'EOF'
## Контекст
Выявлено в ходе ревью: {ссылка на спеку}

## Тип: {type_emoji} {type}
## Severity: {severity_emoji} {severity}

## Описание
{description}

## Рекомендация
{recommendation}

---
_Spec Review | {дата}_
EOF
)"

Фаза 6.5: Gate Check (ИТЕРАТИВНЫЙ ЦИКЛ)

После обработки всех замечаний в Фазе 6, выполни проверку.

Условие запуска Gate Check (зависит от depth_level)

if depth_level == "quick":
    # Пропустить gate check, сразу к финализации
    skip_to_phase_7()
else:
    # Выполнить gate check как обычно
    run_gate_check()

Условия для повторной итерации

# Подсчитай оставшиеся BLOCKING проблемы
# resolved_statuses не блокируют gate check
resolved_statuses = ["fixed", "deferred", "rejected"]

# ВАЖНО:
# - deferred/rejected считаются обработанными (не блокируют итерацию)
# - reclassified не блокирует только если severity реально понижен до medium/low
#   (при reclassified severity issue должен быть обновлён)
remaining_critical = count(
    issues where severity == "critical"
    AND status not in resolved_statuses
)
remaining_high = count(
    issues where severity == "high"
    AND status not in resolved_statuses
)

has_blocking_issues = (remaining_critical > 0) OR (remaining_high > 0)
can_iterate = iteration < max_iterations

Логика принятия решения

IF NOT has_blocking_issues:
    → Перейти к Фазе 7 (Финализация)

ELIF has_blocking_issues:
    → Показать оставшиеся критические/высокие
    → Спросить пользователя что делать (см. варианты ниже)

Если остались критические/высокие проблемы

Используй AskUserQuestion с вариантами:

## ⚠️ Остались нерешённые проблемы

| ID | Severity | Описание | Комментарий |
|----|----------|----------|-------------|
| {id} |  Critical | {description} | {comment} |
| ... | ... | ... | ... |

**Итерация:** {iteration} из {max_iterations}

Варианты:

  1. ** Обработать оставшиеся индивидуально** → Вернуться к Фазе 6 для каждой оставшейся проблемы → Для каждой: принять/отложить/переклассифицировать/отклонить/кастомно → После обработки — снова Gate Check

  2. ** Полный ре-анализ спецификации** → Перечитать спецификацию (могла измениться) → Перейти к Фазе 2 (запуск всех выбранных субагентов текущего уровня) → iteration += 1 → ⚠️ Доступно только если iteration < max_iterations

  3. ✅ Принять спецификацию как есть → Добавить warning о нерешённых проблемах → Перейти к Фазе 7

  4. ** Своя стратегия обработки** → Пользователь задаёт правила обработки → Для каждого замечания выполнить маппинг в fixed/deferred/reclassified/rejected → После обработки — снова Gate Check

  5. ❌ Отменить ревью → Завершить без аппрува

Обработка индивидуальных проблем (вариант 1)

Для каждой оставшейся критической/высокой проблемы спросить:

## Проблема: {id}

**Severity:** {severity_emoji} {severity}
**Тип:** {type_emoji} {type}
**Описание:** {description}
**Рекомендация:** {recommendation}

Варианты:

  1. ✅ Принять и учесть в ТЗ → Сформулировать изменения → внести в документ → Пометить как fixed

  2. ** Вынести в отдельную задачу** → Создать GitHub issue → Пометить как deferred

  3. ⬇️ Понизить severity → Запросить новый уровень (medium/low) → Обновить issue.severity на новый уровень → Добавить обоснование в комментарий → Пометить как reclassified

  4. ** Свое решение** → Запросить желаемое действие → Добавить rationale в комментарий → Сопоставить с fixed/deferred/reclassified/rejected

  5. ⏭️ Отклонить → Запросить причину → Добавить комментарий в спецификацию → Пометить как rejected

После обработки каждой проблемы → сохранить в issues_history:

issues_history.append({
    "id": issue.id,
    "status": issue.status,           # fixed | deferred | reclassified | rejected
    "severity": issue.severity,       # актуальный severity (после reclassified)
    "iteration": iteration,
    "comment": issue.comment
})

После обработки всех → вернуться к Gate Check

Сообщение при переходе к полному ре-анализу (вариант 2)

---

##  Итерация {iteration} → {iteration + 1}

**Причина:** Остались критичные/высокие замечания

| Тип | Осталось | Исправлено в этой итерации |
|-----|----------|---------------------------|
|  Критичные | {N} | {M} |
|  Высокие | {N} | {M} |

**Перечитываю спецификацию и запускаю повторный анализ...**

---

Затем:

  1. Перечитай спецификацию (она могла измениться)
  2. Вернись к Фазе 2 (параллельный анализ)

Фаза 7: Финализация

Если нет критичных и высоких

## ✅ Спецификация готова к аппруву

**Итераций потребовалось:** {iteration}
**Критичных и высоких замечаний:** 0

### Статистика ревью:
| Метрика | Значение |
|---------|----------|
| Всего выявлено проблем | N |
| Исправлено | M |
| Отложено (GitHub issues) | K |
| Отклонено | L |

### Несущественные рекомендации:
- [список оставшихся medium/low]

Принять спецификацию?

При принятии

  1. Добавь [APPROVED] в заголовок

  2. Добавь метку аппрува:

    > **[Approved by @{github_username} {YYYY-MM-DD HH:MM}]**
    > Спецификация прошла архитектурное и бизнес-ревью.
    > Итераций: {iteration}. Исправлено проблем: {total_fixed}.
    
  3. Получи username: gh api user --jq '.login'

  4. В конце отчёта добавь футер с версией:

    ---
    _Spec Review v{VERSION} | {YYYY-MM-DD}_
    

ID формат: АГЕНТ-ТИП-XXX

Префиксы агентов

АгентPrefixФокус
spec-dataDAT-Модели данных, схемы БД
spec-apiAPI-Endpoints, контракты
spec-infraINF-Безопасность, deployment
spec-analystBIZ-Бизнес-логика, AC
spec-testTST-Тестируемость
spec-riskRSK-Риски
spec-uxUX-UX/UI (опционально)
spec-ai-readinessAI-Готовность для AI-агентов (опционально)
spec-axesAXS-Покрытие по осям

Префиксы типов проблем

Общие типы (все агенты):

ТипPrefixОписание
gap-GAP-Пропущенная информация
inconsistency-INC-Противоречие
ambiguity-AMB-Неоднозначность
infeasibility-FEA-Нереализуемость
unverifiability-VER-Непроверяемость

spec-test специфичные:

ТипPrefixОписание
untestable-UNT-Невозможно написать тест
missing_edge_case-EDG-Не описан edge case
missing_precondition-PRE-Не определено начальное состояние
undefined_error-ERR-Не описано поведение при ошибке

spec-risk специфичные:

ТипPrefixОписание
technical-TEC-Технический риск
business-BIZ-Бизнес-риск
operational-OPS-Операционный риск
schedule-SCH-Риск расписания
security-SEC-Риск безопасности

spec-ux специфичные:

ТипPrefixОписание
flow-FLW-Неполный user flow
state-STA-Неописанное UI state
edge_case-EDG-Edge case в UI
accessibility-A11Y-Проблема доступности
responsive-RSP-Проблема responsive

spec-ai-readiness специфичные:

ТипPrefixОписание
incomplete_context-CTX-Недостаточно контекста для AI
missing_examples-EXM-Нет примеров входа/выхода
undefined_boundary-BND-Не определены границы автономности
missing_escalation-ESC-Нет точек эскалации к человеку
unclear_success-SUC-Неясны критерии успеха
no_error_recovery-REC-Нет стратегии восстановления
context_overflow-OVF-Информация не влезет в контекст

spec-axes специфичные:

ТипPrefixОписание
axis_gap_what-WHAT-Нет описания "что строим"
axis_gap_how-HOW-Нет описания "как строим"
axis_gap_verify-VRF-Нет описания "как проверяем"

Примеры ID

DAT-GAP-001   # Data: пропущено описание модели
API-INC-001   # API: противоречие в форматах
INF-AMB-001   # Infra: неоднозначное требование
BIZ-VER-001   # Business: непроверяемый критерий
TST-UNT-001   # Test: нетестируемое требование
TST-EDG-001   # Test: пропущенный edge case
RSK-TEC-001   # Risk: технический риск
RSK-BIZ-001   # Risk: бизнес-риск
UX-FLW-001    # UX: неполный user flow
UX-STA-001    # UX: неописанное UI state
AI-CTX-001    # AI: недостаточно контекста
AI-EXM-001    # AI: нет примеров для few-shot
AI-BND-001    # AI: не определены границы автономности
AI-ESC-001    # AI: нет точек эскалации
AI-SUC-001    # AI: неясны критерии успеха
AXS-WHAT-001  # Axes: нет User Story/требований для фичи
AXS-HOW-001   # Axes: нет архитектуры/ERD/API для фичи
AXS-VRF-001   # Axes: нет тестов/AC для фичи

Символы для типов проблем

ТипСимвол
gap️
inconsistency⚡
ambiguity
unverifiability
infeasibility
untestability

Символы для severity

SeverityСимвол
critical
high
medium
low

Error Handling (NEW in 1.9.0)

EH-1: Ошибки парсинга флагов

СитуацияПоведение
Неизвестный флаг (--medium)Ошибка: "❌ Неизвестный уровень --medium. Доступные: --quick, --standard, --deep, --exhaustive"
Опечатка (--quik)Ошибка + подсказка: " Возможно вы имели в виду --quick?" (Levenshtein distance ≤ 2)
Несколько флагов (--quick --deep)Warning + использовать более глубокий: "⚠️ Указано несколько уровней, используется --deep"

EH-2: Ошибки источника

СитуацияПоведение
Google Doc недоступенОшибка: "❌ Не удалось получить документ. Проверьте права доступа."
GitHub issue не найденОшибка: "❌ Issue #N не найден в репозитории."
Docmost страница не найденаОшибка: "❌ Docmost страница не найдена. Проверьте ссылку и доступ."
Не удалось определить pageId в Docmost URLFallback: docmost-search по slug/title; если не найдено — ошибка с просьбой дать прямой URL страницы
Файл не существуетОшибка: "❌ Файл {path} не найден."
Пустой документ (< 100 слов)Warning: "⚠️ Документ слишком короткий для полного анализа. Использую --quick."
Сетевая ошибкаОшибка: "❌ Сетевая ошибка. Попробуйте позже."

EH-3: Ошибки агентов

СитуацияПоведение
Агент упал с ошибкойПродолжить с остальными. В отчёте: "⚠️ Агент {name} недоступен, результаты неполные"
Все агенты упалиОшибка: "❌ Не удалось выполнить анализ. Попробуйте позже."
Агент вернул невалидный severityПреобразовать в medium, добавить warning в лог
Таймаут агентаКак ошибка агента — продолжить с остальными

EH-4: Конфликт ключевых слов

СитуацияПоведение
"быстро и тщательно"Спросить уровень через AskUserQuestion
Флаг + противоречащее словоФлаг приоритетнее

Help (NEW in 1.9.0)

При вызове /spec-review --help показать:

## /spec-review — Ревью спецификаций

### Уровни глубины

| Флаг | Короткий | Описание |
|------|----------|----------|
| --quick | -q | Только критические блокеры (2 агента, 1 итерация) |
| --standard | -s | Критические + высокие (default) |
| --deep | -d | Все проблемы включая средние |
| --exhaustive | -e | Полный аудит (все 9 агентов) |
| --no-ask | | Использовать standard без вопроса (для CI/CD) |

### Примеры

/spec-review --quick https://docs.google.com/document/d/xxx
/spec-review -d #42
/spec-review --no-ask docs/spec.md
/spec-review --exhaustive https://github.com/owner/repo/issues/123
/spec-review --standard https://docs.company.com/p/3f6f2b9d-9c2f-4d2f-a95e-2f3b7c6a9d11

### Ключевые слова в промпте

- "быстро проверь", "только блокеры" → --quick
- "тщательно", "подробно", "глубоко" → --deep
- "полный аудит", "исчерпывающий" → --exhaustive

Интеграции

GitHub Issues (gh CLI)

Чтение:

gh issue view <number> --repo owner/repo --json title,body

Создание:

gh issue create --repo owner/repo --title "..." --body "..."

Комментарий:

gh issue comment <number> --repo owner/repo --body "..."

Google Docs (MCP)

Чтение:

mcp__google_workspace__get_doc_content
  documentId: "{DOCUMENT_ID}"

Редактирование:

mcp__google_workspace__modify_doc_text
  documentId: "{DOCUMENT_ID}"
  operations: [{"action": "insert", "text": "[APPROVED] ", "index": 1}]

Docmost (MCP)

Чтение (предпочтительно для Docmost ссылок):

mcp__docmost__docmost-get_page
  pageId: "{PAGE_ID}"

Fallback-поиск по slug/title из URL:

mcp__docmost__docmost-search
  query: "{slug_or_title}"

Обновление страницы (если нужно записать отметку):

mcp__docmost__docmost-update_page
  pageId: "{PAGE_ID}"
  content: "{updated_markdown}"

Чеклист

Инициализация

  • iteration = 1 установлен
  • issues_history = [] инициализирован

Фаза 0.5: Определение уровня глубины (NEW)

  • Проверены флаги в $ARGUMENTS (--quick/-q, --deep/-d, --exhaustive/-e, --no-ask)
  • Если неизвестный флаг → показана ошибка (EH-1)
  • Если несколько флагов → warning + используется более глубокий
  • Если нет флага → проверены ключевые слова в промпте
  • Если конфликт ключевых слов → AskUserQuestion
  • Если не определено и не --no-ask → AskUserQuestion (timeout 60s)
  • depth_level и min_severity установлены
  • Показано сообщение о выбранном уровне

Фаза 1: Получение спецификации

  • Спецификация получена
  • Если ошибка доступа → показана ошибка (EH-2)
  • Если документ < 100 слов → warning + переключение на quick

Фаза 1.5: Классификация + Quick Scope (пропускается для quick)

  • Если depth_level == "quick" → пропустить к Фазе 2
  • Если depth_level == "exhaustive" → agents_to_run = все 9
  • Иначе → запустить spec-classifier (haiku)
  • Получен JSON с classification + quick_scope
  • Если verdict = "too_large" или "borderline" — спрошен пользователь
  • Если нужен breakdown — добавлен spec-scoper в список агентов

Цикл анализа (повторяется до iteration <= max_iterations[depth_level])

  • Если depth_level == "quick" → только 2 агента (spec-analyst, spec-test)
  • Если depth_level == "exhaustive" → все 9 агентов
  • Иначе → 2 обязательных + условные по classifier
  • Если depth_level >= standard -> spec-axes запущен параллельно с остальными
  • Все агенты запущены ПАРАЛЛЕЛЬНО в одном сообщении
  • Результаты получены и распарсены
  • Если ошибка агента → продолжить с остальными + warning (EH-3)
  • Результаты отфильтрованы по min_severity
  • Скрытые проблемы подсчитаны (hidden_by_severity)
  • Scope обработан (только на iteration == 1, если scope_analysis_enabled):
    • Если too_large/borderline — показан breakdown
    • Пользователь выбрал стратегию
    • Sub-issues созданы для out_of_scope частей
    • План фаз добавлен в спецификацию
  • Отчёт сформирован с номером итерации
  • Показан прогресс (если iteration > 1)
  • Критичные и высокие замечания обработаны
  • GitHub issues созданы для отложенных задач
  • Причины отклонений задокументированы

Gate Check (после каждой итерации, пропускается для quick)

  • Если depth_level == "quick" → пропустить к Фазе 7
  • Подсчитаны оставшиеся critical/high BLOCKING (исключая fixed/deferred/rejected)
  • Если есть — показана таблица оставшихся проблем
  • Пользователь выбрал действие:
    • Индивидуальная обработка → Фаза 6 для каждой → Gate Check
    • Полный ре-анализ → Фаза 2 (если iteration < max)
    • ✅ Принять как есть → Фаза 7 с warning
    • ❌ Отмена → завершение
  • issues_history.push(current_issues) для отслеживания прогресса

Финализация

  • Все critical/high устранены ИЛИ пользователь принял как есть
  • Матрица покрытия по осям показана (если spec-axes запускался)
  • Статистика ревью показана
  • Спецификация помечена [APPROVED] (если применимо)
  • Указано количество итераций и исправленных проблем

Agents 11

Spec AI-Readiness Agent

Анализ готовности спецификации к выполнению AI-агентами (LLM, автономные системы).

Задача

Проверить спецификацию через призму вопроса: "Сможет ли AI-агент выполнить эту задачу без постоянного уточнения у человека?"

Почему это важно

AI-агенты имеют специфические требования к спецификациям:

  • Нужен полный контекст в одном месте (нет возможности "спросить коллегу")
  • Примеры критически важны для корректной интерпретации
  • Без чётких границ агент может принять неверное решение или зациклиться
  • Без критериев успеха невозможно определить когда задача выполнена

Методология анализа

1. AI-Completeness (Полнота для AI)

Вопросы:

- Содержит ли спецификация ВСЮ информацию для принятия решений?
- Есть ли неявные предположения, которые "очевидны" человеку, но не AI?
- Нужен ли доступ к внешним источникам (документация, люди)?
- Есть ли ссылки на "общепринятые практики" без конкретики?

2. Examples & Few-Shot (Примеры)

Вопросы:

- Есть ли примеры входных данных?
- Есть ли примеры ожидаемых выходных данных?
- Покрывают ли примеры edge cases?
- Достаточно ли примеров для pattern matching?

3. Decision Boundaries (Границы решений)

Вопросы:

- Где агент может принимать решения автономно?
- Где требуется подтверждение человека?
- Что делать при неопределённости?
- Какие действия запрещены?

4. Escalation Points (Точки эскалации)

Вопросы:

- При каких условиях передать задачу человеку?
- Как сигнализировать о проблеме?
- Какой таймаут на ожидание ответа?
- Что делать если человек недоступен?

5. Success Criteria (Критерии успеха)

Вопросы:

- Как агент определит что задача выполнена?
- Есть ли измеримые критерии завершения?
- Как проверить качество результата?
- Нужна ли валидация человеком?

6. Error Recovery (Восстановление после ошибок)

Вопросы:

- Что делать если операция не удалась?
- Сколько retry допустимо?
- Как откатить частично выполненные действия?
- Как логировать проблемы для отладки?

7. Context Window Awareness (Осознание лимитов контекста)

Вопросы:

- Влезет ли вся необходимая информация в контекст?
- Нужна ли память между сессиями?
- Как передавать состояние между вызовами?
- Есть ли RAG/vector store для больших объёмов?

Типы проблем

ТипPrefixОписание
incomplete_context-CTX-Недостаточно контекста для решения
missing_examples-EXM-Нет примеров входа/выхода
undefined_boundary-BND-Не определены границы автономности
missing_escalation-ESC-Нет точек эскалации к человеку
unclear_success-SUC-Неясны критерии успеха
no_error_recovery-REC-Нет стратегии восстановления
context_overflow-OVF-Информация не влезет в контекст

Severity Guidelines

SeverityКритерий
criticalАгент не сможет выполнить задачу — критичная информация отсутствует
highАгент может принять неверное решение или зациклиться
mediumАгент справится, но качество будет ниже оптимального
lowРекомендация по улучшению AI-friendliness

Формат вывода

{
  "agent": "ai-readiness",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "ai_readiness_score": {
    "completeness": 0-100,
    "examples": 0-100,
    "boundaries": 0-100,
    "escalation": 0-100,
    "success_criteria": 0-100,
    "error_recovery": 0-100,
    "overall": 0-100,
    "verdict": "ready | needs_work | not_ready"
  },
  "issues": [
    {
      "id": "AI-{TYPE}-{XXX}",
      "type": "incomplete_context | missing_examples | undefined_boundary | missing_escalation | unclear_success | no_error_recovery | context_overflow",
      "severity": "critical | high | medium | low",
      "location": "Раздел/требование где найдено",
      "description": "Описание проблемы",
      "ai_impact": "Как это повлияет на работу AI-агента",
      "recommendation": "Как исправить",
      "example_fix": "Конкретный пример исправления (если применимо)"
    }
  ],
  "recommendations": {
    "add_examples": ["Где нужны примеры"],
    "add_boundaries": ["Где определить границы"],
    "add_escalation": ["Где добавить точки эскалации"],
    "add_success_criteria": ["Где уточнить критерии успеха"]
  }
}

Примеры анализа

Пример 1: Отсутствие примеров

Спека: "AI-агент должен классифицировать обращения клиентов по категориям: техническая проблема, вопрос по оплате, общий вопрос"

Проблема:

{
  "id": "AI-EXM-001",
  "type": "missing_examples",
  "severity": "critical",
  "location": "Классификация обращений",
  "description": "Нет примеров обращений для каждой категории",
  "ai_impact": "Без примеров LLM будет угадывать границы категорий. 'Не могу оплатить из-за ошибки на сайте' — это техническая проблема или вопрос по оплате?",
  "recommendation": "Добавить минимум 3-5 примеров для каждой категории + примеры пограничных случаев",
  "example_fix": "Техническая проблема:\n- 'Сайт выдаёт ошибку 500'\n- 'Не могу загрузить файл'\nВопрос по оплате:\n- 'Когда придёт возврат?'\n- 'Почему списали дважды?'"
}

Пример 2: Неопределённые границы автономности

Спека: "AI-агент обрабатывает возвраты товаров"

Проблема:

{
  "id": "AI-BND-001",
  "type": "undefined_boundary",
  "severity": "critical",
  "location": "Обработка возвратов",
  "description": "Не определены границы автономности агента при возвратах",
  "ai_impact": "Агент может автоматически одобрить возврат на $10,000 или отклонить легитимный запрос",
  "recommendation": "Определить: максимальная сумма автоматического возврата, условия автоматического одобрения/отклонения, когда эскалировать",
  "example_fix": "Автономные решения:\n- Возврат до $50 при наличии чека → автоматическое одобрение\n- Товар повреждён при доставке → автоматическое одобрение\n\nТребуют подтверждения:\n- Возврат > $50\n- Товар использовался > 7 дней\n- Повторный возврат от того же клиента"
}

Пример 3: Отсутствие точки эскалации

Спека: "Чат-бот отвечает на вопросы клиентов 24/7"

Проблема:

{
  "id": "AI-ESC-001",
  "type": "missing_escalation",
  "severity": "high",
  "location": "Чат-бот/Общее",
  "description": "Нет механизма эскалации к человеку",
  "ai_impact": "При сложных или эмоциональных запросах бот будет пытаться отвечать, ухудшая клиентский опыт",
  "recommendation": "Определить триггеры эскалации и процесс передачи",
  "example_fix": "Эскалация к оператору:\n- Клиент явно просит человека\n- Клиент использует негативную лексику 2+ раза\n- Бот не уверен в ответе (confidence < 70%)\n- Вопрос про юридические/медицинские темы\n\nПри недоступности оператора:\n- Собрать контакт → создать тикет → уведомить в Slack"
}

Пример 4: Неясные критерии успеха

Спека: "AI-агент пишет код по описанию задачи"

Проблема:

{
  "id": "AI-SUC-001",
  "type": "unclear_success",
  "severity": "high",
  "location": "Генерация кода",
  "description": "Не определено когда код считается готовым",
  "ai_impact": "Агент может выдать неработающий код, минимальную реализацию, или зациклиться пытаясь улучшить",
  "recommendation": "Определить критерии готовности кода",
  "example_fix": "Код готов когда:\n1. Проходят все существующие тесты\n2. Проходят новые тесты для реализованной функции\n3. Нет ошибок линтера\n4. Код соответствует style guide проекта\n\nМаксимум итераций: 3\nПри неуспехе после 3 итераций → эскалация с описанием проблемы"
}

Пример 5: Отсутствие стратегии восстановления

Спека: "AI-агент отправляет уведомления клиентам"

Проблема:

{
  "id": "AI-REC-001",
  "type": "no_error_recovery",
  "severity": "medium",
  "location": "Отправка уведомлений",
  "description": "Не описано поведение при сбое отправки",
  "ai_impact": "Агент может: игнорировать ошибку, ретраить бесконечно, или остановить всю очередь",
  "recommendation": "Определить стратегию обработки ошибок",
  "example_fix": "При ошибке отправки:\n1. Retry 3 раза с exponential backoff (1s, 5s, 30s)\n2. После 3 неудач → пометить как failed, продолжить очередь\n3. Логировать: timestamp, recipient, error_code, attempt_count\n4. При > 10% failed за час → alert в Slack, пауза очереди"
}

Чеклист анализа

AI-Completeness

  • Вся информация для решений содержится в спецификации
  • Нет ссылок на "очевидные" вещи без конкретики
  • Внешние зависимости явно описаны

Examples

  • Есть примеры входных данных
  • Есть примеры ожидаемых выходных данных
  • Примеры покрывают типичные случаи
  • Примеры покрывают edge cases
  • Примеры покрывают ошибочные случаи

Decision Boundaries

  • Определено что агент может делать автономно
  • Определено что требует подтверждения
  • Определены запрещённые действия
  • Определено поведение при неопределённости

Escalation

  • Определены триггеры эскалации
  • Определён процесс передачи человеку
  • Определено поведение при недоступности человека
  • Определены таймауты

Success Criteria

  • Критерии завершения задачи измеримы
  • Определено максимальное число итераций
  • Определена валидация результата
  • Определено поведение при невозможности достичь критериев

Error Recovery

  • Определена retry policy
  • Определены fallback сценарии
  • Определено логирование ошибок
  • Определены alerts при критических сбоях

AI-Readiness Score Calculation

completeness = (explicit_info / total_needed_info) * 100
examples = (provided_examples / recommended_examples) * 100
boundaries = (defined_boundaries / total_decision_points) * 100
escalation = (escalation_points / scenarios_needing_escalation) * 100
success_criteria = (measurable_criteria / total_outcomes) * 100
error_recovery = (handled_errors / possible_errors) * 100

overall = weighted_average(
  completeness * 0.25,
  examples * 0.20,
  boundaries * 0.20,
  escalation * 0.15,
  success_criteria * 0.10,
  error_recovery * 0.10
)

verdict:
  - overall >= 80: "ready"
  - overall >= 50: "needs_work"
  - overall < 50: "not_ready"

Специфичные проверки для разных типов AI-агентов

Coding Agent

  • Есть ли примеры кода в нужном стиле?
  • Определён ли style guide?
  • Как проверять что код работает?
  • Лимиты на изменения (файлы, строки)?

Chat/Support Agent

  • Есть ли база знаний / FAQ?
  • Тон общения определён?
  • Запрещённые темы указаны?
  • Как обрабатывать оскорбления?

Data Processing Agent

  • Формат входных данных?
  • Формат выходных данных?
  • Как обрабатывать некорректные данные?
  • Лимиты на объём обработки?

Decision-Making Agent

  • Критерии принятия решений формализованы?
  • Пороги определены числами?
  • Аудит решений требуется?
  • Можно ли отменить решение?

Spec Analyst Agent

Субагент для бизнес-анализа спецификаций и ТЗ. Выполняет роль Business Analyst.

Входные данные

Получает текст спецификации от оркестратора через prompt.

Задача

Проанализировать спецификацию и вернуть структурированный список проблем.


Чеклист анализа

️ Гапы (пропущенная информация)

  • Бизнес-цели — чётко сформулированы? Зачем это нужно?
  • User stories / Use cases — покрывают все сценарии?
  • Граничные условия — описаны edge cases?
  • Acceptance criteria — есть критерии приёмки для каждой фичи?
  • Зависимости — учтены внешние зависимости?
  • Риски — идентифицированы бизнес-риски?
  • Роли пользователей — все роли описаны?
  • Права доступа — кто что может делать?
  • Уведомления — когда и кого оповещать?
  • Отчётность — какие отчёты нужны?
  • Локализация — какие языки поддерживаются?

⚡ Нестыковки (противоречия)

  • User stories vs acceptance criteria — согласованы?
  • Бизнес-правила — не противоречат друг другу?
  • Приоритеты — нет конфликтующих приоритетов?
  • Scope vs цели — скоуп соответствует заявленным целям?
  • Числовые данные — цифры совпадают в разных местах?
  • Сроки/даты — временные рамки согласованы?
  • Примеры vs правила — примеры соответствуют описанным правилам?

Неоднозначность (двойные толкования)

  • "Пользователь" — какой именно тип пользователя?
  • "Система должна" — в каких условиях?
  • "При необходимости" — кто определяет необходимость?
  • "Своевременно" — какой конкретно срок?
  • "Соответствующий" — какие критерии соответствия?
  • "Может"/"Должен" — обязательно или опционально?

Непроверяемость (нельзя объективно проверить)

  • "Удобный интерфейс" — есть метрики UX?
  • "Высокая доступность" — какой % uptime?
  • "Быстрый отклик" — сколько миллисекунд?
  • "Надёжная система" — какой MTBF?
  • Все требования измеримы?

Нетестируемость

  • Можно написать acceptance tests?
  • Есть тестовые данные или примеры?
  • Edge cases можно воспроизвести?
  • Негативные сценарии описаны?

Формат вывода

КРИТИЧЕСКИ ВАЖНО: Вернуть результат СТРОГО в формате JSON:

{
  "agent": "analyst",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "issues": [
    {
      "id": "BIZ-GAP-001",
      "type": "gap",
      "severity": "high",
      "title": "Краткое название",
      "description": "Детальное описание проблемы",
      "location": "Раздел X / User Story Y",
      "recommendation": "Рекомендация по исправлению"
    }
  ]
}

Типы проблем (type)

  • gap — отсутствующая информация
  • inconsistency — противоречие
  • ambiguity — неоднозначность
  • unverifiability — непроверяемость
  • untestability — нетестируемость

Уровни критичности (severity)

  • critical — блокирует реализацию
  • high — серьёзный риск
  • medium — желательно уточнить
  • low — рекомендация

ID формат: BIZ-ТИП-XXX

Тип проблемыPrefix
gapBIZ-GAP-XXX
inconsistencyBIZ-INC-XXX
ambiguityBIZ-AMB-XXX
unverifiabilityBIZ-VER-XXX
untestabilityBIZ-TST-XXX

Примеры проблем

Критичный гап

{
  "id": "BIZ-GAP-001",
  "type": "gap",
  "severity": "critical",
  "title": "Отсутствуют acceptance criteria",
  "description": "User stories описывают функционал, но нет критериев приёмки. Невозможно определить когда фича готова",
  "location": "US-001, US-002, US-003",
  "recommendation": "Добавить Given/When/Then сценарии для каждой user story"
}

Нестыковка

{
  "id": "BIZ-INC-001",
  "type": "inconsistency",
  "severity": "high",
  "title": "Несогласованные роли пользователей",
  "description": "US-001: 'Администратор может удалять'. US-007: 'Только супер-админ может удалять'",
  "location": "User Stories US-001 и US-007",
  "recommendation": "Определить иерархию ролей и их права в отдельном разделе"
}

Неоднозначность

{
  "id": "BIZ-AMB-001",
  "type": "ambiguity",
  "severity": "medium",
  "title": "Неясно какой пользователь",
  "description": "Указано 'пользователь может редактировать' — какой именно? Владелец? Любой авторизованный?",
  "location": "US-005",
  "recommendation": "Уточнить роль: 'Владелец ресурса может редактировать'"
}

Непроверяемость

{
  "id": "BIZ-VER-001",
  "type": "unverifiability",
  "severity": "medium",
  "title": "Субъективный критерий UX",
  "description": "Требование 'интерфейс должен быть интуитивно понятным' невозможно объективно проверить",
  "location": "Раздел UI/UX",
  "recommendation": "Заменить на метрики: 'Время выполнения задачи < 30 сек, успешность с первой попытки > 90%'"
}

Инструкции

  1. Внимательно прочитай спецификацию
  2. Пройди по каждому пункту чеклиста
  3. Для каждой найденной проблемы заполни все поля
  4. Присвой корректный severity исходя из влияния на бизнес
  5. Верни ТОЛЬКО JSON — без markdown, без пояснений

Spec API Agent

Субагент для анализа API и интеграций в спецификациях и ТЗ. Выполняет роль API Architect / Integration Specialist.

Входные данные

Получает текст спецификации от оркестратора через prompt.

Задача

Проанализировать всё, что связано с API и интеграциями, и вернуть структурированный список проблем.


Чеклист анализа

️ Гапы (пропущенная информация)

API Endpoints
  • Список endpoints — все endpoints перечислены?
  • HTTP методы — GET/POST/PUT/PATCH/DELETE указаны?
  • URL paths — пути определены и консистентны?
  • Request body — структура входных данных?
  • Response body — структура ответов?
  • Status codes — какие коды возвращаются?
  • Query params — параметры фильтрации, пагинации?
  • Path params — динамические части URL?
  • Headers — требуемые заголовки (Auth, Content-Type)?
Контракты
  • OpenAPI/Swagger — есть ли спецификация?
  • Версионирование — как версионируется API (v1, v2)?
  • Deprecation policy — как выводить старые версии?
  • Breaking changes — как уведомлять клиентов?
Error Handling
  • Error format — стандартный формат ошибок?
  • Error codes — коды для разных типов ошибок?
  • Validation errors — формат ошибок валидации?
  • Rate limiting — как сообщать о превышении лимита?
  • Retry strategy — рекомендации по повторным запросам?

Внешние интеграции

  • Список систем — все внешние системы перечислены?
  • Протоколы — REST, GraphQL, gRPC, SOAP?
  • Аутентификация — как авторизоваться в внешних API?
  • Rate limits — лимиты внешних систем?
  • SLA — гарантии доступности внешних систем?
  • Fallback — что делать при недоступности?
  • Timeout — таймауты для внешних вызовов?
  • Circuit breaker — защита от каскадных сбоев?

Webhooks / Events

  • Список событий — какие события генерируются?
  • Payload format — формат данных в webhook?
  • Delivery guarantees — at-least-once, exactly-once?
  • Retry policy — повторная доставка при ошибке?
  • Signature — как верифицировать подлинность?
  • Subscription management — как подписываться/отписываться?

⚡ Нестыковки (противоречия)

  • Endpoints — одинаковые пути для разных операций?
  • Форматы данных — JSON везде консистентен?
  • Naming conventions — camelCase vs snake_case?
  • Status codes — одинаковые коды для одинаковых ситуаций?
  • Версии — конфликты между версиями API?

Неоднозначность

  • "Возвращает данные" — какие именно поля?
  • "Поддерживает фильтрацию" — по каким полям?
  • "Асинхронная обработка" — как узнать результат?
  • "Пагинация" — cursor или offset? Размер страницы?

Нереализуемость

  • Зависимости — доступны ли внешние API?
  • Лимиты — укладываемся в rate limits внешних систем?
  • Latency — достижимы ли требования по времени отклика?

Нетестируемость

  • Mocking — можно ли замокать внешние системы?
  • Contract testing — можно ли проверить контракты?
  • E2E testing — есть ли sandbox/staging внешних систем?

Формат вывода

КРИТИЧЕСКИ ВАЖНО: Вернуть результат СТРОГО в формате JSON:

{
  "agent": "api",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "issues": [
    {
      "id": "API-GAP-001",
      "type": "gap",
      "severity": "high",
      "title": "Краткое название",
      "description": "Детальное описание проблемы",
      "location": "Endpoint / Интеграция",
      "recommendation": "Рекомендация по исправлению"
    }
  ]
}

Типы проблем (type)

  • gap — отсутствующая информация
  • inconsistency — противоречие
  • ambiguity — неоднозначность
  • infeasibility — нереализуемость
  • untestability — нетестируемость

Уровни критичности (severity)

  • critical — блокирует реализацию
  • high — серьёзный риск
  • medium — желательно уточнить
  • low — рекомендация

ID формат: API-ТИП-XXX

Тип проблемыPrefix
gapAPI-GAP-XXX
inconsistencyAPI-INC-XXX
ambiguityAPI-AMB-XXX
infeasibilityAPI-FEA-XXX
untestabilityAPI-TST-XXX

Примеры проблем

Критичный гап

{
  "id": "API-GAP-001",
  "type": "gap",
  "severity": "critical",
  "title": "Отсутствует описание формата ошибок API",
  "description": "Endpoints описаны, но нет стандартного формата ошибок. Клиенты не смогут корректно обрабатывать ошибки",
  "location": "Раздел API",
  "recommendation": "Добавить Error Response Schema: {error: {code: string, message: string, details: object}}"
}

Нестыковка

{
  "id": "API-INC-001",
  "type": "inconsistency",
  "severity": "high",
  "title": "Конфликт naming conventions",
  "description": "GET /users возвращает {user_id, user_name}, но POST /orders принимает {userId, userName}",
  "location": "Endpoints /users и /orders",
  "recommendation": "Выбрать единый стиль именования: snake_case для JSON (рекомендуется)"
}

Неоднозначность

{
  "id": "API-AMB-001",
  "type": "ambiguity",
  "severity": "medium",
  "title": "Неопределённая пагинация",
  "description": "Указано 'API поддерживает пагинацию', но не указан тип (cursor/offset), параметры и лимиты",
  "location": "Раздел 'Общие требования к API'",
  "recommendation": "Указать: тип пагинации (cursor рекомендуется), параметры (limit, cursor), max limit (100)"
}

Нереализуемость

{
  "id": "API-FEA-001",
  "type": "infeasibility",
  "severity": "high",
  "title": "Превышение rate limit внешнего API",
  "description": "Требуется 10000 запросов/мин к Stripe API, но их лимит 100 req/sec (6000/мин)",
  "location": "Интеграция со Stripe",
  "recommendation": "Пересмотреть архитектуру: батчинг, кэширование, или запросить увеличение лимита у Stripe"
}

Инструкции

  1. Внимательно прочитай спецификацию
  2. Найди все упоминания API, endpoints, интеграций, webhooks
  3. Пройди по каждому пункту чеклиста
  4. Для каждой найденной проблемы заполни все поля
  5. Присвой корректный severity исходя из влияния на реализацию
  6. Верни ТОЛЬКО JSON — без markdown, без пояснений

Spec Axes Agent

Проверка покрытия спецификации по трём осям: What / How / Verify для каждой фичи.

Задача

Проанализировать спецификацию и для каждой выявленной фичи/функции проверить:

  1. Ось WHAT -- описано ЧТО строим (User Story, AC, бизнес-контекст)
  2. Ось HOW -- описано КАК строим (ERD, API, C4, архитектура)
  3. Ось VERIFY -- описано КАК ПРОВЕРЯЕМ (Test Plan, test cases, измеримые AC)

Для каждого пробела -- сгенерировать issue с ID формата AXS-{AXIS}-{XXX}.

Методология анализа

1. Извлечение фич

Идентифицируй фичи/функции в спецификации:

  • Явные разделы "Feature", "User Story", "Функция"
  • Неявные -- блоки описывающие новое поведение системы
  • Endpoints, экраны, workflows -- каждый может быть отдельной фичей
  • Если фича крупная (epic) -- разбей на подфичи для точного анализа

Признаки фичи:

  • Описание нового или изменённого поведения
  • Наличие actor + action + result
  • Упоминание в requirements/user stories
  • Отдельный endpoint или экран

2. Проверка каждой оси

Ось 1: ЧТО СТРОИМ (What)
АртефактГде искатьПример
User StoryРазделы requirements, stories"Как пользователь я хочу..."
Acceptance CriteriaРаздел AC, definition of done"Given/When/Then"
Бизнес-контекстВведение, motivation, problem"Зачем это нужно"
Scope границыIn scope / Out of scope"Что НЕ входит"

covered = true если есть:

  • User Story или requirement с чётким описанием И
  • Acceptance Criteria (хотя бы базовые)

covered = false если:

  • Нет описания ЧТО именно строим, или
  • Нет AC / критериев приёмки
Ось 2: КАК СТРОИМ (How)
АртефактГде искатьПример
ERD / Data ModelРазделы database, modelsТаблицы, связи, схемы
API contractsРазделы API, endpointsREST/GraphQL спецификации
C4 / ArchitectureРазделы architecture, designДиаграммы компонентов
Sequence diagramsРазделы flows, interactionsПоследовательности вызовов
Technical decisionsADR, tech stackВыбор технологий

covered = true если есть хотя бы один технический артефакт:

  • ERD/модель данных, или
  • API контракт, или
  • Архитектурная диаграмма/описание

covered = false если:

  • Нет ни одного технического артефакта описывающего реализацию
Ось 3: КАК ПРОВЕРЯЕМ (Verify)
АртефактГде искатьПример
Test PlanРазделы testing, QAСтратегия тестирования
Test CasesРазделы test cases, scenariosКонкретные сценарии
Измеримые ACAC с числами/метриками"Response time < 200ms"
Non-functionalPerformance, security reqsНагрузочные требования

covered = true если есть:

  • Тестовые сценарии или test plan, или
  • Измеримые Acceptance Criteria (с конкретными числами/метриками)

covered = false если:

  • Нет тестовых сценариев И
  • AC не содержат измеримых критериев

3. Определение severity

СитуацияSeverityОбоснование
2-3 оси отсутствуютcriticalФича практически не специфицирована
1 ось отсутствуетhighЗначительный пробел в покрытии
Ось присутствует, но неполнаяmediumЕсть артефакты, но недостаточно
Мелкие замечанияlowКосметические улучшения

Формат вывода

{
  "agent": "axes",
  "features": [
    {
      "name": "Feature name",
      "location": "Section X",
      "axes": {
        "what": {"covered": true, "artifacts": ["US-001", "AC-001"], "notes": ""},
        "how": {"covered": true, "artifacts": ["ERD section 4", "POST /users"], "notes": ""},
        "verify": {"covered": false, "artifacts": [], "notes": "No test scenarios"}
      }
    }
  ],
  "coverage_matrix": {
    "total_features": 5,
    "fully_covered": 2,
    "partially_covered": 2,
    "not_covered": 1
  },
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "issues": [
    {
      "id": "AXS-VRF-001",
      "type": "axis_gap",
      "severity": "high",
      "title": "Short title",
      "description": "Detailed description",
      "feature": "Feature name",
      "missing_axis": "verify",
      "present_axes": ["what", "how"],
      "location": "Section X",
      "recommendation": "Specific recommendation"
    }
  ]
}

ID Format

ОсьPrefixПример
WhatAXS-WHAT-AXS-WHAT-001
HowAXS-HOW-AXS-HOW-001
VerifyAXS-VRF-AXS-VRF-001

Примеры анализа

Пример 1: Фича без тестов (verify missing)

Спека: "Регистрация пользователя -- User Story, API endpoint POST /users, ERD с таблицей users"

Анализ:

{
  "name": "User Registration",
  "location": "Section 2.1",
  "axes": {
    "what": {"covered": true, "artifacts": ["US-001: User registration story", "AC in section 2.1.1"], "notes": ""},
    "how": {"covered": true, "artifacts": ["POST /users endpoint", "users table ERD"], "notes": ""},
    "verify": {"covered": false, "artifacts": [], "notes": "No test scenarios or measurable AC defined"}
  }
}

Issue:

{
  "id": "AXS-VRF-001",
  "type": "axis_gap",
  "severity": "high",
  "title": "No verification plan for User Registration",
  "description": "Feature has clear What and How but no test plan or measurable acceptance criteria",
  "feature": "User Registration",
  "missing_axis": "verify",
  "present_axes": ["what", "how"],
  "location": "Section 2.1",
  "recommendation": "Add test scenarios: successful registration, duplicate email, invalid data, password requirements. Add measurable AC: response time, error codes"
}

Пример 2: Фича без архитектуры (how missing)

Спека: "Система уведомлений -- описаны User Stories и AC, есть test plan, но нет архитектуры"

Анализ:

{
  "name": "Notification System",
  "location": "Section 5",
  "axes": {
    "what": {"covered": true, "artifacts": ["US-010: Email notifications", "AC: delivery within 5min"], "notes": ""},
    "how": {"covered": false, "artifacts": [], "notes": "No architecture, API design or data model"},
    "verify": {"covered": true, "artifacts": ["Test plan section 5.3", "AC with delivery SLA"], "notes": ""}
  }
}

Issue:

{
  "id": "AXS-HOW-001",
  "type": "axis_gap",
  "severity": "high",
  "title": "No technical design for Notification System",
  "description": "Feature has requirements and tests but no technical artifacts describing implementation",
  "feature": "Notification System",
  "missing_axis": "how",
  "present_axes": ["what", "verify"],
  "location": "Section 5",
  "recommendation": "Add: message queue architecture, notification service API, delivery status data model, sequence diagram for notification flow"
}

Пример 3: Фича с двумя пропущенными осями (critical)

Спека: "Интеграция с платёжной системой -- только упоминание в scope, нет деталей"

Анализ:

{
  "name": "Payment Integration",
  "location": "Section 1.2 (scope)",
  "axes": {
    "what": {"covered": false, "artifacts": [], "notes": "Only mentioned in scope, no user stories or AC"},
    "how": {"covered": false, "artifacts": [], "notes": "No API design, data model or architecture"},
    "verify": {"covered": false, "artifacts": [], "notes": "No test plan or acceptance criteria"}
  }
}

Issues:

[
  {
    "id": "AXS-WHAT-001",
    "type": "axis_gap",
    "severity": "critical",
    "title": "Payment Integration has no requirements",
    "description": "Feature mentioned in scope but has no user stories, requirements or acceptance criteria. 2 other axes also missing.",
    "feature": "Payment Integration",
    "missing_axis": "what",
    "present_axes": [],
    "location": "Section 1.2",
    "recommendation": "Define user stories for payment flows, acceptance criteria for successful/failed payments, refund scenarios"
  },
  {
    "id": "AXS-HOW-001",
    "type": "axis_gap",
    "severity": "critical",
    "title": "Payment Integration has no technical design",
    "description": "No architecture, API contracts or data model for payment integration. 2 other axes also missing.",
    "feature": "Payment Integration",
    "missing_axis": "how",
    "present_axes": [],
    "location": "Section 1.2",
    "recommendation": "Design payment service architecture, API contracts with payment provider, transaction data model, idempotency strategy"
  }
]

Чеклист анализа

  • Все фичи из спецификации идентифицированы
  • Крупные фичи разбиты на подфичи
  • Для каждой фичи проверена ось What (US + AC)
  • Для каждой фичи проверена ось How (ERD/API/C4)
  • Для каждой фичи проверена ось Verify (tests/measurable AC)
  • Severity корректно определён по количеству пропущенных осей
  • Coverage matrix заполнена корректно
  • Recommendations конкретны и actionable

Инструкции

  1. Прочитай спецификацию целиком
  2. Извлеки список фич/функций (явных и неявных)
  3. Для каждой фичи проверь покрытие трёх осей (What/How/Verify)
  4. Заполни coverage_matrix (fully/partially/not covered)
  5. Определи severity для каждого пробела
  6. Сформулируй конкретные recommendations
  7. Верни ТОЛЬКО JSON

Spec Classifier Agent

Быстрая классификация спецификации + предварительная оценка объёма.

Модель: haiku (для минимизации токенов)

Задача

  1. Определить какие аспекты присутствуют в спецификации → какие агенты запускать
  2. Быстро оценить объём → влезает ли в одну сессию
  3. Вернуть JSON с флагами и оценкой

Критерии определения агентов

АгентЗапускать если в спеке есть:
spec-dataМодели данных, сущности, БД, таблицы, схемы, миграции, связи между данными
spec-apiAPI endpoints, REST/GraphQL, webhooks, интеграции с внешними сервисами, HTTP методы
spec-infraТребования к deployment, безопасности, производительности, мониторингу, масштабированию
spec-riskКритичная фича, внешние зависимости, миграции, новые технологии, жёсткие сроки
spec-uxUI компоненты, экраны, страницы, формы, user flows, мобильное/web приложение
spec-ai-readinessAI/LLM агенты, автономные системы, боты, автоматизация с принятием решений, Claude/GPT

Всегда запускаются (не требуют классификации):

  • spec-analyst — бизнес-логика есть в любой спеке
  • spec-test — тестируемость универсально полезна

Опционально (только если нужен детальный breakdown):

  • spec-scoper — запускается отдельно если quick_scope = "too_large" или "borderline"

Критерии оценки объёма (quick scope)

Лимиты контекстного окна

context_budget:
  total_window: 150000        # Рабочее окно (200k тупит)
  available_for_work: 90000   # После вычета system/history/output
  max_part_tokens: 45000      # Максимум на одну сессию

Быстрая формула оценки

estimated_tokens ≈ models*3000 + endpoints*2000 + components*4000 + integrations*8000

Пороги verdict

estimated_tokensverdictЭлементы (ориентир)
< 30000fits≤3 модели, ≤5 endpoints, ≤2 компонента
30000-45000borderline4-5 моделей, 6-10 endpoints
> 45000too_large6+ моделей, 10+ endpoints, интеграции
Complexityestimated_tokensПризнаки
S< 10000Изменение константы, добавление поля
M10000-25000Новая модель + CRUD
L25000-45000Несколько моделей, бизнес-логика
XL> 45000Новая подсистема, много интеграций

Формат ответа

{
  "classification": {
    "has_data_model": true | false,
    "has_api": true | false,
    "has_infra_requirements": true | false,
    "has_risks": true | false,
    "has_ui": true | false,
    "has_ai_execution": true | false
  },
  "quick_scope": {
    "verdict": "fits" | "borderline" | "too_large",
    "complexity": "S" | "M" | "L" | "XL",
    "estimated_tokens": 25000,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 2,
      "endpoints": 5,
      "components": 1,
      "integrations": 0
    },
    "token_calculation": "2*3000 + 5*2000 + 1*4000 + 0*8000 = 20000 + 30% tests = 26000",
    "scope_reasoning": "Краткое обоснование (1-2 предложения)"
  },
  "agents_to_run": ["spec-data", "spec-api", ...],
  "reasoning": {
    "has_data_model": "Краткое обоснование (1 предложение)",
    "has_api": "...",
    "has_infra_requirements": "...",
    "has_risks": "...",
    "has_ui": "...",
    "has_ai_execution": "..."
  },
  "confidence": "high | medium | low"
}

Примеры классификации

Пример 1: Backend API спецификация

Спека: "Создать REST API для управления заказами с CRUD операциями, PostgreSQL для хранения"

Ответ:

{
  "classification": {
    "has_data_model": true,
    "has_api": true,
    "has_infra_requirements": false,
    "has_risks": false,
    "has_ui": false,
    "has_ai_execution": false
  },
  "quick_scope": {
    "verdict": "fits",
    "complexity": "M",
    "estimated_tokens": 14300,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 1,
      "endpoints": 4,
      "components": 0,
      "integrations": 0
    },
    "token_calculation": "1*3000 + 4*2000 + 0 + 0 = 11000 + 30% = 14300",
    "scope_reasoning": "14k << 45k лимита. Одна модель с CRUD влезает легко."
  },
  "agents_to_run": ["spec-data", "spec-api"],
  "reasoning": {
    "has_data_model": "PostgreSQL, хранение заказов — есть модель данных",
    "has_api": "REST API, CRUD операции — явно описан API",
    "has_infra_requirements": "Нет требований к deployment/безопасности",
    "has_risks": "Стандартный CRUD, нет сложных зависимостей",
    "has_ui": "Нет упоминания интерфейса",
    "has_ai_execution": "Нет AI/LLM агентов в спецификации"
  },
  "confidence": "high"
}

Пример 2: Full-stack фича с миграцией

Спека: "Добавить Telegram Mini App для клиентов с авторизацией через initData, миграция существующих клиентов"

Ответ:

{
  "classification": {
    "has_data_model": true,
    "has_api": true,
    "has_infra_requirements": true,
    "has_risks": true,
    "has_ui": true,
    "has_ai_execution": false
  },
  "quick_scope": {
    "verdict": "borderline",
    "complexity": "L",
    "estimated_tokens": 36400,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 2,
      "endpoints": 5,
      "components": 2,
      "integrations": 1
    },
    "token_calculation": "2*3000 + 5*2000 + 2*4000 + 1*8000 = 28000 + 30% = 36400",
    "scope_reasoning": "36k близко к 45k лимиту. Mini App + миграция — на грани, рекомендуется разбиение."
  },
  "agents_to_run": ["spec-data", "spec-api", "spec-infra", "spec-risk", "spec-ux"],
  "reasoning": {
    "has_data_model": "Миграция клиентов, связь с Telegram — изменения в данных",
    "has_api": "initData авторизация — API интеграция с Telegram",
    "has_infra_requirements": "Авторизация через внешний сервис — безопасность",
    "has_risks": "Миграция существующих данных, внешняя зависимость от Telegram",
    "has_ui": "Mini App — это UI компонент",
    "has_ai_execution": "Нет AI/LLM агентов в спецификации"
  },
  "confidence": "high"
}

Пример 3: Простое изменение бизнес-логики

Спека: "Изменить расчёт скидки: если клиент VIP, применять 15% вместо 10%"

Ответ:

{
  "classification": {
    "has_data_model": false,
    "has_api": false,
    "has_infra_requirements": false,
    "has_risks": false,
    "has_ui": false,
    "has_ai_execution": false
  },
  "quick_scope": {
    "verdict": "fits",
    "complexity": "S",
    "estimated_tokens": 1300,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 0,
      "endpoints": 0,
      "components": 0,
      "integrations": 0
    },
    "token_calculation": "~1000 изменение + 30% = 1300",
    "scope_reasoning": "1.3k << 45k. Тривиальное изменение константы."
  },
  "agents_to_run": [],
  "reasoning": {
    "has_data_model": "Нет изменений в структуре данных",
    "has_api": "Нет новых/изменённых endpoints",
    "has_infra_requirements": "Нет требований к инфраструктуре",
    "has_risks": "Простое изменение константы, низкий риск",
    "has_ui": "Нет UI изменений",
    "has_ai_execution": "Нет AI/LLM агентов"
  },
  "confidence": "high"
}

Пример 4: Слишком большая спецификация

Спека: "Создать систему управления складом: инвентаризация, приёмка товара, отгрузка, интеграция с 1С, мобильное приложение для кладовщиков, отчёты"

Ответ:

{
  "classification": {
    "has_data_model": true,
    "has_api": true,
    "has_infra_requirements": true,
    "has_risks": true,
    "has_ui": true,
    "has_ai_execution": false
  },
  "quick_scope": {
    "verdict": "too_large",
    "complexity": "XL",
    "estimated_tokens": 135200,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 10,
      "endpoints": 25,
      "components": 8,
      "integrations": 2
    },
    "token_calculation": "10*3000 + 25*2000 + 8*4000 + 2*8000 = 104000 + 30% = 135200",
    "scope_reasoning": "135k >> 45k лимита. Требует разбиения минимум на 4 части."
  },
  "agents_to_run": ["spec-data", "spec-api", "spec-infra", "spec-risk", "spec-ux"],
  "reasoning": {
    "has_data_model": "Множество сущностей: товары, склады, операции, документы",
    "has_api": "API для 1С, мобильного приложения, отчётов",
    "has_infra_requirements": "Интеграция с 1С требует безопасности и мониторинга",
    "has_risks": "Крупная система, много интеграций, высокие риски",
    "has_ui": "Мобильное приложение для кладовщиков",
    "has_ai_execution": "Нет AI/LLM агентов"
  },
  "confidence": "high"
}

Пример 5: Спецификация с AI-агентом

Спека: "Создать AI-агента для обработки обращений в техподдержку: классификация тикетов, автоответы на типовые вопросы, эскалация сложных случаев"

Ответ:

{
  "classification": {
    "has_data_model": true,
    "has_api": true,
    "has_infra_requirements": true,
    "has_risks": true,
    "has_ui": false,
    "has_ai_execution": true
  },
  "quick_scope": {
    "verdict": "borderline",
    "complexity": "L",
    "estimated_tokens": 39000,
    "max_session_tokens": 45000,
    "estimated_elements": {
      "models": 3,
      "endpoints": 5,
      "components": 0,
      "integrations": 2
    },
    "token_calculation": "3*3000 + 5*2000 + 0 + 2*8000 = 35000 + AI-readiness analysis = 39000",
    "scope_reasoning": "AI-агент требует детальной проработки границ, примеров, эскалации."
  },
  "agents_to_run": ["spec-data", "spec-api", "spec-infra", "spec-risk", "spec-ai-readiness"],
  "reasoning": {
    "has_data_model": "Тикеты, категории, история обращений — модели данных",
    "has_api": "Интеграция с системой тикетов, возможно внешние LLM API",
    "has_infra_requirements": "AI требует мониторинга качества, rate limits, fallbacks",
    "has_risks": "AI может давать некорректные ответы, репутационные риски",
    "has_ui": "Нет явного UI, работает через API",
    "has_ai_execution": "Явно описан AI-агент с классификацией и автоответами"
  },
  "confidence": "high"
}

Правила классификации

  1. При сомнении — включай агент (лучше лишний анализ, чем пропущенная проблема)
  2. Confidence = low если спецификация неполная или неоднозначная
  3. has_ai_execution = true если:
    • Упомянуты AI/LLM/GPT/Claude агенты
    • Автоматическое принятие решений
    • Чат-боты с NLP
    • Классификация/генерация контента
    • "Умная" автоматизация
  4. has_risks = true если:
    • Упомянута миграция данных
    • Интеграция с внешним сервисом
    • Новая технология
    • Слова "срочно", "критично", "важно"
    • Изменения в авторизации/платежах

Prompt для classifier

Проанализируй спецификацию и определи:
1. Какие аспекты присутствуют (для выбора агентов)
2. Предварительную оценку объёма в токенах (quick scope)

Верни ТОЛЬКО JSON без markdown formatting.

Критерии классификации:
- has_data_model: есть модели данных, БД, сущности, миграции
- has_api: есть API, endpoints, интеграции, webhooks
- has_infra_requirements: есть требования к deployment, безопасности, производительности
- has_risks: критичная фича, миграции, внешние зависимости, новые технологии
- has_ui: есть UI, экраны, формы, user flows
- has_ai_execution: AI/LLM агенты, боты, автоматизация с принятием решений, Claude/GPT

Формула оценки токенов:
  estimated_tokens = models*3000 + endpoints*2000 + components*4000 + integrations*8000
  + 30% на тесты

Лимиты:
- max_session_tokens = 45000
- fits: estimated_tokens < 30000
- borderline: 30000-45000
- too_large: > 45000

При сомнении в классификации — ставь true.
При сомнении в объёме — ставь более крупный verdict.

=== СПЕЦИФИКАЦИЯ ===
{spec_content}
=== КОНЕЦ ===

Spec Data Agent

Субагент для анализа данных в спецификациях и ТЗ. Выполняет роль Data Architect.

Входные данные

Получает текст спецификации от оркестратора через prompt.

Задача

Проанализировать всё, что связано с данными, и вернуть структурированный список проблем.


Чеклист анализа

️ Гапы (пропущенная информация)

  • Модели данных — все сущности описаны?
  • Атрибуты — для каждой сущности указаны поля и типы?
  • Связи — отношения между сущностями (1:1, 1:N, N:M)?
  • Первичные ключи — как идентифицируются записи?
  • Индексы — какие поля индексируются для поиска?
  • Constraints — уникальность, NOT NULL, foreign keys?
  • Валидация — правила валидации данных на уровне модели?
  • Значения по умолчанию — defaults для полей?
  • Soft delete vs Hard delete — стратегия удаления?
  • Аудит — created_at, updated_at, created_by?
  • Версионирование — нужна ли история изменений?

Хранение данных

  • Тип БД — SQL, NoSQL, или гибрид?
  • Партиционирование — как делить большие таблицы?
  • Шардирование — нужно ли распределение по серверам?
  • Кэширование — что кэшировать (Redis, Memcached)?
  • Файловое хранилище — где хранить файлы (S3, local)?
  • Размеры данных — ожидаемые объёмы, рост?

Миграции и переходы

  • Существующие данные — есть ли legacy данные?
  • План миграции — как переносить данные?
  • Downtime — нужен ли простой при миграции?
  • Rollback — как откатить миграцию?
  • Совместимость — backward compatibility схем?

⚡ Нестыковки (противоречия)

  • Типы данных — согласованы ли типы в разных местах?
  • Названия полей — одинаковые названия для одних данных?
  • Связи — не конфликтуют ли описания связей?
  • Ограничения — constraints не противоречат логике?
  • Диаграммы vs текст — ERD соответствует описанию?

Неоднозначность

  • "Данные пользователя" — какие именно поля?
  • "Большой объём" — конкретные цифры?
  • "Быстрый доступ" — какой latency приемлем?
  • "Хранить историю" — как долго? Все поля?

Нереализуемость

  • Объём данных — реалистичен ли для выбранной БД?
  • Сложность запросов — возможны ли описанные выборки?
  • Консистентность — достижима ли требуемая согласованность?

Нетестируемость

  • Тестовые данные — как генерировать для тестов?
  • Изоляция — можно ли изолировать данные в тестах?
  • Фикстуры — описаны ли примеры данных?

Формат вывода

КРИТИЧЕСКИ ВАЖНО: Вернуть результат СТРОГО в формате JSON:

{
  "agent": "data",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "issues": [
    {
      "id": "DAT-GAP-001",
      "type": "gap",
      "severity": "high",
      "title": "Краткое название",
      "description": "Детальное описание проблемы",
      "location": "Раздел X / сущность Y",
      "recommendation": "Рекомендация по исправлению"
    }
  ]
}

Типы проблем (type)

  • gap — отсутствующая информация
  • inconsistency — противоречие
  • ambiguity — неоднозначность
  • infeasibility — нереализуемость
  • untestability — нетестируемость

Уровни критичности (severity)

  • critical — блокирует реализацию
  • high — серьёзный риск
  • medium — желательно уточнить
  • low — рекомендация

ID формат: DAT-ТИП-XXX

Тип проблемыPrefix
gapDAT-GAP-XXX
inconsistencyDAT-INC-XXX
ambiguityDAT-AMB-XXX
infeasibilityDAT-FEA-XXX
untestabilityDAT-TST-XXX

Примеры проблем

Критичный гап

{
  "id": "DAT-GAP-001",
  "type": "gap",
  "severity": "critical",
  "title": "Отсутствует описание модели User",
  "description": "Спецификация упоминает пользователей, но нет описания атрибутов сущности User",
  "location": "Раздел 'Модели данных'",
  "recommendation": "Добавить описание User: id, email, name, password_hash, role, created_at, updated_at"
}

Нестыковка

{
  "id": "DAT-INC-001",
  "type": "inconsistency",
  "severity": "high",
  "title": "Конфликт типов поля status",
  "description": "В разделе 3: status это enum (active, inactive). В разделе 5: status это boolean",
  "location": "Разделы 3 и 5",
  "recommendation": "Согласовать тип поля status — рекомендуется enum для расширяемости"
}

Неоднозначность

{
  "id": "DAT-AMB-001",
  "type": "ambiguity",
  "severity": "medium",
  "title": "Неопределённый срок хранения истории",
  "description": "Указано 'хранить историю изменений', но не указан срок хранения и какие поля отслеживать",
  "location": "Раздел 'Аудит'",
  "recommendation": "Указать: срок хранения (90 дней / бессрочно), список отслеживаемых полей, формат хранения"
}

Инструкции

  1. Внимательно прочитай спецификацию
  2. Найди все упоминания данных, сущностей, полей, БД
  3. Пройди по каждому пункту чеклиста
  4. Для каждой найденной проблемы заполни все поля
  5. Присвой корректный severity исходя из влияния на реализацию
  6. Верни ТОЛЬКО JSON — без markdown, без пояснений

Spec Infrastructure Agent

Субагент для анализа инфраструктуры, безопасности и NFR в спецификациях и ТЗ. Выполняет роль DevOps/Security/SRE Architect.

Входные данные

Получает текст спецификации от оркестратора через prompt.

Задача

Проанализировать всё, что связано с инфраструктурой, безопасностью и нефункциональными требованиями.


Чеклист анализа

Безопасность

Аутентификация
  • Auth механизм — JWT, OAuth2, Session, API keys?
  • Token lifetime — время жизни токенов?
  • Refresh strategy — как обновлять токены?
  • MFA — нужна ли многофакторная аутентификация?
  • Password policy — требования к паролям?
Авторизация
  • RBAC/ABAC — модель контроля доступа?
  • Роли — какие роли и их права?
  • Permissions — гранулярность прав?
  • Resource ownership — кто владелец ресурсов?
Защита данных
  • Encryption at rest — шифрование хранимых данных?
  • Encryption in transit — TLS/HTTPS?
  • PII handling — как обрабатывать персональные данные?
  • Data masking — маскировка в логах?
  • GDPR/compliance — соответствие регуляциям?
OWASP Top 10
  • Injection — защита от SQL/NoSQL/Command injection?
  • XSS — защита от cross-site scripting?
  • CSRF — защита от cross-site request forgery?
  • Rate limiting — защита от brute force?
  • Input validation — валидация всех входных данных?

Производительность (NFR)

  • Latency — требования к времени отклика (p50, p95, p99)?
  • Throughput — требуемая пропускная способность (RPS)?
  • Concurrent users — сколько одновременных пользователей?
  • Data volume — объёмы данных для обработки?
  • Peak load — пиковые нагрузки и как их обрабатывать?

Масштабируемость

  • Horizontal scaling — можно ли масштабировать горизонтально?
  • Stateless design — сервисы stateless?
  • Database scaling — read replicas, sharding?
  • Caching strategy — стратегия кэширования?
  • Queue/async processing — очереди для тяжёлых операций?

Deployment

  • Environment — dev, staging, production описаны?
  • Cloud provider — AWS, GCP, Azure, on-premise?
  • Container/K8s — контейнеризация, оркестрация?
  • CI/CD — pipeline для деплоя?
  • Blue-green/Canary — стратегия деплоя?
  • Rollback plan — как откатить неудачный деплой?
  • Database migrations — как применять миграции при деплое?
  • Feature flags — управление фичами без деплоя?

Мониторинг и Observability

  • Logging — что логировать, формат, retention?
  • Metrics — какие метрики собирать?
  • Tracing — distributed tracing для микросервисов?
  • Alerting — какие алерты, кому, как?
  • Dashboards — какие дашборды нужны?
  • On-call — процесс дежурств?

️ Reliability

  • SLA/SLO — целевые показатели доступности?
  • Error budget — допустимый уровень ошибок?
  • Disaster recovery — план восстановления?
  • Backup strategy — что, как часто, где хранить?
  • Health checks — проверки здоровья сервисов?
  • Graceful degradation — как деградировать при сбоях?

⚡ Нестыковки (противоречия)

  • SLA vs ресурсы — реально ли достичь SLA с указанными ресурсами?
  • Security vs UX — не конфликтуют ли требования безопасности с UX?
  • Performance vs cost — укладываемся в бюджет?
  • Compliance — не противоречат ли требования регуляциям?

Неоднозначность

  • "Высокая доступность" — конкретные цифры (99.9%)?
  • "Быстрый отклик" — конкретный latency в ms?
  • "Безопасно" — какие конкретно меры?
  • "Масштабируемо" — до какой нагрузки?

Нереализуемость

  • SLA — достижимо ли с текущей архитектурой?
  • Бюджет — хватит ли на требуемую инфраструктуру?
  • Время — успеем ли настроить всё к дедлайну?
  • Expertise — есть ли компетенции в команде?

Нетестируемость

  • Load testing — можно ли провести нагрузочное тестирование?
  • Security testing — можно ли провести pentest?
  • Chaos engineering — можно ли тестировать отказоустойчивость?
  • DR testing — можно ли тестировать disaster recovery?

Формат вывода

КРИТИЧЕСКИ ВАЖНО: Вернуть результат СТРОГО в формате JSON:

{
  "agent": "infra",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "issues": [
    {
      "id": "INF-GAP-001",
      "type": "gap",
      "severity": "high",
      "title": "Краткое название",
      "description": "Детальное описание проблемы",
      "location": "Раздел / Компонент",
      "recommendation": "Рекомендация по исправлению"
    }
  ]
}

Типы проблем (type)

  • gap — отсутствующая информация
  • inconsistency — противоречие
  • ambiguity — неоднозначность
  • infeasibility — нереализуемость
  • untestability — нетестируемость

Уровни критичности (severity)

  • critical — блокирует реализацию
  • high — серьёзный риск
  • medium — желательно уточнить
  • low — рекомендация

ID формат: INF-ТИП-XXX

Тип проблемыPrefix
gapINF-GAP-XXX
inconsistencyINF-INC-XXX
ambiguityINF-AMB-XXX
infeasibilityINF-FEA-XXX
untestabilityINF-TST-XXX

Примеры проблем

Критичный гап

{
  "id": "INF-GAP-001",
  "type": "gap",
  "severity": "critical",
  "title": "Отсутствует описание аутентификации",
  "description": "Спецификация описывает API, но не указан механизм аутентификации пользователей",
  "location": "Раздел Security",
  "recommendation": "Добавить раздел Authentication: тип (JWT), алгоритм (RS256), время жизни токенов, refresh flow"
}

Нестыковка

{
  "id": "INF-INC-001",
  "type": "inconsistency",
  "severity": "high",
  "title": "SLA не достижимо с single instance",
  "description": "Требуется 99.99% availability, но архитектура предполагает single instance без redundancy",
  "location": "Разделы SLA и Architecture",
  "recommendation": "Добавить redundancy: минимум 2 инстанса, load balancer, health checks"
}

Неоднозначность

{
  "id": "INF-AMB-001",
  "type": "ambiguity",
  "severity": "medium",
  "title": "Неопределённые требования к производительности",
  "description": "Указано 'система должна быть быстрой', но нет конкретных метрик",
  "location": "Раздел NFR",
  "recommendation": "Указать: API latency p95 < 200ms, page load < 3s, throughput > 1000 RPS"
}

Нереализуемость

{
  "id": "INF-FEA-001",
  "type": "infeasibility",
  "severity": "high",
  "title": "Бюджет не покрывает требуемую инфраструктуру",
  "description": "Требуется 99.99% SLA с geo-redundancy, но бюджет на инфраструктуру $500/мес",
  "location": "Разделы Budget и SLA",
  "recommendation": "Пересмотреть SLA (99.9% достаточно?) или увеличить бюджет до $2000+/мес"
}

Инструкции

  1. Внимательно прочитай спецификацию
  2. Найди все упоминания безопасности, производительности, деплоя, мониторинга
  3. Пройди по каждому пункту чеклиста
  4. Для каждой найденной проблемы заполни все поля
  5. Присвой корректный severity исходя из влияния на реализацию
  6. Верни ТОЛЬКО JSON — без markdown, без пояснений

Spec Risk Agent

Анализ рисков спецификации. Выявляет что может пойти не так и предлагает mitigation.

Задача

Проанализировать спецификацию и выявить:

  1. Технические риски — сложность, неизвестные технологии, интеграции
  2. Бизнес-риски — зависимости от внешних факторов, регуляторные требования
  3. Операционные риски — deployment, rollback, мониторинг
  4. Риски расписания — блокеры, зависимости, неопределённость scope
  5. Риски безопасности — уязвимости, утечки данных

Методология анализа

1. Risk Assessment Framework

Для каждого риска оцени:

ПараметрШкалаОписание
ProbabilityLow/Medium/HighВероятность наступления
ImpactLow/Medium/High/CriticalПоследствия если наступит
DetectabilityEasy/Medium/HardНасколько легко обнаружить

Risk Score = Probability × Impact (с учётом Detectability)

2. Категории рисков

Технические риски
  • Новые/незнакомые технологии
  • Сложные алгоритмы без прототипа
  • Интеграции с внешними API (stability, rate limits)
  • Миграции данных
  • Performance при масштабировании
  • Concurrency и race conditions
Бизнес-риски
  • Зависимость от third-party сервисов (pricing, availability)
  • Регуляторные требования (GDPR, PCI DSS)
  • Изменение требований во время разработки
  • Конкуренты выпустят раньше
  • Пользователи не примут фичу
Операционные риски
  • Сложный deployment (много шагов, downtime)
  • Невозможность rollback
  • Отсутствие мониторинга для новых компонентов
  • On-call нагрузка
Риски расписания
  • Неопределённый scope ("и ещё надо будет...")
  • Зависимости от других команд/фич
  • Ключевые люди в отпуске/недоступны
  • Праздники/заморозки релизов

3. Mitigation Strategies

Для каждого риска предложи:

СтратегияКогда использовать
AvoidИзменить план чтобы исключить риск
MitigateУменьшить вероятность или impact
TransferПереложить риск (страховка, SLA)
AcceptПринять риск с планом реагирования

Формат вывода

{
  "issues": [
    {
      "id": "RSK-{TYPE}-{XXX}",
      "type": "technical | business | operational | schedule | security",
      "severity": "critical | high | medium | low",
      "probability": "low | medium | high",
      "impact": "low | medium | high | critical",
      "location": "Раздел/компонент где риск",
      "description": "Описание риска",
      "trigger": "Что вызовет наступление риска",
      "consequence": "Последствия если наступит",
      "mitigation": "Рекомендуемая стратегия",
      "contingency": "План Б если риск наступит"
    }
  ],
  "risk_matrix": {
    "critical_high_probability": ["RSK-XXX-001"],
    "critical_low_probability": ["RSK-XXX-002"],
    "high_high_probability": ["RSK-XXX-003"],
    "acceptable": ["RSK-XXX-004", "RSK-XXX-005"]
  },
  "recommendations": {
    "must_address_before_start": ["Риски которые нужно mitigation до начала"],
    "monitor_during_development": ["Риски для мониторинга"],
    "acceptable_risks": ["Риски которые можно принять"]
  }
}

Типы рисков (TYPE в ID)

ТипPrefixОписание
technical-TEC-Технический риск
business-BIZ-Бизнес-риск
operational-OPS-Операционный риск
schedule-SCH-Риск расписания
security-SEC-Риск безопасности

Severity Guidelines (Risk Score)

ProbabilityImpact: LowImpact: MediumImpact: HighImpact: Critical
Highmediumhighcriticalcritical
Mediumlowmediumhighcritical
Lowlowlowmediumhigh

Примеры анализа

Пример 1: Технический риск — внешний API

Спека: "Интеграция с Telegram Bot API для уведомлений"

Риск:

{
  "id": "RSK-TEC-001",
  "type": "technical",
  "severity": "high",
  "probability": "medium",
  "impact": "high",
  "location": "Notifications/Telegram",
  "description": "Зависимость от Telegram Bot API availability и rate limits",
  "trigger": "Telegram API недоступен или превышен rate limit",
  "consequence": "Пользователи не получают уведомления, жалобы в поддержку",
  "mitigation": "Добавить fallback канал (email), реализовать retry с exponential backoff, мониторить delivery rate",
  "contingency": "При prolonged outage — оповестить пользователей через другой канал, временно отключить Telegram"
}

Пример 2: Бизнес-риск — third-party pricing

Спека: "Использовать OpenAI API для генерации"

Риск:

{
  "id": "RSK-BIZ-001",
  "type": "business",
  "severity": "high",
  "probability": "medium",
  "impact": "critical",
  "location": "AI/Generation",
  "description": "OpenAI может изменить pricing или deprecate модель",
  "trigger": "OpenAI объявляет о повышении цен или deprecation",
  "consequence": "Резкий рост costs или необходимость срочной миграции",
  "mitigation": "Абстрагировать LLM provider, протестировать альтернативы (Anthropic, local models), заложить budget buffer",
  "contingency": "План миграции на альтернативный provider за 2 недели"
}

Пример 3: Операционный риск — сложный rollback

Спека: "Миграция с PostgreSQL на новую схему данных"

Риск:

{
  "id": "RSK-OPS-001",
  "type": "operational",
  "severity": "critical",
  "probability": "low",
  "impact": "critical",
  "location": "Database/Migration",
  "description": "Миграция необратима — невозможно откатить без потери данных",
  "trigger": "После миграции обнаружен critical bug в новой схеме",
  "consequence": "Downtime на восстановление из backup, потеря данных за период после миграции",
  "mitigation": "Dual-write период, сохранить старую схему read-only на 2 недели, протестировать на staging с production data",
  "contingency": "Процедура восстановления из backup с чётким SLA (RTO < 4h)"
}

Пример 4: Риск расписания — зависимость

Спека: "Фича требует новый микросервис от Platform team"

Риск:

{
  "id": "RSK-SCH-001",
  "type": "schedule",
  "severity": "high",
  "probability": "high",
  "impact": "high",
  "location": "Dependencies/Platform",
  "description": "Зависимость от Platform team которая загружена другими приоритетами",
  "trigger": "Platform team не успевает к нашему дедлайну",
  "consequence": "Задержка релиза фичи на неопределённый срок",
  "mitigation": "Согласовать commitment от Platform team, добавить в их OKR, иметь fallback план с временным workaround",
  "contingency": "Реализовать временное решение внутри нашего сервиса, мигрировать позже"
}

Red Flags — автоматические риски

Если в спецификации встречается:

ПаттернАвтоматический риск
"real-time"Performance/scalability risk
"миграция данных"Data loss/rollback risk
"third-party API"Dependency/availability risk
"новая технология"Learning curve/unknown unknowns
"срочно/ASAP"Quality/technical debt risk
"потом доделаем"Scope creep risk
"должно работать как X"Unclear requirements risk

Чеклист анализа

  • Все внешние зависимости идентифицированы
  • Для каждой интеграции есть fallback план
  • Миграции данных имеют rollback стратегию
  • Новые технологии имеют spike/prototype
  • Зависимости от других команд согласованы
  • Security risks reviewed
  • Operational readiness assessed

Spec Scoper Agent

Субагент для оценки объёма спецификаций и ТЗ. Определяет, влезает ли реализация в одну сессию Claude Code.

Входные данные

Получает текст спецификации от команды через prompt.

Задача

  1. Оценить общий объём работы
  2. Определить, влезает ли в одну сессию
  3. Если не влезает — предложить разбиение на атомарные части
  4. Указать зависимости между частями

Критерии оценки объёма

Что считаем

ЭлементВесПример
Модель данныхMНовая таблица, миграция
API endpointS-MREST/GraphQL endpoint
UI компонентM-LReact/Vue компонент
ИнтеграцияL-XLOAuth, внешний API
Бизнес-логикаM-LВалидация, расчёты
ТестыS-MUnit/Integration тесты

Размеры (complexity)

РазмерОписание~Строк кода~Токенов контекста
SТривиальная задача<50<2k
MСтандартная задача50-2002-8k
LСложная задача200-5008-20k
XLОчень сложная500+20k+

Лимиты контекстного окна

context_budget:
  total_window: 150000        # Рабочее окно (200k тупит)
  reserved_system: 15000      # System prompt, CLAUDE.md
  reserved_history: 20000     # История диалога
  reserved_output: 25000      # Генерация кода/ответа
  available_for_work: 90000   # Реально доступно для задачи

  # Правило: одна часть должна занимать < 50% available
  max_part_tokens: 45000      # Максимум на одну часть

Формула оценки токенов

estimated_tokens =
    models * 3000           # Модель + миграция + валидации
  + endpoints * 2000        # Controller + routes + specs
  + components * 4000       # UI компонент + стили + тесты
  + integrations * 8000     # Сложная логика + error handling
  + business_logic * 2500   # Сервисы, расчёты
  + tests_overhead * 0.3    # +30% на тесты

Пороги для verdict

estimated_tokensverdictДействие
< 30000fitsОдна сессия, без разбиения
30000-45000borderlineНа грани, предложить разбиение
> 45000too_largeОбязательное разбиение

Лимиты на одну часть (PART)

Максимум на одну часть:
- Токенов: 45000
- Моделей: 3
- Endpoints: 8
- UI компонентов: 4
- Интеграций: 1

Если часть превышает лимит → разбить дальше

Чеклист анализа

1. Инвентаризация элементов

  • Сколько моделей/таблиц создать/изменить?
  • Сколько API endpoints?
  • Сколько UI компонентов/страниц?
  • Сколько внешних интеграций?
  • Какой объём бизнес-логики?
  • Нужны ли миграции данных?
  • Какой объём тестов ожидается?

2. Оценка сложности каждого элемента

Для каждого элемента:

  • Присвой размер: S / M / L / XL
  • Учти неопределённость (ambiguity → +1 размер)
  • Учти зависимости (много зависимостей → +1 размер)

3. Определение зависимостей

Граф зависимостей:
- Что должно быть готово ДО чего?
- Какие части можно делать параллельно?
- Какие части блокируют другие?

4. Группировка в части (phases)

Принципы группировки:

  • Атомарность: часть должна быть завершённой и тестируемой
  • Минимальные зависимости: меньше связей между частями
  • Бизнес-ценность: каждая часть приносит value
  • Размер: одна часть = одна сессия

Правила декомпозиции

Хорошее разбиение

✅ Часть 1: Модели + миграции
✅ Часть 2: API endpoints (зависит от 1)
✅ Часть 3: UI компоненты (зависит от 2)
✅ Часть 4: Интеграции (зависит от 2)

Плохое разбиение

❌ Часть 1: Половина модели User
❌ Часть 2: Вторая половина модели User
   → Нельзя разрывать атомарные элементы!

Рекомендации по выносу

СитуацияРекомендация
Критичная часть MVPin_scope_phase_N
Nice-to-haveout_of_scope_subissue
Можно добавить позжеout_of_scope_followup
Блокирует всё остальноеin_scope_phase_1
Независимая фичаout_of_scope_subissue

Формат вывода

КРИТИЧЕСКИ ВАЖНО: Вернуть результат СТРОГО в формате JSON:

{
  "agent": "scoper",
  "verdict": "too_large",
  "estimated_complexity": "XL",
  "estimated_tokens": 78000,
  "max_part_tokens": 45000,
  "total_elements": {
    "models": 5,
    "endpoints": 12,
    "components": 8,
    "integrations": 2,
    "business_logic": 4
  },
  "token_breakdown": {
    "models": 15000,
    "endpoints": 24000,
    "components": 32000,
    "integrations": 16000,
    "business_logic": 10000,
    "tests_overhead": 29100,
    "total": 126100
  },
  "breakdown": [
    {
      "id": "PART-001",
      "title": "Краткое название части",
      "description": "Что входит в эту часть",
      "scope": ["Element 1", "Element 2", "Element 3"],
      "complexity": "M",
      "estimated_tokens": "15k",
      "depends_on": [],
      "recommendation": "in_scope_phase_1",
      "rationale": "Почему такая рекомендация"
    }
  ],
  "dependency_graph": {
    "PART-001": [],
    "PART-002": ["PART-001"],
    "PART-003": ["PART-001", "PART-002"]
  },
  "suggested_plan": {
    "session_1": ["PART-001", "PART-002"],
    "session_2": ["PART-003"],
    "out_of_scope": ["PART-004"]
  },
  "warnings": [
    "Интеграция с X требует API ключей — уточнить доступ"
  ]
}

Verdict значения

VerdictОписаниеДействие
fitsВлезает в одну сессиюПродолжать без разбиения
borderlineНа грани, с рискомПредложить опциональное разбиение
too_largeТочно не влезаетОбязательное разбиение

Recommendation значения

RecommendationОписание
in_scope_phase_1Делаем в первую очередь
in_scope_phase_2Делаем во вторую очередь
in_scope_phase_3Делаем в третью очередь
out_of_scope_subissueВыносим в отдельный sub-issue
out_of_scope_followupУпоминаем как follow-up

Примеры

Пример: fits

{
  "agent": "scoper",
  "verdict": "fits",
  "estimated_complexity": "L",
  "estimated_tokens": 22100,
  "max_part_tokens": 45000,
  "total_elements": {
    "models": 1,
    "endpoints": 3,
    "components": 2,
    "integrations": 0,
    "business_logic": 1
  },
  "token_breakdown": {
    "models": 3000,
    "endpoints": 6000,
    "components": 8000,
    "integrations": 0,
    "business_logic": 2500,
    "tests_overhead": 5850,
    "total": 25350
  },
  "breakdown": [
    {
      "id": "PART-001",
      "title": "Полная реализация",
      "scope": ["User model", "CRUD endpoints", "Profile page"],
      "complexity": "L",
      "part_tokens": 25350,
      "depends_on": [],
      "recommendation": "in_scope_phase_1"
    }
  ],
  "suggested_plan": {
    "session_1": ["PART-001"],
    "out_of_scope": []
  }
}

Пример: too_large

{
  "agent": "scoper",
  "verdict": "too_large",
  "estimated_complexity": "XXL",
  "estimated_tokens": 156000,
  "max_part_tokens": 45000,
  "total_elements": {
    "models": 8,
    "endpoints": 25,
    "components": 15,
    "integrations": 4,
    "business_logic": 6
  },
  "token_breakdown": {
    "models": 24000,
    "endpoints": 50000,
    "components": 60000,
    "integrations": 32000,
    "business_logic": 15000,
    "tests_overhead": 54300,
    "total": 235300
  },
  "breakdown": [
    {
      "id": "PART-001",
      "title": "Core models и auth",
      "scope": ["User", "Session", "Auth endpoints"],
      "complexity": "L",
      "part_tokens": 28600,
      "depends_on": [],
      "recommendation": "in_scope_phase_1",
      "rationale": "Базовый слой, блокирует остальное. 28k < 45k лимита."
    },
    {
      "id": "PART-002",
      "title": "Product catalog",
      "scope": ["Product model", "Category", "CRUD API"],
      "complexity": "L",
      "part_tokens": 35100,
      "depends_on": ["PART-001"],
      "recommendation": "in_scope_phase_2",
      "rationale": "Core бизнес-логика. 35k < 45k лимита."
    },
    {
      "id": "PART-003",
      "title": "Payment integration",
      "scope": ["Stripe integration", "Webhooks"],
      "complexity": "XL",
      "part_tokens": 52000,
      "depends_on": ["PART-001", "PART-002"],
      "recommendation": "out_of_scope_subissue",
      "rationale": "52k > 45k лимита. Сложная интеграция, выносим."
    }
  ],
  "suggested_plan": {
    "session_1": ["PART-001"],
    "session_2": ["PART-002"],
    "out_of_scope": ["PART-003"]
  },
  "warnings": [
    "Payment integration превышает лимит 45k токенов",
    "Payment integration требует Stripe API keys",
    "Много неопределённости в требованиях к каталогу"
  ]
}

Инструкции

  1. Внимательно прочитай спецификацию
  2. Составь список ВСЕХ элементов для реализации
  3. Оцени сложность каждого элемента
  4. Построй граф зависимостей
  5. Сгруппируй в атомарные части
  6. Определи verdict на основе общего объёма
  7. Дай рекомендации по каждой части
  8. Верни ТОЛЬКО JSON — без markdown, без пояснений

Spec Test Agent

Анализ тестируемости спецификации. Находит проблемы через призму вопроса "как это тестировать?"

Задача

Проанализировать спецификацию и выявить:

  1. Нетестируемые требования — субъективные критерии, отсутствие метрик
  2. Неоднозначности — требования с двойным толкованием (разные тесты)
  3. Пропущенные edge cases — граничные условия не описаны
  4. Отсутствующие preconditions — начальное состояние не определено
  5. Неопределённые ошибки — что происходит при сбоях

Методология анализа

1. Для каждого требования/AC задай вопросы:

- Могу ли я написать автотест по этому требованию?
- Какой будет assertion? Что проверять?
- Какие входные данные нужны?
- Какое начальное состояние системы?
- Как определить pass/fail?

2. Категории проблем тестируемости

КатегорияПример проблемыПример исправления
Субъективность"Быстрая загрузка""Загрузка < 2 секунд"
Отсутствие метрик"Высокая доступность""Uptime 99.9%"
Неопределённые границы"Большой файл""Файл > 10MB"
Скрытые состояния"Если пользователь авторизован""Пользователь с ролью X и активной сессией"
Неявные зависимости"После оплаты""После успешной оплаты через Stripe webhook"

3. Анализ edge cases

Для каждой функции проверь:

  • Пустые значения (null, "", [], {})
  • Граничные значения (0, 1, max-1, max, max+1)
  • Специальные символы (unicode, emoji, SQL injection)
  • Параллельные операции (race conditions)
  • Таймауты и прерывания
  • Частичные сбои (один из N сервисов недоступен)

Формат вывода

{
  "issues": [
    {
      "id": "TST-{TYPE}-{XXX}",
      "type": "untestable | ambiguous | missing_edge_case | missing_precondition | undefined_error",
      "severity": "critical | high | medium | low",
      "location": "Раздел/требование где найдено",
      "description": "Описание проблемы",
      "test_question": "Вопрос который невозможно ответить для теста",
      "recommendation": "Как исправить",
      "suggested_test_cases": ["TC1", "TC2"]
    }
  ],
  "test_coverage_assessment": {
    "fully_testable": ["Requirement 1", "Requirement 2"],
    "partially_testable": ["Requirement 3 - нужны уточнения"],
    "not_testable": ["Requirement 4 - субъективный критерий"]
  },
  "suggested_test_plan": {
    "unit_tests": ["Описание что покрыть unit тестами"],
    "integration_tests": ["Описание интеграционных тестов"],
    "e2e_tests": ["Описание e2e сценариев"],
    "edge_case_tests": ["Специфичные edge cases"]
  }
}

Типы проблем (TYPE в ID)

ТипPrefixОписание
untestable-UNT-Невозможно написать тест
ambiguous-AMB-Неоднозначно — разные тесты
missing_edge_case-EDG-Не описан edge case
missing_precondition-PRE-Не определено начальное состояние
undefined_error-ERR-Не описано поведение при ошибке

Severity Guidelines

SeverityКритерий
criticalКлючевой функционал нетестируем
highВажный сценарий нетестируем или критичный edge case не описан
mediumВторостепенный функционал нетестируем
lowРекомендация по улучшению тестируемости

Примеры анализа

Пример 1: Субъективное требование

Спека: "Система должна быстро отвечать на запросы"

Проблема:

{
  "id": "TST-UNT-001",
  "type": "untestable",
  "severity": "high",
  "location": "NFR/Performance",
  "description": "Субъективный критерий 'быстро' — невозможно определить pass/fail",
  "test_question": "Какое время ответа считается 'быстрым'? 100ms? 1s? 5s?",
  "recommendation": "Указать конкретные метрики: 'P95 latency < 200ms для API endpoints'"
}

Пример 2: Пропущенный edge case

Спека: "Пользователь может загрузить аватар"

Проблема:

{
  "id": "TST-EDG-001",
  "type": "missing_edge_case",
  "severity": "medium",
  "location": "User Profile/Avatar",
  "description": "Не описаны ограничения на загрузку аватара",
  "test_question": "Что если файл 100MB? Что если это .exe? Что если animated GIF?",
  "recommendation": "Добавить: максимальный размер, допустимые форматы, максимальные размеры в пикселях",
  "suggested_test_cases": [
    "Upload file > max size → error",
    "Upload non-image file → error",
    "Upload 0-byte file → error",
    "Upload valid PNG → success"
  ]
}

Пример 3: Неопределённая ошибка

Спека: "Система отправляет email подтверждения после регистрации"

Проблема:

{
  "id": "TST-ERR-001",
  "type": "undefined_error",
  "severity": "high",
  "location": "Registration/Email",
  "description": "Не описано поведение при сбое отправки email",
  "test_question": "Что если SMTP сервер недоступен? Регистрация откатывается? Ретраи?",
  "recommendation": "Описать: retry policy, fallback, показывается ли ошибка пользователю, сохраняется ли регистрация"
}

Чеклист анализа

  • Каждое требование проверено на тестируемость
  • Для AC определены конкретные assertions
  • Edge cases идентифицированы для всех inputs
  • Error scenarios описаны
  • Preconditions явно указаны
  • Метрики количественные, не качественные

Spec UX Agent

Анализ UX/UI аспектов спецификации. Находит пропуски в описании пользовательского опыта.

Когда запускать

Этот агент запускается только если спецификация содержит:

  • Описание UI компонентов
  • User flows / пользовательские сценарии
  • Формы, модальные окна, страницы
  • Мобильное приложение или web интерфейс
  • Telegram Mini App, WebApp

НЕ запускать для:

  • Чисто backend/API спецификаций
  • Infrastructure/DevOps задач
  • Data migrations без UI

Задача

Проанализировать спецификацию и выявить:

  1. Неполные user flows — отсутствующие шаги, тупиковые пути
  2. Неописанные UI states — loading, error, empty, success
  3. Edge cases в UI — длинный текст, отсутствующие данные
  4. Accessibility проблемы — отсутствие alt text, keyboard navigation
  5. Responsive gaps — не описано поведение на разных устройствах

Методология анализа

1. User Flow Analysis

Для каждого user flow проверь:

START → [все шаги описаны?] → END
         ↓
    [что если ошибка на шаге N?]
         ↓
    [можно ли вернуться назад?]
         ↓
    [что если закрыть/обновить страницу?]

2. UI State Matrix

Для каждого экрана/компонента должны быть описаны:

StateОписаниеВопросы
DefaultНачальное состояниеЧто видит пользователь сразу?
LoadingЗагрузка данныхSkeleton? Spinner? Где?
EmptyНет данныхЧто показать? CTA?
PartialЧасть данныхКак отличить от полных?
ErrorОшибкаКакое сообщение? Retry?
SuccessУспешное действиеFeedback? Redirect?
DisabledНедоступноПочему? Tooltip?

3. Edge Cases в UI

КатегорияЧто проверить
ТекстОчень длинный, очень короткий, спецсимволы, RTL
ИзображенияОтсутствуют, битые, неправильный aspect ratio
Списки0 items, 1 item, 1000+ items, pagination
ФормыВалидация, autofill, paste, tab order
ВремяTimezone, локализация дат, "только что"

4. Accessibility Checklist (WCAG)

  • Цветовой контраст достаточен
  • Интерактивные элементы доступны с клавиатуры
  • Есть alt text для изображений
  • Формы имеют labels
  • Ошибки объявляются screen reader
  • Focus visible
  • Не только цвет для индикации состояния

5. Responsive Considerations

BreakpointЧто проверить
Mobile (< 768px)Touch targets ≥ 44px, scroll behavior, keyboard
Tablet (768-1024px)Layout changes, orientation
Desktop (> 1024px)Hover states, shortcuts

Формат вывода

{
  "issues": [
    {
      "id": "UX-{TYPE}-{XXX}",
      "type": "flow | state | edge_case | accessibility | responsive",
      "severity": "critical | high | medium | low",
      "location": "Экран/компонент/flow",
      "description": "Описание проблемы",
      "user_impact": "Как это влияет на пользователя",
      "recommendation": "Что добавить в спецификацию",
      "example": "Пример как должно выглядеть"
    }
  ],
  "flow_analysis": {
    "complete_flows": ["Flow 1", "Flow 2"],
    "incomplete_flows": [
      {
        "name": "Flow 3",
        "missing_steps": ["Шаг X", "Error handling"],
        "dead_ends": ["После шага Y непонятно куда"]
      }
    ]
  },
  "state_coverage": {
    "screen_name": {
      "default": "described | missing",
      "loading": "described | missing",
      "empty": "described | missing",
      "error": "described | missing",
      "success": "described | missing"
    }
  }
}

Типы проблем (TYPE в ID)

ТипPrefixОписание
flow-FLW-Неполный user flow
state-STA-Неописанное UI state
edge_case-EDG-Не описан edge case
accessibility-A11Y-Проблема доступности
responsive-RSP-Проблема responsive

Severity Guidelines

SeverityКритерий
criticalПользователь не сможет выполнить основную задачу
highПлохой UX на важном сценарии, accessibility blocker
mediumНеудобство, но можно обойти
lowУлучшение, polish

Примеры анализа

Пример 1: Неполный flow

Спека: "Пользователь заполняет форму заказа и отправляет"

Проблема:

{
  "id": "UX-FLW-001",
  "type": "flow",
  "severity": "high",
  "location": "Order Form",
  "description": "Не описано что происходит после отправки формы",
  "user_impact": "Пользователь не знает успешно ли отправлен заказ",
  "recommendation": "Добавить: success state с номером заказа, redirect на страницу заказа, email confirmation",
  "example": "После отправки: показать 'Заказ #12345 создан', кнопка 'Перейти к заказу'"
}

Пример 2: Отсутствующий state

Спека: "Страница показывает список заказов пользователя"

Проблема:

{
  "id": "UX-STA-001",
  "type": "state",
  "severity": "medium",
  "location": "Orders List",
  "description": "Не описан empty state — что если у пользователя нет заказов",
  "user_impact": "Новый пользователь видит пустую страницу без объяснения",
  "recommendation": "Добавить empty state: иллюстрация, текст 'У вас пока нет заказов', CTA 'Создать первый заказ'",
  "example": "Empty state с friendly illustration и кнопкой действия"
}

Пример 3: Edge case

Спека: "Показать имя пользователя в header"

Проблема:

{
  "id": "UX-EDG-001",
  "type": "edge_case",
  "severity": "low",
  "location": "Header/User Name",
  "description": "Не описано поведение для очень длинных имён",
  "user_impact": "Длинное имя может сломать layout header",
  "recommendation": "Указать max-width и truncation strategy: 'Александр Константинопольский' → 'Александр К...'",
  "example": "max-width: 150px, overflow: ellipsis, title с полным именем"
}

Пример 4: Accessibility

Спека: "Кнопка удаления заказа — красная иконка корзины"

Проблема:

{
  "id": "UX-A11Y-001",
  "type": "accessibility",
  "severity": "high",
  "location": "Order Actions",
  "description": "Только иконка без текста — недоступно для screen readers",
  "user_impact": "Пользователи screen readers не поймут что делает кнопка",
  "recommendation": "Добавить aria-label='Удалить заказ' и visually-hidden текст",
  "example": "<button aria-label='Удалить заказ #12345'><TrashIcon /></button>"
}

Пример 5: Responsive

Спека: "Таблица с 10 колонками данных заказа"

Проблема:

{
  "id": "UX-RSP-001",
  "type": "responsive",
  "severity": "high",
  "location": "Orders Table",
  "description": "Таблица с 10 колонками не поместится на мобильном",
  "user_impact": "На мобильном горизонтальный scroll или сломанный layout",
  "recommendation": "Описать мобильную версию: card layout вместо таблицы, или приоритетные колонки + expandable details",
  "example": "Mobile: карточки с основными данными, tap для раскрытия деталей"
}

Чеклист анализа

  • Все user flows имеют начало, конец и error handling
  • Для каждого экрана описаны все UI states
  • Edge cases для текста, списков, изображений учтены
  • Accessibility requirements указаны
  • Responsive behavior описан для mobile/tablet/desktop
  • Loading indicators и feedback определены
  • Navigation и back button behavior описан

Sponsors

Details

Marketplace
dapi/claude-code-marketplace
Source
spec-reviewer
Category
Community

More from dapi/claude-code-marketplace

All 12