Use Case Pattern: a step-by-step guide

← Back to the section

The question most often sounds like this: "I get what the Use Case Pattern is — but where do I start right now?". This article answers exactly that: two concrete scenarios, the commands, the expected results, and the common mistakes.

Before you start, make sure the skills are installed: UCP skills — catalog and installation.

When the task is small: one operation in an existing service

The most common case is when you need to add a single business operation: check an order's status, cancel a payment, export a report. Not a new service, not a refactoring — just one operation.

Here you need a single skill: open Claude Code in the project and call:

/ucp-pattern-design Command "cancel order" with a DRAFT|PAID status check and a permission check by customerId

In 30–60 seconds the skill returns:

• CancelOrderUseCase — the command object describing the input and the expected result;
• CancelOrderHandler — the component with transactional semantics; the business logic for the status and permission checks lives inside;
• a controller with authorization, implementing the OpenAPI interface;
• tests for the main scenarios (allowed transitions, permission denial, status mismatch).

Then:

1. Read the response carefully.
2. Apply it through Claude Code's editing tools (or copy it in manually).
3. Run /ucp-pattern-review on the fresh diff — you get findings if something breaks the rules.
4. Run the tests, fix anything that's red.
5. Open a PR.

The real time from request to committed code is 5–10 minutes.

A table of skills for small tasks

Different types of operations call for different skills:

Every design skill has a paired *-review — for checking code that's already written.

When the task is large: a new service from scratch

Here the input is a business description (a page at minimum), and the output is a working service. The process has four steps.

Step 1. Write the spec from the business description

/ucp-spec-design A marketplace catalog service. The seller publishes and hides products, the Order Service takes the price by productId. Maturity level 2

The skill reads the description and creates a specification in docs/spec/: the root context file and one file per domain unit in aggregates/.

If the service already exists and there is no description — start with /ucp-spec-tier-0. It reads the code, the migrations, and the configuration and creates an as-is spec in the same format. That's the starting point for later improvement.

Step 2. Draft the implementation plan

/superpowers:writing-plans

The skill reads the spec and produces a numbered plan of steps — each with acceptance criteria. For example:

1. Project scaffold (modules, build, profiles)
2. DB schema migration: initial-schema
3. Code generation from the applied schema
4. ProductRepository — data access
5. CreateProductUseCase + Handler + controller
6. PublishProductUseCase + Handler
7. HideProductUseCase + Handler
8. GET /products/{id} — query
9. Security configuration (prod / local / integration-test)
10. Integration tests for each UseCase
11. Architecture tests for the layer invariants

Step 3. Execute the plan

/superpowers:executing-plans

The skill goes through the plan step by step and, at each one, calls the appropriate ucp-*-design:

After each step, verify: the build and tests are green before moving on to the next step.

Step 4. Final review

/ucp-pattern-review
/ucp-api-review
/ucp-ddd-tactical-review
/ucp-java-style-review
/ucp-auth-review

Each methodology skill walks through the diff. The findings reference specific rule codes. After that, an outside view via /superpowers:requesting-code-review: the reviewer looks at the PR from the outside and catches what a familiar eye misses.

From business description to a working service takes a day or two, once the stack is installed.

How to pick the scenario

A simple rule:

• One operation in an existing service → a single ucp-*-design skill directly.
• Several operations in an existing service → the first scenario repeated one operation per iteration, without superpowers.
• A new service from scratch → the second scenario in full.
• Rewrite an existing service → first ucp-pattern-review on the current code (to understand what's wrong), then a migration plan via superpowers:writing-plans, then the second scenario module by module.
• The approach itself is unclear → /superpowers:brainstorming, then the second scenario with a decision already made.

What's worth doing

Start one level lower than seems necessary. If you're torn between maturity level 2 and 3 — take 2. The level is easy to raise and hard to lower. DDD and Hexagonal are needed where the domain has complex invariants (order, payment, booking). Reference data and admin pages are level 1 or 2.

Don't skip the verification after each step. When the AI generates something that looks correct, the temptation to skip the check is strong. A non-green build after a step is a signal that the step is bad and you need to go back.

One UseCase — one PR. Don't cram five operations into one commit, even if the AI writes them fast. PR size directly affects review quality.

Keep the spec and the code in sync. Changed a UseCase in the code — update the spec in the same PR. A divergence is a bug, not a "we'll fix it later".

Review skills come before a human, not instead of one. ucp-*-review catches rule violations; a human looks at the architecture and the trade-offs.

What to avoid

"We'll write the spec first, then the code" — a spec without code goes stale in two weeks. Do them in parallel, or don't write a spec at all.

"The AI refactored three neighboring modules while it was at it" — a narrow prompt gives a narrow diff. "While it was at it" turns into a large PR that nobody has time to review.

"We use level 3 everywhere because we do DDD" — level 3 is more expensive to maintain. Use it only where the domain has real invariants.

"The AI wrote the tests, I didn't read them" — wrapper tests (assertNotNull, verify(any())) let bugs through. Read five tests — that tells you the quality of the rest.

"Skills plus a team of role-based agents is even better" — no. Multiple agents in an autonomous dialogue break style consistency and the audit trail. More on this — in the article on installing the skills.

In short

• One operation → a single ucp-pattern-design directly, result in a few minutes.
• A new service → ucp-spec-design → plan → executing-plans → final reviews.
• Start one level lower than seems necessary: level 2 instead of 3 if there are no complex invariants.
• One UseCase — one PR. One step — a green build before the next.
• The spec and the code must match: the UseCase changed — update the spec in the same PR.
• Review skills complement a human, they don't replace one.

What to read next

• UCP skills — catalog and installation — if you haven't set up the tools yet.
• Use Case specification: a universal template — the context root and the domain units.
• Maturity levels: 1 — Layered → 2 — Use Case Pattern → 3 — DDD + Hexagonal.
• Case study: Order Service (maturity level 3) — a full example of a service applying UCP.