Use Case Pattern: как применять пошагово

← назад к разделу

Чаще всего вопрос звучит так: «Понятно, что такое Use Case Pattern — но с чего начать прямо сейчас?». Эта статья отвечает именно на него: два конкретных сценария, команды, ожидаемые результаты и частые ошибки.

Перед первым шагом убедитесь, что скиллы установлены: скиллы UCP — каталог и установка.

Когда задача маленькая: одна операция в существующем сервисе

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

Здесь нужен единственный скилл: открываете Claude Code в проекте и вызываете:

/ucp-pattern-design Команда «отменить заказ» с проверкой статуса DRAFT|PAID и проверкой прав по customerId

Через 30–60 секунд скилл вернёт:

• CancelOrderUseCase — объект команды с описанием входных данных и ожидаемого результата;
• CancelOrderHandler — компонент с транзакционной семантикой; бизнес-логика проверки статуса и прав — внутри;
• контроллер с авторизацией, реализующий OpenAPI-интерфейс;
• маппер между моделью запроса и командой.

Тестов этот скилл не пишет — они идут отдельным вызовом /ucp-test-design на ту же операцию.

Дальше:

1. Читаете ответ внимательно.
2. Применяете через инструменты редактирования Claude Code (или копируете вручную).
3. Запускаете /ucp-pattern-review на свежий diff — получаете замечания, если что-то не по правилам.
4. Запускаете тесты, правите если что-то красное.
5. Создаёте PR.

На одной такой операции в уже настроенном проекте от запроса до коммита уходит 5–10 минут — при условии, что сборка и тесты до этого были зелёные и правки после ревью мелкие.

Таблица скиллов для маленьких задач

Под разные типы операций — разные скиллы:

Для каждого design-скилла есть парный *-review — для проверки уже написанного кода.

Когда задача большая: новый сервис с нуля

Здесь на входе — бизнес-описание (хотя бы на страницу), на выходе — рабочий сервис. Процесс состоит из четырёх шагов.

Шаг 1. Написать спеку из бизнес-описания

/ucp-spec-design Сервис каталога маркетплейса. Продавец публикует и скрывает товары, Order Service берёт цену по productId. Уровень 2

Скилл читает описание и создаёт спецификацию в docs/spec/: корневой файл контекста и по файлу на каждый домен-юнит в aggregates/.

Если сервис уже существует, а описания нет — стартуйте с /ucp-spec-tier-0. Он читает код, миграции и конфигурацию и создаёт as-is спеку в том же формате. Это отправная точка для последующего улучшения.

Шаг 2. Составить план реализации

/superpowers:writing-plans

Скилл читает спеку и разбивает работу на шаги такого размера, чтобы каждый заканчивался тем, что можно проверить тестом. Ниже — только названия шагов такого плана, у каждого в самом файле плана расписаны файлы, тесты и порядок действий:

1. Scaffold проекта (модули, сборка, профили)
2. Миграция схемы БД: initial-schema
3. Кодогенерация из применённой схемы
4. ProductRepository — доступ к данным
5. CreateProductUseCase + Handler + контроллер
6. PublishProductUseCase + Handler
7. HideProductUseCase + Handler
8. GET /products/{id} — запрос
9. Конфигурация безопасности (prod / local / integration-test)
10. Интеграционные тесты на каждый UseCase
11. Архитектурные тесты на инварианты слоёв

Почему шаги идут именно в таком порядке

Порядок в плане не декоративный: каждый шаг опирается на результат предыдущего, и перестановка ломает конкретную вещь, а не «стройность».

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

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

И отдельно про соблазн «сначала все миграции, потом все операции». Это горизонтальная нарезка, и она возвращает всё то, от чего защищают вертикальные срезы: проверить нечего до самого конца. В плане выше первые четыре шага — вынужденный фундамент (его меньше, чем кажется), а дальше идут вертикальные срезы по одной операции.

Шаг 3. Выполнить план

/superpowers:executing-plans

