Use Case Pattern

Use Case Pattern: методология, где описывают не изменение, а систему, и спека живёт столько же, сколько сервис. Паттерн, уровни зрелости, биндинги и скиллы.

Use Case Pattern — методология, не библиотека. По классу это spec-driven разработка: сначала спецификация, потом код по ней. Отличие от OpenSpec, Spec Kit и Kiro — в единице описания: они описывают изменение и архивируют его после мержа, здесь описывается система — Bounded Context со своими агрегатами, инвариантами и событиями, и спека живёт столько же, сколько сервис. Разбор различий — в сравнении со spec-driven инструментами.

Четыре составляющих:

Сам паттерн. UseCase + Handler + Dispatcher — единый способ описывать бизнес-операции в коде.
Спецификация. Универсальный шаблон того, что должно быть описано про сервис; хранится в git как код.
Три уровня зрелости. Как паттерн и спецификация наращиваются по мере роста сервиса — от слоёного MVP до DDD с десятками интеграций.
Сквозной кейс. Бизнес-описание маркетплейса, на котором проверяется и сам паттерн, и спецификация, и уровни зрелости. Без него методология остаётся теорией.

Скиллы для AI-агентов работают со всеми четырьмя — это инструмент, а не отдельная составляющая.

Контракт и биндинги

Все четыре составляющих язык-нейтральны — это контракт методологии. Реализацию под конкретный стек дают языковые биндинги: те же правила, те же коды, своя идиоматика. Вторая ось — специализация: backend (основной трек), frontend (React + TypeScript, каркас), e2e (зарезервирован).

Биндинг	Стек	Статус
Java	Spring Boot, jOOQ, эталонные библиотеки	статьи в Стандартах, библиотеки, скиллы `ucp-*`
Python	FastAPI, SQLAlchemy, Pydantic	style-guide и скиллы `ucp-py-*` в репо скиллов; статей на сайте пока нет
Node	NestJS, TypeORM, class-validator	style-guide и скиллы `ucp-node-*` в репо скиллов; статей на сайте пока нет
Go	net/http + chi, sqlc	в работе

Правило одно и то же на любом стеке: R-UC-3 означает «один UseCase — одна бизнес-операция» и в Java, и в Python, и в Node — меняется только то, как это выглядит в коде. Поэтому команда на любом из стеков читает одни контракты, а AI-скиллы проверяют одни коды правил.

1. Сам паттерн

Каждая бизнес-операция — отдельный UseCase и отдельный UseCaseHandler. Между входом (HTTP, очередь, cron) и выходом (БД, внешние API) проходит UseCaseDispatcher, который сводит их по типу.

Между запросом и логикой стоит тип операции, а не контроллер: откуда пришёл вызов — из HTTP, из очереди или по расписанию — обработчику всё равно.

Главное:

Один UseCase — одна бизнес-операция. CreateOrder, ConfirmPayment, GetOrderById. Никаких «универсальных сервисов».
Контроллеры, обработчики очередей, cron — разные входные адаптеры к одному и тому же UseCase.
Слои не смешивают модели данных. Между ними — явный маппинг.

Паттерн язык-нейтрален. Для Java есть готовая библиотека usecase-pattern; в Python- и Node-биндингах паттерн собирается руками из лёгких интерфейсов — как именно, описывают биндинг-гайды в репо скиллов.

2. Спецификация как код

В основе методологии лежит простое правило: спецификация — это код. Не Word-документ, не Confluence-страница, не PDF от аналитика. Markdown-файл в том же репозитории, что и код сервиса.

Что из этого следует:

Спека лежит в git рядом с кодом и проходит через PR-обзор как любой коммит.
История изменений видна в git log — кто, когда, почему изменил правило.
Формат структурирован: одиннадцать разделов в корневом файле контекста и семь в файле каждого агрегата — с заголовками, таблицами, списками. Это читают и люди, и инструменты — линтеры, генераторы кода, AI-агенты.
Контракты выводятся, а не дублируются: из раздела «Commands» получается OpenAPI, из «Domain Events» — AsyncAPI, из «Domain Model» — заготовки агрегатов.
Спека и код обязаны совпадать. Расхождение — баг, не «доработаем потом».

