version: "1.0.1" name: spec-standard description: "Use for написания спецификации задачи (SDD). Defines структуру документа, RFC 2119 уровни требований и quality checklist для Phase 1 full-cycle."

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

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

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

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 проверяет это как часть приёмки плана тестирования.

5. Правила RFC 2119

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

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

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

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

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

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

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

• [ ] «Контекст» описывает кто имеет проблему и что не работает.
• [ ] Каждый MUST покрыт пунктом в «Плане тестирования».
• [ ] «Границы» явно разделяют «Входит в scope» и «Не входит в scope».
• [ ] «Рассмотренные варианты» содержит минимум 2 альтернативы.
• [ ] «Выбранное решение» содержит обоснование и последствия.
• [ ] «Технический дизайн» разделяет задачи пользователя (метаданные) и агента (код).
• [ ] Между разделами нет противоречий.
• [ ] Требования сформулированы через RFC 2119 (MUST/SHOULD/MAY/MUST NOT).
• [ ] Есть ссылка/выжимка по отдельному Task Breakdown JSON.
• [ ] «Приёмочные сценарии» содержат Gherkin-сценарии бизнес-уровня (Дано/Когда/Тогда) для MUST-требований.
• [ ] Документ написан на русском языке (кроме идентификаторов кода).

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

depends_on: []