Use case — новый исходник программы

28 сентября 2026 · 17 минут чтения

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

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

Двадцать лет назад сценарии использования (use cases) считали тяжёлой бюрократией. Аналитик неделю писал документ, разработчики его не читали, через месяц он расходился с кодом, и все переходили на пользовательские истории (user stories) в три строки. Этот аргумент был честным, пока самым дорогим в разработке было написание кода.

Сейчас код пишет coding-агент — программа, которая сама читает репозиторий, меняет файлы и запускает проверки. Функцию, над которой команда сидела неделю, он делает за вечер. Дешёвым стал код, а дорогим — решение, которое агент не может принять за вас: что делать, если слот уже заняли, платёж не прошёл, пользователь закрыл вкладку посередине.

Моя позиция: в агентной разработке сценарий использования фактически становится исходником программы. Его редактируют, когда нужно изменить поведение. Его читают на ревью. Код, тесты и документация всё больше выводятся из него, примерно как бинарник выводится из исходного текста. Ниже — что такое use case, как его писать и где эта аналогия перестаёт работать.

Что такое сценарий использования

Сценарий использования описывает, как конкретный участник (пользователь программы) достигает своей цели с помощью системы: основной путь, допустимые варианты и то, что происходит при отказе. Идею ввёл в программную инженерию Ивар Якобсон, а текстовую форму, которой пользуются до сих пор, развил Алистер Кокберн.

Карл Вигерс и Джой Битти в книге «Разработка требований к программному обеспечению» противопоставляют два способа собирать требования. Можно спросить пользователя, какие функции ему нужны, и получить список кнопок. Можно спросить, какие задачи он решает с помощью системы, и получить сценарии. Второй способ Вигерс называет ориентированным на использование и считает его основным способом выяснить пользовательские требования: функциональные требования и тесты затем выводятся из сценариев.

Состав сценария в разных источниках почти одинаков. Анастасия Солдатова в статье на Хабре (часть 1, часть 2) и Академия MediaSoft называют одни и те же поля. Под каждым полем — как оно заполнено для записи на встречу на моём сайте:

• Идентификатор и название — цель пользователя, сформулированная глаголом.
  Пример: UC-BOOK-01. Записаться на онлайн-встречу. Не «Форма записи»: форма — это экран, а не цель.
• Основное действующее лицо — кто начинает сценарий ради своей цели.
  Пример: посетитель сайта.
• Триггер — событие, с которого всё начинается.
  Пример: посетитель открывает страницу записи.
• Предусловия — что уже должно быть верно до начала.
  Пример: в ближайшие 14 дней есть свободное время по расписанию.
• Постусловия, или гарантии — что система обеспечивает при успехе и что при любом исходе.
  Пример: при успехе встреча стоит в календаре, а посетитель получил приглашение; при любом исходе посетитель не видит «Вы записаны», если встреча не создана.
• Основной сценарий — нумерованные шаги успешного пути.
  Пример: 1) система показывает свободное время; 2) посетитель выбирает слот; 3) посетитель вводит имя и email; 4) система создаёт встречу и показывает подтверждение.
• Расширения — ветви от конкретных шагов: «А что, если…?»
  Пример: 4a. Слот заняли, пока посетитель заполнял форму: система сообщает об этом и предлагает выбрать другое время.

Главная часть здесь — расширения. Основной путь обычно очевиден всем участникам. Решения, о которых потом спорят, прячутся в ветвях: повтор запроса, отказ внешней системы, частичный успех, отмена.

Почему use cases стали снова нужны

Солдатова честно перечисляет минусы сценариев: громоздкость на крупных проектах и трудность поддерживать их в актуальном состоянии. Именно эти минусы и увели индустрию к коротким user stories. Карточка «Как бухгалтер, я хочу импортировать выписку» держалась на разговоре: детали выяснялись устно, между аналитиком, разработчиком и тестировщиком.

С агентом эта схема ломается в трёх местах.

Агент не переспрашивает так, как переспрашивал бы коллега. Если в постановке не сказано, что делать с дублем, он выберет правдоподобное поведение и реализует его аккуратно, с тестами. Ошибка обнаружится позже и будет выглядеть как нормальный код.

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

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

Индустрия пришла к тому же с другой стороны. Шон Гроув из OpenAI в докладе «The New Code» на AI Engineer World's Fair 2025 сравнил привычную работу с моделью с тем, как если бы мы выбрасывали исходник и бережно хранили в системе контроля версий только бинарник: промпт, в котором было намерение, теряется, а сгенерированный код остаётся. Его вывод — главным навыком становится написание спецификаций. GitHub в открытом наборе Spec Kit строит работу агента по цепочке «спецификация → технический план → задачи → реализация», и в файле спецификации лежат пользовательские сценарии с приёмочными сценариями для каждого.

