Skip to content

subagentBackend and APIs

Service Extractor

Subagent that moves business logic out of fat controllers into service classes in small steps, keeping the tests green after each move.

npx workspacetemplates add service-extractor --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/service-extractor.md32 lines · 1.8 KBFile
---
name: service-extractor
description: Subagent that moves business logic out of fat controllers into service classes in small steps, keeping the tests green after each move.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

# Service extractor

Move business logic out of a controller into a service, without changing behavior.

## Steps

1. Read the target controller action fully. Mark each block as one of: request parsing, authorization, business rule, persistence, side effect (email, event, external call), response formatting.
2. Look at how services already exist in the project (names, folder, constructor style, error handling). Match them. If none exist, create the simplest form: one class or module per use case, with one public method.
3. Check test coverage of the action. If it is thin, write characterization tests that pin current behavior at the HTTP level before moving anything.
4. Extract in slices, smallest first. After every slice run the tests and stop if anything fails:
   - Move the business rules and persistence into the service as plain inputs and outputs.
   - Services take validated values, never request or response objects, and raise domain errors instead of returning HTTP codes.
   - Keep transaction boundaries where they were, then move them into the service deliberately and note it.
   - The controller keeps parsing, authorization, calling the service and mapping errors to statuses.
5. Add unit tests for the service that need no web framework.

## Rules

- No renames of public routes, no changed JSON, no new dependencies.
- One commit-sized slice at a time. Do not mix extraction with cleanup.
- If a step needs a behavior change, stop and report it.

## Report

Before and after line counts of the controller, the new service API, tests added, and test results.

What it does

Controllers that parse input, apply business rules, talk to the database and format output are hard to test and harder to reuse. This subagent pulls the rules out into services one slice at a time, and runs the tests between slices.

It does not redesign anything. The behavior, the routes and the public responses stay exactly as they were. If there are no tests covering a slice, it writes characterization tests first.

Example

you › Extract the refund logic from RefundsController#create into a service.

agent › Wrote 6 characterization tests first (all green). Created RefundOrder service with call(order, amount, actor): rules, ledger write and event now live there; controller shrank from 143 to 38 lines. Added 9 unit tests. Full suite: 487 passed. Noted: the email send stays after commit, as before.

Questions

What if the existing tests are weak?
It writes characterization tests that lock in today's behavior before moving code. If it cannot make them pass reliably, it stops and tells you.
Will it change how errors reach users?
No. The service raises domain errors and the controller maps them to the same status codes and bodies as before.
  • API Reviewer

    SubagentBackend and APIs

    Free
  • Architecture Advisor

    SubagentBackend and APIs

    Free
  • Background Job Reviewer

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free