steelmorgan/spec-standard

Навык написания спецификаций (SDD)

Навык не выбирает режим исполнения (subagent/linear) — только структура, RFC 2119 и quality checklist.

---

2. Когда нужна спецификация

| Тип задачи | Нужна спека | Обоснование | |------------|-------------|-------------| | Новая функциональность | MUST | Фиксирует scope, требования, альтернативы и выбранное решение. | | Исправление бага с архитектурным влиянием | MUST | Требуется обосновать изменение структуры/поведения. | | Простое локальное исправление бага | MAY | Допустимо короткое описание без полной спеки, если изменение изолированно. | | Крупный рефакторинг | SHOULD | Нужна прозрачность по границам и последствиям изменений. |

---

3. Язык спецификации

Спецификация MUST быть написана на русском языке — заголовки секций, описания, требования, сценарии. Исключение — идентификаторы кода и метаданных (имена модулей, реквизитов, переменных) остаются как есть.

4. Обязательная структура спецификации

# SPEC-NNN: [Краткое название]
Статус: Черновик | Ревью | Утверждена | Реализована
Дата: YYYY-MM-DD

## Контекст и постановка проблемы

## Требования (RFC 2119)
### MUST
### SHOULD
### MAY
### MUST NOT

## Границы
### Входит в scope
### Не входит в scope

## Рассмотренные варианты

## Выбранное решение

## Технический дизайн
### Объекты метаданных (создаёт пользователь)
### Модули (пишет агент)
### Поток данных

## План тестирования (TDD)

### Тестовые пользователи (Test Users)

Если тесты (unit / BDD / integration) зависят от ролей, прав или контекста пользователя, спека ОБЯЗАНА содержать секцию «Test Users» (или эквивалент) со следующими правилами:

- Перечислять **только реально существующих** в целевой базе пользователей (логин + состав ролей + ссылка на источник: предзагруженный профиль, fixture, final-report связанной задачи и т.п.).
- **Запрещены placeholder-имена** («User1», «TestUser», «Manager_NoRole»), а также вымышленные ФИО без подтверждённого соответствия реальному аккаунту в базе («Сидоров», «Иванов» — если такого пользователя в базе нет).
- Для каждого test user указать минимум: логин, состав ролей, источник, тестовый сценарий-применение.
- Если подходящий пользователь **неизвестен** или **не существует** — Analyst задаёт `clarification_needed` пользователю в clarification round, а не выдумывает имя. Допустимо предложить пользователю кандидатов на создание (с указанием ролей), но имя должно быть подтверждено.
- Если test user должен быть **создан администратором** перед запуском (manual data prep) — это явно фиксируется отдельным пунктом в `manual-test-scenario.md` или эквивалентном артефакте, с описанием шагов создания.

**Почему:** placeholder-имена в спеке приводят к Vanessa-сценариям типа «Не смог подключить TestClient <Сидоров>» и проваливают весь Vanessa-уровень. Tester / Scenario-Coder не могут «угадать» реального пользователя и теряют часы на диагностику.

## Приёмочные сценарии (BDD)

## Открытые вопросы

## Журнал решений (ADR)

---

4a. Недублирование уровней теста (MUST)

Каждый тест в «Плане тестирования» ОБЯЗАН добавлять покрытие, которого ещё нет. Запрещено планировать тест (особенно BDD/Vanessa или integration), который проверяет ту же логику теми же входами и тем же наблюдаемым результатом, что уже закрытый unit-тест — то есть идёт 1-в-1.

Критерий «дубль 1-в-1» (НЕ планировать): второй тест проходит через тот же код-путь, с тем же Arrange и теми же ассертами, что первый, и не задействует ни одного нового слоя (UI/клиент, проводка в реальной БД, интеграционная граница, права/роли, многосессионность, конкуренция). BDD поверх полного unit-покрытия одного и того же серверного расчёта — типичный дубль.

Когда второй тест ОПРАВДАН (планировать): он РАСШИРЯЕТ покрытие — добавляет слой или измерение, недоступное первому:

• клиентское/UI-поведение формы (видимость, доступность, оповещения, ввод оператора);
• end-to-end проводка через реальную запись в БД (а unit мокировал движок);
• интеграционная граница (внешний API, обмен, HTTP-сервис);
• права/роли/контекст пользователя (если режим НЕ безусловно привилегированный — см. [[test-writing]] про антипаттерн теста привилегированного режима);
• конкуренция, идемпотентность перезапуска, многосессионность.

Почему: дубль 1-в-1 тратит ресурс и время (написание + прогон + сопровождение + диагностика ложных падений), не давая ни строки нового покрытия. «Зелёный» дубль создаёт иллюзию большей проверенности, которой нет. Стоимость BDD-уровня (Phase 3a/3c: исполняемые шаги, профиль прогона, итерации до GREEN, zero-residue teardown) особенно высока — оправдывать его обязан новый слой, а не повтор серверной логики.

Действие Analyst: для каждого BDD/integration-сценария в спеке явно указать, КАКОЙ слой он закрывает сверх unit-плана (одна строка «расширяет: <слой>»). Если расширения нет и сценарий идёт 1-в-1 с unit — НЕ включать его в план; зафиксировать в ADR решение «BDD не нужен: покрыто unit, дубля избегаем». Reviewer проверяет это как часть приёмки плана тестирования.

---

4b. Покрытие по затронутому runtime-слою (MUST)

План тестирования ОБЯЗАН выбирать уровень теста по тому runtime-слою, который меняется. Нельзя закрывать клиентское изменение только синтаксисом/юнитом, а серверное изменение — только кликом в UI.