Скилл идёт по плану шаг за шагом и на каждом вызывает нужный ucp-*-design:

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

Шаг 4. Финальное ревью

/ucp-pattern-review
/ucp-api-review
/ucp-ddd-tactical-review
/ucp-java-style-review
/ucp-auth-review
/ucp-test-review
/ucp-pg-schema-review
/ucp-pg-migration-review

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

Каждый скилл методологии проходится по diff. Замечания ссылаются на конкретные коды правил. После — внешний взгляд через /superpowers:requesting-code-review: ревьюер смотрит на PR со стороны, замечает то, что привычный взгляд пропускает.

От бизнес-описания до работающего сервиса — день-два, если стек установлен.

Когда результат не нравится

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

1. Не нравится частность — правите руками. Имя, порядок полей, лишняя переменная. Объяснять это скиллу дороже, чем поправить. Признак: правка занимает меньше минуты и не меняет структуру.

2. Не нравится решение — переформулируйте запрос, а не диалог. Скилл получил недостаточно входных данных, и добавлять их репликами в тот же разговор — худший способ: контекст уже забит первым вариантом, и второй будет похож на первый. Лучше вызвать скилл заново с уточнённым запросом. Что чаще всего приходится добавлять:

• Уровень зрелости. Без него скилл выбирает по признакам кода и может угадать не то.
• Где живёт правило. «Проверка статуса в агрегате, не в обработчике» — одна фраза, снимающая половину замечаний на Уровне 3.
• Границу задачи. «Только команда, контракт не трогаем» — иначе заодно появится в соседних файлах.
• Существующие имена. Если в проекте уже есть OrderStatus, скажите об этом: иначе появится второй.

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

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

Отдельно про случай, который выглядит как «не нравится», а является другим: скилл выдал код, противоречащий тому, что уже есть в проекте. Это почти всегда значит, что в проекте нет записанного правила на этот счёт — и правильное действие не поправить файл, а добавить правило, чтобы следующий вызов не изобретал заново. Куда именно его добавить, зависит от того, правило это или решение, — разбор в статье про настройку агента.

Чего делать не стоит: принимать код, который вам не нравится, потому что «скилл же по методологии». Скилл применяет правила, но постановку он получает от вас, и ответственность за результат не переезжает.

Когда правило нарушено осознанно

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

1. Подавить замечание в этом месте, с причиной. Локальное исключение: пометка рядом с кодом, которая гасит конкретное правило в конкретной точке и обязательно содержит причину.

@SuppressWarnings("ucp:R-PAT-3") // объединённый обработчик: обе команды пишут в одну таблицу одним запросом

//nolint:ucp // R-PAT-3: объединённый обработчик, обе команды пишут в одну таблицу одним запросом

// eslint-disable-next-line ucp/R-PAT-3 -- объединённый обработчик: обе команды пишут в одну таблицу одним запросом

# noqa: UCP-R-PAT-3  объединённый обработчик: обе команды пишут в одну таблицу одним запросом

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

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

3. Отступить от методологии в этом модуле сознательно. Самый редкий случай: кусок системы, где правила не применяются вовсе (интеграция с чужим кодом, временный модуль, эксперимент). Тогда это фиксируется явно — границей, за которой правила не проверяются, и записью, почему и до какого момента. Молчаливая зона, где «мы тут по-другому», расползается.

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

Как выбрать сценарий

Простое правило:

• Одна операция в существующем сервисе → один ucp-*-design скилл напрямую.
• Несколько операций в существующем сервисе → первый сценарий повторяется по одной операции за итерацию, без superpowers.
• Новый сервис с нуля → второй сценарий целиком.
• Переписать существующий сервис → сначала ucp-pattern-review на текущий код (понять, что не так), потом план миграции через superpowers:writing-plans, потом второй сценарий по модулям.
• Неясен сам подход → /superpowers:brainstorming, потом второй сценарий с уже определённым решением.

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

Что от этого меняется практически:

• План на пять однотипных операций не несёт информации. Он будет состоять из пяти одинаковых строк, и время на его составление и чтение потрачено зря.
• Каждая операция и так проверяется отдельно. Ценность пошагового исполнения в том, что оно не даёт перейти к следующему шагу на красной сборке; при работе по одной операции это делает обычный порядок «сделал — прогнал — закоммитил».
• Один PR на операцию всё равно остаётся правилом. А значит операции неизбежно идут по очереди, и оркестровка ничего не ускоряет.
• Длинный автономный проход хуже проверяется. Пять операций подряд без вашего чтения между ними — это большой diff, в котором расхождение со спекой замечают последним.

Обратное тоже верно: если между операциями есть зависимость (вторая читает то, что пишет первая; нужна общая миграция; меняется контракт, который используют обе), — это уже не «несколько операций», а маленький проект, и второй сценарий уместен.

Существующий код, который под правила не подходит

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

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

Порядок, который работает.

1. Снимок текущего состояния. Сначала спека «как есть» — скилл читает код, миграции и конфигурацию и описывает то, что система делает сегодня. Без этого непонятно, что именно нельзя сломать. Подробно — в статье про Уровень 0.
2. Ревью ради карты, а не ради правок. Прогнать ревью и не чинить, а отсортировать замечания: что ломает работу, что мешает развитию, что косметика. Обычно выясняется, что из двухсот замечаний по-настоящему важны пятнадцать.
3. Зафиксировать текущее поведение тестами. До любых правок. Характеризующие тесты — «на такой вход сегодня такой выход» — не проверяют правильность, они ловят изменение поведения. Без них переписывание слепое.
4. Заморозить нарушения на текущем уровне. Правила включаются с базовым списком существующих нарушений: новое нарушение падает в сборке, старые ждут. Это превращает неподъёмную работу в фоновую: код не ухудшается с первого дня, а улучшается по мере того, как его трогают.
5. Переводить по одной операции, когда её всё равно меняете. Не «рефакторинг-спринт», а правило: тронул операцию — привёл её к правилам целиком, с тестами. Так перевод оплачивается из бюджета задач, которые всё равно делаются.
6. Границы модулей — последними. Разделение на слои и модули стоит дороже всего и даёт эффект только когда внутри уже порядок.

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

Признак, что выбран правильный масштаб: каждая порция перевода — это PR, который можно прочитать за двадцать минут и откатить одной командой.

Сколько это стоит

Цифры в статье есть для времени и нет для всего остального, а решение «скиллом или руками» принимается по совокупности. Ориентиры ниже — порядок величины, не обещание: разброс по проектам кратный.

Что на самом деле определяет расход: не сложность задачи, а объём читаемого. Скилл, которому нужно понять существующий код, тратит на чтение больше, чем на генерацию. Отсюда два практических следствия: точная постановка («операция в этом модуле, спека вот здесь») дешевле общей на порядок, а большой проход по незнакомому коду — самая дорогая из операций.

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

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

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

Что стоит делать

Стартуйте с уровня ниже, чем кажется нужным. Если сомневаетесь между Уровнем 2 и 3 — берите 2. Сомнение — это когда инварианты не названы вслух; если вы уже можете перечислить правила, которые объект обязан держать сам, сомнения нет — это сразу Уровень 3. Уровень повышается легко, понижается тяжело. DDD и Hexagonal нужны там, где в домене есть сложные инварианты (заказ, платёж, бронирование). Справочники и административные страницы — Уровень 1 или 2.

Не пропускайте проверку после каждого шага. Когда AI генерирует что-то выглядящее правильным, соблазн пропустить проверку велик. Незелёный билд после шага — это сигнал, что шаг плохой, и нужно вернуться.

Один UseCase — один PR. Не складывайте пять операций в один коммит, даже если AI пишет их быстро. Размер PR прямо влияет на качество ревью.

Держите спеку и код в синхронизации. Изменили UseCase в коде — обновите спеку в том же PR. Расхождение — это ошибка, а не «доработаем потом».

