# Use cases: как писать, чтобы их можно было прожить

> Шаблон UC as-code, образцовый пример, критерий проживаемости, специфика AI-продуктов и связь с evals

_Источник: https://sii.sergeivolchkov.ru/materials/use-cases/writing_



Use case — единственный артефакт, из которого потом выводится всё
остальное: экраны, API, evals, критерии приёмки. Если он написан плохо,
плохо будет во всех четырёх местах сразу.

Критерий приёмки в курсе один и жёсткий:

> **Проживаемость.** Человек не из команды берёт твой UC, садится за
> продукт (или за макет) и проходит сценарий до результата — не задав
> ни одного вопроса.

Не «понравилось ли ему описание». Именно прошёл или споткнулся.

## Что такое use case — и чем он не является [#что-такое-use-case--и-чем-он-не-является]

Use case — это **цель актёра**, достигаемая за один заход работы с
системой. Формулировка: глагол + объект на языке предметной области.
«Получить набор вопросов по теме» — да. «Нажать кнопку», «POST /questions»,
«Работа с базой» — нет.

Частые подмены:

* **UI вместо цели.** «Открыть модалку загрузки» — редизайн, и артефакт
  протух. Цель живёт дольше интерфейса.
* **Система вместо актёра.** «Система отправляет запрос в модель» — это
  реализация. UC пишется от того, кому нужен результат.
* **Шаг вместо кейса.** «Ввести логин» — не цель, а строчка сценария.
  Цель — «Войти в свой прогресс подготовки».

## Шаблон UC as-code [#шаблон-uc-as-code]

Один файл на один use case, `docs/use-cases/UC-01-<короткое-имя>.md`.
Ровно эта структура — чтобы автопроверка и агент читали одинаково:

```markdown title="docs/use-cases/UC-02-questions.md"
# UC-02. Получить набор вопросов по теме

**Актёр:** Студент, готовящийся к экзамену
**Цель:** получить вопросы, по которым можно проверить себя перед экзаменом
**Предусловия:** материалы курса загружены (UC-01), студент авторизован
**Триггер:** студент выбирает тему и нажимает «Тренироваться»

## Основной сценарий
1. Студент выбирает тему из списка тем, распознанных в материалах.
2. Студент указывает количество вопросов (5–20) и уровень сложности.
3. Система формирует набор вопросов по выбранной теме.
4. Система показывает набор с пометкой, из какого фрагмента материала
   взят каждый вопрос.
5. Студент подтверждает набор и переходит к тренировке (UC-03).

## Альтернативы и исключения
- **2а. Материалов по теме мало** (< 2 страниц): система предупреждает,
  что вопросов будет меньше запрошенного, и предлагает выбрать другую тему.
- **3а. Модель недоступна или ответила невалидно:** система показывает
  ранее сгенерированный набор по этой теме, помечая его как «из архива»;
  если архива нет — понятная ошибка и предложение повторить.
- **4а. Вопрос не подтверждается фрагментом материала:** такой вопрос в
  набор не попадает; если отсеяно больше половины — набор
  перегенерируется один раз, дальше — сообщение студенту.

## Результат
У студента есть набор вопросов по теме, каждый со ссылкой на фрагмент
исходного материала. Набор сохранён и доступен в истории.

## Как поймём, что работает
- 8 из 10 вопросов набора преподаватель признаёт корректными по теме.
- Каждый вопрос имеет ссылку на фрагмент источника (проверяется evals).
- Время от нажатия до готового набора — до 20 секунд.
```

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

## Специфика AI-продукта: модель ошибается — это часть сценария [#специфика-ai-продукта-модель-ошибается--это-часть-сценария]

В обычном UC исключения — это «сеть отвалилась» и «нет прав». В
AI-продукте добавляется третий класс: **модель ответила, но плохо**.
Ответ приходит уверенным тоном, статус 200, и только содержание —
мусор.

Поэтому в каждом UC, где участвует модель, обязаны быть прописаны:

* **Что считается негодным ответом** — не «плохой», а проверяемое:
  нет ссылки на источник, не тот формат, выход за рамки темы.
* **Что делает система, когда ответ негоден** — повтор, деградация на
  архив/простой вариант, честное сообщение. Молча показать мусор —
  не вариант.
* **Где в сценарии человек** — какие решения не отдаём модели
  (см. [HITL-точки](/materials/architecture/multi-agent)).

Это же место связывает UC с качеством: &#x2A;*evals пишутся прямо из
раздела «Как поймём, что работает»**. Строчка «каждый вопрос имеет
ссылку на фрагмент источника» превращается в проверку в наборе
из 30–50 пар «вход и эталонный ответ», который готовит роль Quality.
Нет измеримой строчки в UC — нечего проверять в evals.

## Проверка проживаемости: как проводить [#проверка-проживаемости-как-проводить]

Десять минут, один человек не из команды, никакой подготовки:

1. Даёшь ему UC — только текст, без своих комментариев.
2. Он вслух проходит сценарий по макету или прототипу.
3. **Каждый его вопрос — дефект твоего UC.** Не отвечаешь — записываешь.
4. Правишь UC по записанным вопросам, а не по своим ощущениям.

Прогон записывается в конец файла UC: кто проходил, что споткнулось, что
исправлено. Это заодно самый дешёвый способ выполнить обязательную часть
проверки гипотез — респондент уже перед тобой.

Красные флаги, которые видны сразу:

* Проверяющий спрашивает «а что здесь произойдёт?» — сценарий неполный.
* Он читает и не понимает, кто он в этом сценарии — актёр не определён.
* Он проходит за 30 секунд и говорит «ну и всё?» — это был шаг, а не UC.

## Сколько UC нужно [#сколько-uc-нужно]

На MVP — **3–7 use cases**. Меньше трёх — вы, скорее всего, описали не
продукт, а функцию. Больше семи на старте — обычно признак того, что
шаги записаны как отдельные кейсы; проверь, не разложился ли один UC на
пять.

Дальше — [диаграмма](/materials/use-cases/uml): те же кейсы одной
картинкой, по правилам UML.