| Что затронуто | Обязательное покрытие | |---------------|------------------------| | Серверная логика, общий модуль, модуль менеджера/объекта, серверный метод формы, запрос, запись регистров/документов | YaxUnit unit/integration. Если тест уже есть — актуализировать и перепрогнать; если теста нет — добавить. | | UI или клиентский контекст: форма, команда, кнопка, командный интерфейс, клиентский обработчик, ОткрытьФорму, оповещение, видимость/доступность, права на открытие UI | Сценарный тест через Vanessa/TestClient: открыть пользовательский entrypoint, выполнить действие и проверить наблюдаемый результат без ошибки. Для UI/UX-приёмки формы планировать PNG-скриншот через VA MCP (connect_test_client -> get_window_list_os -> get_window_screenshot_os) с проверкой, что снимок не пустой/чёрный. Web-клиент планировать только для browser-specific слоя (DOM/CSS/JS console/network/web-auth/viewport/browser extension), явно указав, какой функции принципиально нет в VA MCP. Для точечной команды минимальный сценарий кликает команду и подтверждает успешный запуск/завершение. | | Связанный пользовательский процесс, проходящий через несколько форм/объектов | End-to-end сценарий процесса. Сначала переиспользовать существующий сценарий и актуализировать его под изменение; новый сценарий писать только если существующего покрытия нет. | | Интеграционная граница, HTTP/API, фоновое или регламентное выполнение | Integration/YaxUnit или сценарный тест с проверяемым внешним/регистровым эффектом; для фоновых заданий — проверка идемпотентности и повторного запуска, если это относится к изменению. |

Каждый MUST в спеке должен иметь в «Плане тестирования» явную строку трассировки: требование → затронутый слой → тип теста → существующий тест актуализируется или создаётся новый.

Если обязательный UI/VA-тест технически невозможен в текущем окружении, спека НЕ должна молча снижать покрытие: применить fallback-правила va-visual-check и зафиксировать выполненные VA-шаги, причину fallback и остаточный риск. Если fallback не даёт достаточного сигнала для требования — зафиксировать blocker. Reviewer проверяет не только наличие тестов, но и соответствие уровня теста затронутому runtime-слою.

---

4c. Разграничение ADR (MUST)

В процессе существуют два ADR-механизма, их области НЕ пересекаются:

• Inline «Журнал решений (ADR)» этой спецификации — только бизнес-решения уровня требований: выбор альтернативы из «Рассмотренные варианты», scope-решения (что входит / не входит в границы), ответы пользователя в clarification round.
• Файловый task_dir/adr/*.md (MADR, ведётся в technical-design, см. technical-design-standard) — технические решения дизайна (Phase 2+): архитектура, модульная структура, контракты.

Каждый файловый ADR, вытекающий из решения спеки, ССЫЛАЕТСЯ на его номер в «Журнале решений». Дублировать одно решение в обоих местах ЗАПРЕЩЕНО.

---

5. Правила RFC 2119

| Ключевое слово | Значение | Правило использования | |----------------|----------|------------------------| | MUST | Обязательно | Без выполнения требование считается невыполненным. | | SHOULD | Настоятельно рекомендуется | Отклонение допустимо только с явным обоснованием. | | MAY | Опционально | Улучшение, не блокирующее приемку. | | MUST NOT | Запрещено | Явное ограничение, нарушение недопустимо. |

Требования должны быть:

• атомарными (одно требование — одна проверяемая мысль);
• проверяемыми (можно подтвердить тестом/сценарием);
• непротиворечивыми между разделами.

---

6. Декомпозиция задач

Для задач со спецификацией декомпозиция обязательна (отдельный JSON-файл Task Breakdown). В спецификации — ссылка на JSON и/или краткая выжимка.

Процесс контроля качества — вне этого навыка: task-breakdown (§3 Linear — self-check, §4 Subagent — cross-review).

---

7. Критерии качества спецификации

Чеклист для ревью:

• [ ] «Контекст» описывает кто имеет проблему и что не работает.
• [ ] Каждый MUST покрыт пунктом в «Плане тестирования».
• [ ] Для каждого MUST указан затронутый runtime-слой и выбран соответствующий тип теста: server → YaxUnit, UI/client → сценарный UI/BDD, процесс → end-to-end, integration/background → integration/job.
• [ ] «Границы» явно разделяют «Входит в scope» и «Не входит в scope».
• [ ] «Рассмотренные варианты» содержит минимум 2 альтернативы.
• [ ] «Выбранное решение» содержит обоснование и последствия.
• [ ] «Технический дизайн» разделяет задачи пользователя (метаданные) и агента (код).
• [ ] Между разделами нет противоречий.
• [ ] Требования сформулированы через RFC 2119 (MUST/SHOULD/MAY/MUST NOT).
• [ ] Есть ссылка/выжимка по отдельному Task Breakdown JSON.
• [ ] «Приёмочные сценарии» содержат Gherkin-сценарии бизнес-уровня (Дано/Когда/Тогда) для MUST-требований.
• [ ] Если изменение затрагивает UI/client context, есть сценарий, который открывает пользовательский entrypoint и выполняет изменённое действие.
• [ ] Если изменение затрагивает серверный метод/логику, есть YaxUnit-покрытие: актуализирован существующий тест или создан новый.
• [ ] Документ написан на русском языке (кроме идентификаторов кода).

---

8. Типичные ошибки

| Ошибка | Последствие | |--------|------------| | Смешение проблемы и решения в Context | Неясно, что нужно исправить | | Размытые требования без RFC 2119 | Невозможно однозначно принять работу | | Пустой Out of scope | Scope creep | | Отсутствие декомпозиции задач | Слабая трассируемость | | Противоречия Requirements ↔ Technical Design | Ошибки при реализации |

---

depends_on: []