Скиллы для ревью идут перед человеком, а не вместо. ucp-*-review ловит нарушения правил, человек смотрит на архитектуру и компромиссы.

Чего избегать

«Напишем спеку сразу на всю систему, а к коду вернёмся потом» — спека на десять сервисов вперёд устаревает раньше, чем до неё дойдут руки. Спека пишется на один контекст, и по ней сразу делается код; следующий контекст — следующим заходом.

«AI заодно отрефакторил три соседних модуля» — узкий промпт даёт узкий diff. «Заодно» превращается в большой PR, который никто не успевает проверить.

«У нас везде Уровень 3, потому что мы делаем DDD» — Уровень 3 дороже в поддержке. Используйте его только там, где в домене есть реальные инварианты.

«AI написал тесты, я не читал» — тесты-обёртки (assertNotNull, verify(any())) пропускают баги. Прочитайте пять тестов — это даст понимание качества остальных.

«Скиллы плюс команда агентов с ролями — ещё лучше» — нет. Несколько агентов в автономном диалоге ломают согласованность стиля и журнал аудита. Подробнее — в статье про установку скиллов.

Глубже: от карточки в спеке до кода: один проходрасширенное

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

Карточка в docs/spec/aggregates/order.md:

### Команда: ConfirmOrder
Переход: DRAFT → CONFIRMED
Вход: orderId, idempotencyKey
Предусловия: заказ существует; актор владелец заказа или роль operator
Логика: проверить BR-O01 (в заказе есть хотя бы одна позиция), BR-O03 (все позиции в наличии);
        зафиксировать сумму; перевести в CONFIRMED
Эмитит: OrderConfirmed { orderId, total, confirmedAt }
Ошибки: ORDER_NOT_FOUND, ORDER_EMPTY (BR-O01), ITEM_UNAVAILABLE (BR-O03), ORDER_ALREADY_CONFIRMED

Что из неё генерируется, по артефактам. UseCase ConfirmOrderCommand(orderId, idempotencyKey) с маркером команды, поля ровно из строки «Вход». Handler ConfirmOrderHandler, где порядок из строки «Логика» это порядок вызовов: загрузить агрегат, вызвать order.confirm(), сохранить, забрать события; сами правила BR-O01 и BR-O03 живут в методе агрегата, а не в обработчике. Ошибки из карточки становятся исключениями с теми же кодами, и ORDER_NOT_FOUND и ORDER_ALREADY_CONFIRMED это разные классы, потому что у них разный статус на границе. Контракт: операция POST /orders/{orderId}/confirm в OpenAPI с заголовком Idempotency-Key, схемой ответа и ответами 404, 409, 422 по списку ошибок; имя операции confirmOrder совпадает с именем команды. Событие OrderConfirmed с полями из строки «Эмитит» в схеме AsyncAPI и в классе события. Тесты: по одному на каждое правило и ошибку из карточки, с именами confirm_emptyOrder_rejectsWithOrderEmpty, confirm_draftOrder_emitsOrderConfirmed, и это тот список, по которому приёмка сверяет, что покрыто всё, что записано.

Правило соответствия простое и проверяемое: у каждой карточки команды ровно один UseCase с тем же именем, у каждой строки «Ошибки» исключение и тест, у каждого «Эмитит» событие в контракте. Скилл проектирования операции делает это за один вызов, а ревью проверяет соответствие по карточке, а не по вкусу; как это ловится автоматически, в следующем разделе.

Глубже: чем ловится расхождение спеки и кодарасширенное

«Расхождение это ошибка, а не доработаем потом» повторено трижды, и без механизма это лозунг. Механизм состоит из трёх слоёв, и первый из них автоматический.

