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

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

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

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

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

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

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

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

Три подмены, которые убивают UC:

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

Шаблон UC as-code

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

# UC-02 · Получить набор вопросов по теме

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сколько UC нужно

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

Дальше — диаграмма: те же кейсы одной картинкой, по правилам UML.