Глубина спеки = уровень зрелости сервиса (одна ось 0–3), который спека объявляет полем level во frontmatter:

Уровень 0 — As-is. Спека восстановлена из существующего кода без бизнес-брифа (ucp-spec-tier-0): снимок «как сейчас», not-declared для пробелов. Точка отсчёта для миграции.
Уровень 1 — Слоёный. Минимальная спека от бизнес-брифа: глоссарий, ER-схема, операции, правила. Без агрегатов и событий.
Уровень 2 — Use Case Pattern. Добавляются UseCase-ы и карточки команд/запросов; CQRS + Read Model — опция.
Уровень 3 — DDD + Hexagonal. Полная глубина: агрегаты, value objects, доменные события, саги, контракты на рёбрах.

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

Спека → AI-агенты

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

генерирует API-контракты из раздела «Commands» (ucp-api-design);
генерирует агрегаты и события из «Domain Model» (ucp-ddd-tactical-design);
генерирует UseCase + Handler из «Use Cases» (ucp-pattern-design);
проверяет код по правилам спеки (ucp-pattern-review, ucp-ddd-tactical-review).

Скиллы есть под каждый биндинг: ucp-* — Java, ucp-py-* — Python, ucp-node-* — Node. Установщик ставит срез под язык и специализацию команды (UCP_LANG × UCP_TRACK).

К статье с привязанным скиллом на сайте показывается жёлтый барсук. К статьям с эталонной библиотекой — зелёный. С эталонным примером проекта — синий. Все скиллы — в github.com/remodov/usecase-pattern-skills.

3. Уровни зрелости

Методология — лестница. Каждый следующий уровень добавляет ответ на проблему, с которой предыдущий уже не справляется. Подняться можно когда есть причина, а не «потому что модно». Уровень — одна ось, спека объявляет его полем level.

Уровень 0 — As-is

Спека восстановлена из существующего кода без бизнес-брифа (ucp-spec-tier-0) — снимок «как сейчас». Не место для жизни, а точка отсчёта. Когда брать: brownfield-сервис в проде без спеки, онбординг, перед миграцией. Когда уходить: сразу после онбординга — заменяешь not-declared бизнес-фактами и проектируешь целевой уровень.

Уровень 1 — Слоёный

Классическая слоёная архитектура (Controller → Service → Repository), без usecase-pattern. Базовая ступень. Когда брать: CRUD, тонкая бизнес-логика, MVP, внутренний инструмент. Когда уходить: когда операции в сервис-классах не различить и нужны метрики/аудит на операцию.

Уровень 2 — Use Case Pattern

Каждая бизнес-операция — отдельный UseCase и обработчик; один общий маршрут, метрики на операцию. CQRS (команды/запросы + Read Model) — опция этого уровня, когда чтение и запись расходятся по нагрузке. Когда брать: заметное число операций, нужна структура. Когда уходить: когда бизнес-правил так много, что они «расползаются» по обработчикам.

Уровень 3 — DDD + Hexagonal

Явная доменная модель (агрегаты, value objects, доменные события) + изоляция инфраструктуры через порты и адаптеры с проверкой границ ArchUnit. Бизнес-логика живёт в домене, инфраструктура подменяема. Когда брать: сложные инварианты, важен язык, выделены границы (Bounded Context), десятки интеграций, долгий горизонт жизни.

Подсказка по выбору

Что в проекте	Уровень
CRUD, тонкая бизнес-логика, MVP	1
Заметное число операций; разная нагрузка на чтение и запись	2
Сложные инварианты, доменный язык, много интеграций, изоляция от инфраструктуры	3

В одном сервисе разные модули могут жить на разных уровнях: ядро бизнеса — на 3-м, справочники — на 1-м. Это нормально и часто выгоднее, чем «всё на 3-м для единообразия». As-is из существующего кода — Уровень 0.

4. Сквозной кейс

Методология остаётся теорией, пока не приземлена на конкретный бизнес. Поэтому к ней прилагается сквозной кейс — маркетплейс: бизнес-описание в формате «как я понял задачу», без архитектурных терминов.

Кейс — равноправная часть методологии:

Стартовая точка для каждого нового сервиса. Перед спекой и кодом — текст про бизнес. Если бизнес не сформулирован, дальше идти бесполезно.
Эталон для скиллов. Бизнес-описание прогоняется через скиллы (/api-design, /ddd-tactical-design, /usecase-pattern-design), и из него генерируются API-контракты, агрегаты, UseCase-ы — мы видим, что методология работает.
Общая система координат для всех статей сайта. DDD, CQRS, Saga, Resilience4j, OAuth2 — всё разбирается на одном и том же кейсе. Не нужно каждый раз придумывать новый домен.

→ Кейс: маркетплейс — бизнес-описание: стейкхолдеры, глоссарий, процессы, правила, ошибки, целевые объёмы.

Из этого текста через скиллы получаются артефакты по каждому сервису кейса. Что уже разобрано:

Карта сервисов — границы сервисов и их связи.
Notification Service — уведомления по событиям заказа.
Catalog Service и walkthrough — каталог: устройство и путь от описания до кода.
Order Service — заказы, споры и возвраты.

Остальные сервисы кейса — Payment, Customer и Backoffice — появятся по мере наполнения.

Главные правила

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

Один UseCase — одна бизнес-операция. Никаких «универсальных сервисов».
Слои не смешивают модели данных. API-модель ≠ доменная модель ≠ модель хранения.
Внешние зависимости — за интерфейсами. Платёжный шлюз, шина, отправка SMS — всё через порты.
Одна бизнес-операция — одна транзакция. Всё или ничего.
События публикуются атомарно с записью. Никаких «записал, а событие не дошло».
Идемпотентность обязательна там, где она имеет смысл — платежи, создание заказов, повторные доставки сообщений.

Карта сайта

Каждый слой опирается на устоявшиеся практики. Сайт — методичный разбор каждой из них.

Controller / адаптер входа

REST API Style Guide — URL, ресурсы, заголовки, ошибки RFC 9457, OpenAPI.
Паттерны авторизации — OAuth2, JWT, RBAC, ABAC.
Структурные паттерны микросервисов — API Gateway, BFF, Service Discovery.

UseCase + Handler (бизнес-логика)

Что такое DDD — границы и язык домена.
Тактические паттерны DDD — Entity, Value Object, Domain Event.
Стратегические паттерны DDD — Bounded Context.
CQRS — естественное разделение UseCase на Command и Query.
Гексагональная архитектура — Core ↔ Adapters.
Распределённые паттерны — Saga, Outbox, идемпотентность.

Адаптер выхода / данные

Apache Kafka — топики, партиции, гарантии доставки.
Распределённые паттерны — Outbox + polling-relay, Event Sourcing, Idempotent Consumer.

Cross-cutting

Паттерны отказоустойчивости — Retry, Circuit Breaker, Timeout, Bulkhead, Fallback, DLQ.
Паттерны авторизации — RBAC на Gateway, ABAC внутри Handler.

Архитектура и проектирование

Выбор начальной архитектуры — монолит или микросервисы.
Модель C4 — как описывать систему.
Кейс: маркетплейс — сквозной бизнес-домен сайта.

Спецификация и команда

Use Case спецификация: универсальный шаблон — корень контекста + файл на домен-юнит, домен без техники, минимальный frontmatter с level.
Уровень 0 — As-is из кода — реверс существующего сервиса как точка отсчёта для миграции.

Дальше

Готовый стартер: Библиотека usecase-pattern — UseCase / UseCaseHandler / UseCaseDispatcher + Spring Boot auto-configuration + метрики.
Шаблон спецификации: Use Case спецификация.
Скиллы AI-агента: github.com/remodov/usecase-pattern-skills.
Методология и AI: зачем методология, когда пишет AI · AI-native компания · executable standard — правила, которые агент применяет на каждом PR.
Сравнения с другими подходами: UCP и BMAD-METHOD — роли и цикл поставки против доменной спеки и стандартов · UCP и spec-driven инструменты — OpenSpec, Spec Kit и Kiro: спека изменения против спеки системы.
Настройка инструментов: Claude Code под UCP.
Бизнес-кейс сайта: Маркетплейс.