Гейты в сборке. Скрипт сверяет спеку с кодом по формальным признакам и падает при расхождении: список команд из карточек против классов с маркером команды в коде (лишний UseCase без карточки или карточка без класса); коды ошибок из карточек против объявленных исключений; события из «Эмитит» против схем в контракте событий; операции OpenAPI против команд и запросов по имени; статусы из матрицы переходов против перечисления в коде. Сверка формальная, по именам, но она ловит девять из десяти расхождений, потому что расхождения обычно и есть «добавили операцию, спеку не тронули». У каждого правила в корпусе проекта записано, каким гейтом оно ловится, и это то, что ревью проверяет в первую очередь: гейт обещан, а не заведён, это находка важнее одного нарушения.

Ревью по карточке. Смысловые расхождения (логика в обработчике не совпадает с «Логикой», правило проверяется не там) машина не видит; их ловит ревью, у которого перед глазами карточка и код рядом, а не только код. Скиллы ревью проверяют правила корпуса, человек проверяет соответствие смыслу и компромиссы, о чём раздел выше.

Что происходит с pull request. Красный гейт блокирует слияние, как любой тест. Чинит автор, и чинит одно из двух: либо код под спеку, либо спеку под код с записью причины в описании; «поправим спеку следующим PR» не проходит, потому что следующего не бывает. Если изменение поведения было осознанным, оно начинается с документа изменения спеки, а не с кода, и PR ссылается на него.

Периодическая сверка. Раз в несколько недель агенту дают задачу прочитать спеку и код целиком и перечислить расхождения по смыслу; результат это задачи с приоритетом, а не заметки. Так спека остаётся источником правды, а не музеем.

Коротко

• Одна операция → один ucp-pattern-design напрямую, результат за несколько минут. Новый сервис → ucp-spec-design → план → executing-plans → финальные ревью.
• Стартуйте с уровня ниже, чем кажется нужным: Уровень 2 вместо 3, если нет сложных инвариантов. Один UseCase — один PR. Один шаг — зелёный билд перед следующим.
• Спека и код должны совпадать: изменился UseCase — обновите спеку в том же PR. Скиллы ревью дополняют человека, а не заменяют его. Одна карточка команды даёт ровно один UseCase, обработчик с порядком из «Логики», исключения и тесты по строке «Ошибки», операцию OpenAPI по имени и событие по «Эмитит»; соответствие проверяется по карточке.
• Расхождение ловят гейты в сборке (команды, ошибки, события, операции, статусы по именам), ревью по карточке для смысла и периодическая сверка агентом; красный гейт блокирует слияние, чинит автор в том же PR.
• Порядок шагов плана держится на зависимостях артефактов: миграцию надо применить до кодогенерации, репозиторий написать до обработчика, права навесить на существующие эндпоинты; переставляются только независимые шаги.
• Если результат не нравится, ходов четыре: поправить частность руками, вызвать скилл заново с уточнённой постановкой (а не спорить в том же диалоге), прогнать парный скилл ревью или написать руками, когда второй вызов не лучше первого.
• Осознанное нарушение правила подавляют точечно и обязательно с причиной, а не отключают правило целиком; третье подавление одного и того же правила означает, что менять надо правило.
• Несколько операций в существующем сервисе делают по одной, потому что фундамент уже стоит и между срезами нет зависимостей; если зависимость появилась, это уже маленький проект.
• Существующий код приводят к правилам не переписыванием: снимок «как есть», ревью ради карты, характеризующие тесты, заморозка текущих нарушений, перевод по одной операции при обычных задачах, границы модулей последними.
• Расход определяется объёмом читаемого, а не сложностью: точная постановка дешевле общей на порядок; руками дешевле, когда вы знаете правку, она мельче описания и результат трудно проверить.

Что почитать дальше

• Скиллы UCP — каталог и установка — если ещё не настроили инструменты.
• Use Case спецификация: универсальный шаблон — корень контекста и домен-юниты.
• Уровни зрелости: 1 — Слоёный → 2 — Use Case Pattern → 3 — DDD + Hexagonal.
• Кейс: Order Service (Уровень 3) — полный пример сервиса с применением UCP.