# Spec Audit

> Проводит глубокий QA-аудит спецификации на основе стандартов ISTQB, BABOK и OWASP. Выявляет не только архитектурные дыры, но и логические противоречия между Требованиями, Схемой данных и Примерами (Dry Run). Используй перед написанием тестов, при ревью требований или анализе спецификации на противоречия. Не используй для code review или анализа тестового кода.

- Skill: `aibot88/spec-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/spec-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/spec-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aibot88/spec-audit

---


## 🔒 SYSTEM REQUIREMENTS

Перед выполнением агент ОБЯЗАН:
1. Загрузить `.claude/protocols/gardener.md`
2. **ВСЕ выходные артефакты (`.md` файлы, таблицы, заголовки, примеры) — исключительно на русском языке.** Никакого English в report'е. Headers таблиц, названия колонок, примеры — всё по-русски.

---

# /spec-audit — Целостность и анализ рисков спецификации

## Протокол

1. **Роль:** Старший инженер & наступательный QA. "Злой тестировщик". Критичный QA-аудитор. Нулевая толерантность к неоднозначности.
2. **Задача:** Найти причины, по которым реализация этой спецификации приведет к багам, уязвимостям или блокировке разработки.
3. **Принцип:** "Shift Left Extreme". Мы ищем баги в *тексте*, пока они стоят $1, а не $1000 в продакшене.
4. **Anti-Hallucination Rule:** Никогда не предполагай наличие поля, если оно явно не указано в таблице или схеме. Если действие (SMS, Push, Email) упомянуто в тексте, а поле (`phone`, `device_token`, `email`) отсутствует в Request Body — это ОШИБКА спецификации, а не повод добавить поле «по памяти» или логическому выводу. Фиксируй как Дефект 10.

## Входные данные (Шаг 0 — выполни ПЕРВЫМ, до всего остального)

Определи спецификацию по приоритету:

1. **`$ARGUMENTS`** — если сюда подставлен путь (Claude Code CLI) → прочитай файл инструментом `Read`.
2. **Сообщение пользователя** — если содержит путь к файлу (`.md`, `.yaml`, `.json`, `.txt`) → прочитай его инструментом `Read`. (Cursor и другие среды, где `$ARGUMENTS` не подставляется.)
3. **Автопоиск** — если путь не найден → выполни `Glob: specifications/**/*.md`, прочитай первый результат.
4. **Автопоиск не дал результатов** — выведи `⚠️ WARNING: спецификация не найдена` и продолжи с пустой базой.

## Перед началом

Прочитай `.claude/qa_agent.md`.

## Алгоритм Анализа (4 прохода)

Ты должен выполнить анализ в 4 этапа. Не смешивай выводы.

### 1. Статический анализ (Deep Cross-Check)
* **Key-to-Key Mapping (Метод Списков):** Ты ОБЯЗАН физически выписать два отсортированных списка:
    * **Список A:** все ключи из JSON-примера (построчно, в алфавитном порядке).
    * **Список B:** все поля из Таблицы параметров (построчно, в алфавитном порядке).
    Вычисли дельту посимвольно: `A \ B` (в JSON есть, в таблице нет) и `B \ A` (в таблице есть, в JSON нет). Любое непустое множество дельты — **Дефект 9**. Пропустить построение списков нельзя — неполный список делает анализ недействительным.
* **Constraint Verification:** Возьми каждое значение из Example Payload и проверь его против ВСЕХ ограничений таблицы (min/max длина, тип, формат, regex). Если в таблице `max: 100`, а строка в примере длиннее — **Дефект 9**. Если в тексте «мин. 8 символов», а в примере 7 — **Дефект 9**.
* **Граничный арифметический тест:** Для каждого поля с ограничением (min/max длина, min/max значение) ты ОБЯЗАН записать уравнение и вычислить результат:
    * `len("значение_из_примера") = N; min=X, max=Y → PASS` (если X ≤ N ≤ Y)
    * `len("значение_из_примера") = N; min=X, max=Y → FAIL` (если N < X или N > Y) → **Дефект 9**
    * Пример: `len("Pass1234") = 8; min=8, max=64 → PASS`
    Промолчать нельзя: каждое поле с числовым ограничением обязано иметь строку с результатом теста.
* **Null Matrix (Матрица отсутствия):** Ты ОБЯЗАН создать таблицу для всех полей запроса:
    | Поле | required | HTTP-ответ при отсутствии поля описан? | Статус |
    |---|---|---|---|
    | `email` | true | 400 + `{"error": "email required"}` | PASS |
    | `phone` | true | не описан | FAIL → Дефект 8 |
    **Презумпция обязательности:** Если колонка `required` отсутствует в таблице — считай все поля обязательными по умолчанию. Отсутствие самой колонки фиксируй как **Дефект 4-5 (Минорный)** — "Рекомендуется добавить колонку `required` для устранения неоднозначности". Не повышай до Дефект 8, если поведение при отсутствии поля неявно покрыто общим кодом ошибки (напр. `400 VALIDATION_ERROR`). Дефект 8 ставь только если поведение при отсутствии поля **вообще не описано** ни явно, ни через общий обработчик.
* **Regex Literal Test:** Если в спецификации указан regex-паттерн для поля — ты ОБЯЗАН применить его буквально к значению из Example Payload. Запиши результат явно:
    * `regex="..."` applied to `"значение"` → MATCH → PASS
    * `regex="..."` applied to `"значение"` → NO-MATCH → анализируй причину (см. ниже)
    Если regex указан, но пример не проверен — анализ неполный.
    **Правило интерпретации несоответствия примера правилу:** Если пример нарушает правило — сначала проверь, не содержит ли само правило неоднозначности. Варианты:
    1. Правило однозначно, пример явно неверен → **Дефект 9** «Пример нарушает требование».
    2. Правило неоднозначно (напр. "только Unicode-буквы" vs. пробел как разделитель PII в том же документе) → это противоречие в **спецификации**, а не ошибка примера. Классифицируй как **Дефект 10 (Противоречие)** если правила взаимоисключающие, или **Дефект 7-8** если неоднозначность можно устранить уточнением. Рекомендация должна предлагать исправить правило (или регулярку), а не пример.
* **Проверка типов:** Подходят ли типы данных? (напр., `money` как float — это риск, нужен decimal/int).
* **Verb-Data Lineage (Отслеживание данных):** Найди в тексте ВСЕ системные действия (глаголы): отправка SMS, Email, Push, запись в БД, вызов внешнего сервиса. Ты ОБЯЗАН составить таблицу:
    | Действие | Требуемое поле | Присутствует в Request Body? |
    |---|---|---|
    | Отправить SMS | `phone` | НАЙДЕНО / ОТСУТСТВУЕТ |
    Если статус ОТСУТСТВУЕТ — **Блокер (Data Gap, Приоритет 10)**. Anti-Hallucination Rule: не добавляй поле в таблицу «по памяти».

### 2. Мысленная песочница (Имитация и фаззинг)
* **Rule Enforcement (Dry Run):** Возьми Example Payload и «прогони» его через каждое бизнес-правило буквально.
* **PII Dry Run (обязателен при наличии правил безопасности паролей):** Если есть правило «пароль не должен содержать персональных данных» — выполни механическую проверку:
    1. Извлеки все токены из `email` (часть до `@` и после `@`) и `full_name`, длина токена > 3 символов.
    2. Для каждого токена: найди его вхождение в строку `password` (case-insensitive).
    3. Запиши результат: токен `"ivan"` in `"Ivan2024!"` → MATCH → **Дефект 9** «Нарушение бизнес-логики в примере данных».
    Покрытие: каждый токен должен быть проверен явно. Пропустить нельзя.
* **HTTP Status Exhaustion (Покрытие ветвей):** Найди все условные ветки в бизнес-правилах («если», «в случае», «при условии», «иначе»). Ты ОБЯЗАН составить таблицу:
    | Условие (ветка) | HTTP-статус описан? | Формат тела ошибки описан? |
    |---|---|---|
    | Email уже зарегистрирован | 409 / не указан | `{"error": "..."}` / не указан |
    Если статус или тело не описаны для любой ветки — **Дефект 8** (Неопределённое поведение).
* **Прогон счастливого пути:** Прогони пример данных через бизнес-правила шаг за шагом.
* **Мысленный фаззинг (Самое важное):** Атакуй требования. Придумай 3 граничных сценария, которые сломают логику:
    * *Null/Пусто:* Что если обязательное поле придет пустым? Описана ли ошибка?
    * *Граничные значения:* Максимальная длина, отрицательные числа, спецсимволы, emoji.
    * *Конфликты статуса:* Что если статус уже "Завершен", а мы шлем "Отменить"?

### 3. Архитектура и НФТ (Нефункциональные требования)
* **Конкурентность:** Что будет при двух одновременных запросах? (Требуется ли Idempotency Key?)
* **Безопасность (OWASP):**
    * Есть ли IDOR риски? (userId в URL без проверки прав).
    * ПДИ: Есть ли чувствительные данные в логах или ответе?
* **Распределённые системы:** Учтены ли таймауты внешних систем? Что делать, если база ответила, а брокер сообщений упал?

### 4. Проверка неоднозначности
* Ищи слова-паразиты: "быстро", "корректно", "как обычно", "позже". Это признаки техдолга.

## Когда использовать

- Перед написанием тест-кейсов или автотестов для новой фичи
- При ревью требований от PO/аналитика
- Когда спецификация содержит неоднозначные или потенциально конфликтующие требования

## Вывод результатов

**По умолчанию:** сохранить в файл `audit/spec-audit_{YYYY-MM-DD}.md` + вывести SKILL COMPLETE в чат.

При повторном запуске в тот же день — перезаписать.

## Контракт вывода

**Лимит:** Максимум 15 дефектов.

### 1. Резюме исполнителя
* **Вердикт:** `Готово для разработки` / `Одобрено с исправлениями` / `Заблокировано`.
* **Оценка качества спецификации:** (0-100%). Оценка проработки спецификации.
* **Топ 3 риска:** Кратко, главные проблемы.

### 2. Матрица рисков (Таблица дефектов)
Сортировка по приоритету (10 → 1).

**Шкала приоритетов:**
* **10 (Блокер):** Только два вида:
    1. **Data Gap** — данные, необходимые для выполнения задекларированного действия, полностью отсутствуют в схеме (напр. действие "отправить SMS", а поля `phone` нет вообще).
    2. **Прямое логическое противоречие** — два правила взаимно исключают друг друга и не могут быть реализованы одновременно без изменения спецификации.
    Всё остальное — не Блокер.
* **8-9 (Критический):** Высокий риск бага в проде: неописанные ветки бизнес-логики, неопределённое поведение при сбое внешних систем, критические NFR-пробелы.
* **6-7 (Основной):** Архитектурный риск (нет идемпотентности, плохой формат данных), нарушение стандартов.
* **4-5 (Минорный):** Неоднозначность формулировок, отсутствуют примеры ошибок, отсутствие вспомогательных атрибутов схемы (required, max для email).

| Приоритет | Категория | Проблема | Сценарий / Доказательство | Рекомендация |
|:---:|---|---|---|---|
| **10** | Пробел данных | Нет `phone` для SMS | Логика требует 2FA, но в `POST /register` нет телефона. | Добавить поле или брать из профиля. |
| **8** | Безопасность | Риск IDOR | `GET /orders/{id}` не требует проверки владельца в описании. | Явно указать правило: "Order.userId == CurrentUser.id". |
| **7** | Фаззинг | Отрицательная цена | Не описано поведение при `amount: -100`. | Добавить валидацию `min: 0.01`. |

### 3. Чек-лист готовности (Анализ пробелов)
Отметь, что есть (✅), чего нет (❌).

- [ ] **Схема:** JSON примера совпадает с таблицей.
- [ ] **Валидация:** Указаны min/max/regex для всех полей.
- [ ] **Ошибки:** Описаны коды ошибок (4xx, 5xx) и формат ответа при ошибке.
- [ ] **Cross-Check:** Каждое техническое действие (SMS, Email, Push, Запись в БД) обеспечено соответствующим полем во входных данных или контексте.
- [ ] **Безопасность:** Указаны Scope/Roles для эндпоинта.
- [ ] **Наблюдаемость:** Понятно, что писать в логи (и что НЕ писать, напр. PAN карты).

### 4. Блокирующие вопросы
Только вопросы, без ответов на которые нельзя начать писать код.

**Стиль:** Каждый вопрос — полное, вежливое и чёткое предложение на русском языке, адресованное аналитику или владельцу продукта. Не используй сокращения и жаргон.
*Пример хорошего вопроса:* «Просим уточнить, какой HTTP-статус и сообщение об ошибке должен возвращать эндпоинт, если пользователь с указанным email уже зарегистрирован в системе?»

1. [Полное вопросительное предложение.] (Влияние: ...)

## Самопроверка (Критически важно)
Перед выводом проверь себя на 10 конкретных ошибок в спецификации:
1. **Key-to-Key Mapping:** Выписаны ли все ключи JSON и все поля таблицы? Вычислена дельта? Расхождение = Дефект 9.
2. **Constraint Verification:** Проверены ли значения Example Payload против всех min/max/формат ограничений? Нарушение = Дефект 9.
3. **Несоответствие схемы:** Есть ли поля в примере, которых нет в описании (или типы не совпадают)?
4. **Пробел данных:** Есть ли логика (напр. 2FA, отправка Email), для которой не переданы входные данные?
5. **Нарушение правила (Dry Run):** Нарушает ли пример данных (payload) текстовые бизнес-правила?
6. **Неопределённое поведение:** Не описаны ли граничные случаи (null, отрицательные числа, спецсимволы)?
7. **NFR и безопасность:** Есть ли IDOR, PII в логах, отсутствие идемпотентности, race conditions?
8. **Граничный арифметический тест:** Для каждого поля с ограничением — записано ли уравнение `len = N; min=X, max=Y → PASS/FAIL`? Нарушение = Дефект 9.
9. **HTTP Status Exhaustion:** Для каждой ветки бизнес-логики — указан ли HTTP-статус и формат тела ответа? Незакрытая ветка = Дефект 8.
10. **Null Matrix:** Для каждого `required`-поля — описан ли ответ API при его отсутствии? Нет = Дефект 8.

**Если нашел такие — выводи их с приоритетом 8-10 (критический/блокер).**

## Протокол вербозности

**Молчание золота:** Минимум объяснительного текста. Выводи только инструменты и блоки завершения.

**Режимы коммуникации:**

| Режим | Когда | Формат |
|------|------|--------|
| **ГОТОВО** | Задача выполнена | `✅ SKILL COMPLETE: ...` блок |
| **ПРЕДУПРЕЖДЕНИЕ** | Проблема, но продолжаю | `⚠️ WARNING: [Проблема]` |
| **СТАТУС** | Смена фазы | `🤖 Orchestrator Status` (только при смене агента/фазы) |

**Без чата:**
- Нет "Прочитаю файл" — только инструмент Read
- Нет "Сейчас выполню" — только инструмент Bash
- Нет "Файл содержит..." — вывод идет в блок завершения
- Нет "Успешно создано..." — блок завершения показывает артефакты

**Исключение:** При WARNING или Gardener Suggestion — объяснение обязательно.

**Формат решения:** БЛОКИРОВАТЬ / ОТКЛОНИТЬ / ПРОЙТИ С ПРЕДУПРЕЖДЕНИЯМИ / ОДОБРИТЬ.

**Отчёт аудита:** Только в файл. Матрица рисков, таблицы и детали дефектов — ЗАПРЕЩЕНО выводить в чат.

### Завершение

Сохрани полный результат аудита в `audit/spec-audit_{date}.md` (перезапись при повторном запуске).

После сохранения — выведи блок `SKILL COMPLETE`:

**✅ SKILL COMPLETE: /spec-audit**
- Артефакты: `audit/spec-audit_{date}.md`
- Компиляция: N/A
- Upstream: нет
- Оценка качества спецификации: X%
- Дефекты: N (Приоритет 10: X, 8-9: Y, 6-7: Z, 4-5: W)
- Статус: Готово для разработки / Одобрено с исправлениями / Заблокировано