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)

---

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

---

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

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

---

depends_on: []