В каком смысле это исходник

Исходник — это то, что вы меняете, когда хотите изменить программу. Бинарник вы не правите руками: вы правите исходный текст и пересобираете.

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

На моём сайте так устроена запись на онлайн-встречу. Её поведение описано в спецификации docs/booking.md: цели, границы первой версии, правила доступности, пользовательский сценарий, API, проверки. Спецификация появилась в том же коммите, что и первая реализация, и за следующий месяц менялась больше десяти раз — как правило, в тех же коммитах, что и код. Когда я решил запретить запись на текущий день, одно изменение затронуло правило в спецификации, конфигурацию, код расчёта слотов и три набора тестов.

Несколько решений из этой спецификации агент не вывел бы сам:

• выбранный слот остаётся предварительным и не считается занятым, пока не создано событие в календаре;
• успех показывается только после создания события, а утверждать, что письмо доставлено, можно лишь когда Google это подтвердил;
• ошибка определения города или недоступность Telegram не отменяют запись;
• повтор того же запроса после сетевого сбоя не создаёт вторую встречу.

Каждое из этих предложений — расширение или гарантия сценария. Каждое можно реализовать иначе, и код при этом останется «правильным» на вид.

Из этого следует несколько рабочих правил:

• сценарии лежат в репозитории рядом с кодом и версионируются вместе с ним;
• изменение поведения начинается с правки сценария;
• на ревью запроса на слияние (pull request) сначала читается изменение сценария, потом код;
• у сценариев и расширений есть устойчивые идентификаторы, на которые ссылаются тесты;
• если код изменил поведение, а сценарий нет, это дефект изменения, даже когда тесты зелёные.

Где аналогия ломается

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

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

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

И сценарий подходит не всем задачам. Для системы, где главное — внутренние правила расчёта, а не взаимодействие с участником, полезнее таблица правил или модель предметной области. Сценарий тогда ссылается на эти правила, а не пересказывает их.

Как писать сценарий, который агент исполнит правильно

Правила ниже собраны из Вигерса, Кокберна, статей Солдатовой и MediaSoft. Для агента они важнее, чем были для человека: человек достраивал пропуски здравым смыслом и вопросами, агент достраивает их догадкой.

Называйте цель, а не экран. «Импортировать банковскую выписку» — цель. «Нажать “Загрузить”» — действие в интерфейсе. Кокберн предлагает проверку: если шаг состоит из кликов, спросите «зачем?», пока не появится результат, ради которого пользователь пришёл. Если сценарий тянется на недели и включает десяток самостоятельных целей — спросите «как?» и спуститесь уровнем ниже.

В каждом шаге есть действующее лицо. MediaSoft среди первых ошибок называет пассивный залог и сценарии без системы. «Данные проверяются» не говорит, кто проверяет и что будет при неудаче. «Система проверяет, что слот свободен» — говорит.

Система — чёрный ящик. Шаг описывает, что система делает для участника, а не таблицы и очереди внутри. Хорошая проверка: сохранится ли смысл шага, если веб-интерфейс заменить на API? Если нет, в сценарий просочилась реализация. Вигерс и Битти среди ловушек тоже называют дизайн интерфейса и определения данных внутри сценария: их место в отдельных документах, на которые сценарий ссылается.

Не дробите. Сценарий из сорока шагов по одному полю формы агент выполнит буквально и потеряет цель. MediaSoft советует объединять связанные действия в один осмысленный шаг.

Расширения привязаны к шагам. 4a. Слот заняли, пока посетитель заполнял форму сразу показывает, где ветвится поведение. Для каждого шага спросите: что здесь может пойти иначе, может ли система это заметить и что она обязана сделать? Ветвь заканчивается возвратом в основной путь, успехом или явным отказом.

Пишите гарантии. Постусловие успеха говорит, что будет, если всё прошло хорошо. Минимальная гарантия говорит, что система обеспечит при любом исходе: «некорректный импорт не меняет существующие операции». Для агента это самые полезные строки: из них прямо следуют тесты.

Бизнес-правила — отдельно. Вигерс советует хранить правила отдельно и ссылаться на них из сценариев. «Запись возможна не раньше следующего дня» — правило, его используют несколько сценариев: запись, перенос, показ календаря. Как из сценария выводятся требования, тесты и каталог правил, я разобрал отдельно в статье «Что выводится из сценария использования: требования, тесты и бизнес-правила».

Точность растёт с риском. Для простого справочника хватит двух абзацев. Деньги, права доступа, удаление данных и интеграции требуют всех расширений и гарантий. Вигерс и Битти предупреждают и об обратной крайности — слишком большом числе сценариев и злоупотреблении связями «включает» и «расширяет» между ними.

Сценарий записи на встречу из примера выше в такой форме выглядит так:

## UC-BOOK-01. Записаться на онлайн-встречу

Уровень: цель пользователя
Основной участник: посетитель сайта
Вспомогательные участники: Google Calendar, Яндекс Телемост, Telegram-бот
Триггер: посетитель открывает страницу записи

Гарантия успеха:
- в календаре создано событие с уникальной ссылкой на комнату Телемоста;
- посетитель видит подтверждение со временем в своём часовом поясе
  и ссылкой для отмены или переноса.

Минимальная гарантия:
- посетитель не видит сообщения об успехе, если событие не создано;
- повтор того же запроса не создаёт вторую встречу.

Основной сценарий:
1. Система показывает свободные слоты в часовом поясе посетителя.
2. Посетитель выбирает длительность и время.
3. Посетитель указывает имя, email, тему и даёт согласие на обработку данных.
4. Система повторно проверяет, что слот свободен, и создаёт событие.
5. Система показывает подтверждение и уведомляет владельца календаря.

Расширения:
2a. Посетитель меняет часовой пояс:
    1. Система меняет только отображение; доступность не пересчитывается.
4a. Слот заняли, пока посетитель заполнял форму:
    1. Система сообщает, что время занято, и возвращает к выбору слота.
4b. Календарь или сервис встреч недоступен:
    1. Система сообщает об ошибке; событие не создаётся.
5a. Telegram недоступен:
    1. Запись считается успешной; уведомление доставляется повторно позже.

Правила: BR-BOOK-01 (рабочие часы по Москве), BR-BOOK-02 (не день в день).

Это сокращённая переработка настоящей спецификации: в ней больше полей и правил. Но даже в таком виде в тексте видны решения, которые без него агент принял бы сам.

Как с этим работать в репозитории

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

Шаг 1. Составить список сценариев

Список отвечает на вопрос, что вообще делает система: кто ей пользуется и ради каких целей. Каждая строка — одна цель одного участника, пока без деталей.

В новом проекте (greenfield) список пишут руками: перечисляют участников и спрашивают, чего каждый хочет добиться. Это та же работа, что и сбор требований от задач пользователя.

В существующем проекте (brownfield) код уже есть, а описания поведения нет. Здесь список удобно поручить агенту: он прочитает маршруты, API, фоновые задачи и тесты быстрее человека. Например, так:

Список, составленный агентом, — черновик. Агент видит, что код делает, но не знает, что код должен делать. Его проверяет человек, который знает продукт: вычёркивает случайное поведение, дописывает цели, которых в коде пока нет.

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

Шаг 2. Завести паспорт на каждый сценарий

Паспорт — отдельный файл на один сценарий. В нём те же поля, что в начале статьи: участник, триггер, предусловия, гарантии, основной сценарий и расширения. Плюс ссылки на бизнес-правила, которые сценарий использует, и на тесты, которые его проверяют. Готовый шаблон паспорта можно взять из моего шаблона Memory Bank: UC-XXX.md.

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

У паспорта есть номер версии и журнал изменений. Git хранит историю файла, но версия даёт имя конкретному состоянию поведения: на неё можно сослаться из задачи, pull request и теста. В шаблоне UC-XXX.md этого поля пока нет — его стоит добавить во frontmatter самостоятельно. Так выглядел бы паспорт записи на встречу, если бы он вёлся с первого дня:

---
id: UC-BOOK-01
title: Записаться на онлайн-встречу
version: 3
---

…поля сценария…

## Журнал изменений

- v3, 2026-08-25 — каждая встреча получает свою комнату Телемоста
  вместо одной общей ссылки (гарантия G1).
- v2, 2026-08-25 — запись на текущий день запрещена; сценарий
  ссылается на новое правило BR-04.
- v1, 2026-08-25 — первая версия.

После двух шагов в репозитории появляется директория:

docs/use-cases/README.md                           # список сценариевUC-BOOK-01-book-meeting.md          # паспорт: записаться на встречуUC-BOOK-02-cancel-or-reschedule.md  # паспорт: отменить или перенестиUC-BOOK-03-notify-owner.md          # паспорт: узнать о новой записиUC-BOOK-04-change-availability.md   # паспорт: изменить часы записиrules.md                            # бизнес-правила для паспортов

Сейчас запись на встречу у меня описана одной спецификацией docs/booking.md, где сценарии, правила и API лежат вместе. При таком подходе она распалась бы на четыре паспорта и файл правил, а API осталось бы в отдельном техническом документе.

Дальше — при каждом изменении поведения

