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).

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 (критический/блокер).

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

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

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

Без чата:

• Нет "Прочитаю файл" — только инструмент 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)
• Статус: Готово для разработки / Одобрено с исправлениями / Заблокировано