🚀 Документация быстрой спецификации

Быстрая спецификация является документом, с помощью которой можно предоставить командам разработки структурированный, но легковесный процесс для спецификации небольших функций, который обеспечивает ясность, тестируемость и прослеживаемость, минимизируя бюрократию и избыточную документацию.

Цель и задачи "Быстрой спецификации":

• Преобразовать идею небольшой функции в четкие, тестируемые критерии приемки.
• Создать прямой и понятный план реализации в виде списка задач.
• Установить общее понимание между разработчиком, тестировщиком и менеджером.
• Обеспечить прослеживаемость от пользовательской ценности до конкретных задач кодирования.
• Снизить когнитивную нагрузку на разработчика, позволив сосредоточиться на одной задаче за раз.

Пошаговый процесс

Шаг 1: Формулировка пользовательской истории и критериев приемки (EARS)

Цель: Определить что нужно сделать и почему, установив измеримые критерии успеха.

Напишите пользовательскую историю: Используйте формат "Как [роль], я хочу [функция], чтобы [преимущество]". Фокус на бизнес-ценности.

Создайте критерии приемки в формате EARS: Преобразуйте историю в 3-7 конкретных, недвусмысленных и тестируемых утверждений.

• Используйте шаблоны: WHEN... THEN..., IF... THEN..., WHEN... AND... THEN..., WHEN... (ошибка) THEN....
• Обязательно включите как минимум один сценарий обработки ошибок или граничного случая.
• Избегайте технических деталей реализации (например, "использовать Redis").
• Избегайте расплывчатых терминов ("быстро", "удобно").
• Каждое требование должно начинаться с WHEN или IF и содержать THEN система SHALL.

Результат: Четко определенная область работ с измеримыми критериями завершения.

Шаг 2: Преобразование требований в задачи реализации

Цель: Разбить критерии приемки на конкретные, выполнимые шаги для разработчика.

Проанализируйте каждый критерий приемки: Определите, какие именно действия по созданию или изменению кода необходимы для его выполнения.

Сформулируйте задачи: Каждая задача должна описывать конкретную активность (например, "Создать endpoint /api/v1/user/status", "Добавить поле last_login в модель User", "Написать unit-тест для валидации email").

Установите последовательность: Задачи должны быть упорядочены логически. Обычно сначала создаются основы (модели данных, API-контракты), затем бизнес-логика, затем обработка ошибок и тесты.

Обеспечьте прослеживаемость: Каждая задача должна явно ссылаться на номер или текст критерия приемки, который она реализует (например, "Реализует критерий 3: КОГДА пользователь отправляет форму...").

Результат: Структурированный список задач, готовый к исполнению.

Шаг 3: Валидация и уточнение

Цель: Убедиться, что спецификация полна, ясна и выполнима.

Проверьте себя по чек-листу:

• Пользовательская история четко определяет роль, действие и ценность
• Все критерии приемки сформулированы в формате EARS
• Включены критерии для обработки ошибок/граничных случаев (минимум 1)
• Каждая задача реализации имеет четкую, конкретную цель
• Каждая задача ссылается на соответствующий критерий приемки
• Задачи упорядочены в логической последовательности
• Спецификация позволяет разработчику сразу приступить к реализации

Результат: Утвержденная и готовая к реализации спецификация.

Шаблон документа

# Быстрая спецификация: "[Краткое и понятное название функции/изменения]"

**Пользовательская история:**

Как [роль пользователя], я хочу [описание функции/изменения], чтобы [бизнес-ценность/преимущество].

---

## Критерии приемки

### **[Название/Описание критерия 1]**

КОГДА [событие] ТО система ДОЛЖНА [наблюдаемый результат].

### **[Название/Описание критерия 2]**

ЕСЛИ [условие] ТО система ДОЛЖНА [наблюдаемый результат].

### **[Название/Описание критерия 3 - ОБЯЗАТЕЛЬНО обработка ошибки/граничный случай]**

КОГДА [нештатное событие] ТО система ДОЛЖНА [действие по обработке].

### *[При необходимости добавьте еще 1-4 критерия]*

---

## План реализации

*Задачи упорядочены по логике реализации. Каждая задача ссылается на критерий приемки, который она реализует.*

### [Конкретное действие, например, "Создать API endpoint /api/v1/feature"]

  * *Реализует критерии:* [Ссылка на критерии]
  * *Детали:* [Какие файлы/компоненты создать/изменить? Краткое описание логики.]
  * *Критерий завершения:* [Например, "Код написан, контракт API задокументирован в Swagger."]

### [Конкретное действие, например, "Добавить валидацию входных данных"]
  * *Реализует критерии:* [Ссылка на критерии]
  * *Детали:* [Какие файлы/компоненты создать/изменить? Краткое описание логики.]
  * *Критерий завершения:* [Например, "Валидация реализована, unit-тесты на валидацию проходят."]

### [Конкретное действие, например, "Написать интеграционный тест"]
  * *Реализует критерии:* [Ссылка на критерии]
  * *Детали:* [Какие файлы/компоненты создать/изменить? Краткое описание логики.]
  * *Критерий завершения:* [Например, "Тест написан и проходит успешно."]

### [Конкретное действие, например, "Обновить документацию пользователя"]
  * *Реализует критерии:* [Ссылка на критерии]
  * *Детали:* [Какие файлы/компоненты создать/изменить? Краткое описание логики.]
  * *Критерий завершения:* [Например, "Раздел 'Руководство пользователя' обновлен и залит на сайт."]

---

## 3. Чек-лист качества (Заполняется автором перед началом реализации)

| Критерий                                                             | Выполнено | Комментарий |
| -------------------------------------------------------------------- | --------- | ----------- |
| Пользовательская история четко определяет роль, действие и ценность  | ☐        |             |
| Все критерии приемки сформулированы в формате EARS                   | ☐        |             |
| Включены критерии для обработки ошибок/граничных случаев (минимум 1) | ☐        |             |
| Каждая задача реализации имеет четкую, конкретную цель               | ☐        |             |
| Каждая задача ссылается на соответствующий критерий приемки          | ☐        |             |
| Задачи упорядочены в логической последовательности                   | ☐        |             |
| Спецификация позволяет разработчику сразу приступить к реализации    | ☐        |             |