1. Найти в списке сценарий, который меняется, или добавить новый.
2. Поправить паспорт: шаги, расширения, гарантии. Пройтись по шагам вопросом «а что, если?» и разделить ветви: что делаем сейчас, что потом, что не поддерживаем, где ещё нет ответа. Открытый вопрос в тексте лучше догадки в коде.
3. Поднять версию паспорта и записать в журнал, что изменилось и почему. Обновить версию в списке сценариев. Версию поднимает любое изменение поведения; правка формулировки, после которой система ведёт себя так же, версию не меняет. Новое правило, которое сценарий начинает соблюдать, — изменение паспорта. А новое значение уже существующего правила — например, горизонт записи 14 дней вместо 30 — меняет только rules.md: паспорт ссылается на правило, а не копирует его.
4. Попросить агента найти в паспорте противоречия и ветви без решения — до реализации.
5. Для каждой гарантии и существенного расширения завести тест со ссылкой на идентификатор.
6. Передать агенту паспорт, текущий срез работы и команды проверки. В задаче и pull request указать сценарий с версией: «UC-BOOK-01 v3». Тогда видно, какую версию реализует изменение, а агент может найти расхождение: паспорт уже v3, а код и тесты — ещё v2. Порядок нарезки на задачи и конкретные примеры в формате Given / When / Then подробно разобраны в статье «Use cases, user stories и BDD для AI-агента» (черновик).
7. Записать в правилах репозитория, что изменение поведения без новой версии паспорта не принимается.

Сценарий не отменяет разговор с заказчиком. Он фиксирует его итог так, чтобы через месяц его смог прочитать тот, кого в разговоре не было, — человек или агент.

Термины

• Сценарий использования (use case) — описание того, как участник достигает цели с помощью системы: основной путь, варианты и отказы.
• Основное действующее лицо (актор) — роль, которая начинает взаимодействие ради своей цели. Может быть человеком или внешней системой.
• Расширение — ветвь сценария от конкретного шага: другой вариант, ошибка или отмена.
• Предусловие — что должно быть истинно до начала сценария.
• Гарантия, или постусловие — что система обеспечивает после сценария: при успехе или при любом исходе.
• Паспорт сценария — отдельный файл с полным описанием одного сценария использования: поля, шаги, расширения, ссылки на правила и тесты.
• Новый проект (greenfield) — проект, который начинают с нуля, без существующего кода.
• Существующий проект (brownfield) — проект, в котором уже есть работающий код и накопленное поведение.
• Бизнес-правило — ограничение предметной области, которое используют несколько сценариев.
• Пользовательская история (user story) — короткая формулировка потребности как единицы планирования работы.
• Запрос на слияние (pull request) — предложенное изменение кода, которое проходит ревью перед попаданием в основную ветку.
• Coding-агент — AI-инструмент, который сам читает репозиторий, меняет файлы и запускает проверки.
• Разработка от спецификации (spec-driven development) — способ работы с агентом, в котором спецификация пишется до кода и остаётся главным редактируемым документом.

Источники

1. Карл Вигерс, Джой Битти — «Разработка требований к программному обеспечению. Практические приёмы сбора требований и управления ими при разработке программных продуктов», 3-е изд., дополненное. БХВ, 2025 — основной учебник по требованиям: подход, ориентированный на использование, элементы сценария, вывод функциональных требований и тестов из сценариев, ловушки при их написании.
2. Анастасия Солдатова — «Use Case: как описывать эффективные сценарии использования. Part 1», Хабр, 2025 — состав сценария, его плюсы и ограничения, включая трудность поддерживать сценарии в актуальном состоянии.
3. Анастасия Солдатова — «Use Case: как описывать эффективные сценарии использования. Part 2», Хабр, 2025 — диаграммы прецедентов, связи между сценариями и генерация сценариев и диаграмм с помощью LLM.
4. Академия MediaSoft — «Use case: что это, из чего состоит и как избежать ошибок при написании», 2024 — шаблон сценария и разбор типичных ошибок: пассивный залог, детали интерфейса, чрезмерное дробление шагов, путаница расширений.
5. Sean Grove — «The New Code», AI Engineer World's Fair, 2025 — аргумент, что спецификация становится основной единицей программирования с моделями.
6. GitHub Spec Kit — Spec-Driven Development — открытый набор инструментов, где агент работает по цепочке «спецификация → план → задачи → реализация».
7. Alistair Cockburn — Writing Effective Use Cases, Addison-Wesley, 2001 — классическая книга о текстовых сценариях, уровнях целей и расширениях.
8. Шаблон паспорта сценария UC-XXX.md из репозитория dapi/memory-bank — поля паспорта, идентификаторы правил, альтернатив и исключений для трассировки.
9. «Use cases, user stories и BDD для AI-агента» (черновик) — соседний материал: как сценарий, пользовательская история и BDD-примеры складываются в одну постановку задачи агенту.

Синтез не претендует на полноту: он опирается на перечисленные источники и на опыт работы с агентами в собственных репозиториях.

Автор: Данил Письменный · Дата: 28 сентября 2026