Asking for a refactor

"Make this code better" is not a refactor brief. It is an invitation for Claude to guess what you value — and Claude will guess confidently, wrong, and at scale.

What a refactor brief contains

A usable brief has four parts: the structural change, the motivation, the boundary, and the success criterion. Missing any one of them produces a diff that is either too narrow (Claude interprets literally and misses the obvious adjacent case) or too wide (Claude interprets liberally and rewrites the module).

Here is a brief that works:

Refactor: Extract the database calls from UserController into a UserService class.
Motivation: The controller is being unit-tested in isolation and the DB calls prevent
mocking. We want the controller to call service methods, not query the DB directly.
Boundary: Do not change the route definitions in routes/user.ts or any test files.
Success: All existing tests pass. The controller has no direct imports from src/db/.

Here is a brief that does not work:

Clean up the auth module.

The difference is not length. It is specificity about structure, not style.

Naming the structural change

"Extract X into Y," "move X from A to B," "split X into two functions," "collapse X and Y into a single pipeline" — these are structural changes. "Make it cleaner," "simplify it," "improve readability" are style preferences. Claude can execute structural changes reliably. Style preferences produce unpredictable diffs.

Stating the motivation

The motivation lets Claude make judgment calls at the decision points it will encounter inside the task. "We're extracting this because the controller is being tested in isolation" tells Claude why mocking matters. When Claude finds a helper function that straddles the controller/service boundary, it knows which side it belongs on — the side closer to the service, because that is where the DB logic should live.

Without a motivation, Claude picks the most locally plausible option, which is rarely the architecturally correct one.

Setting the boundary

The boundary is the single highest-leverage sentence in the brief. "Do not touch the route definitions" prevents 80% of scope creep. Be specific: name the files or directories that are off-limits. "Don't touch tests" is better than "leave the rest alone."

A working brief template

Refactor: [structural change — what moves where]
Motivation: [why — what problem this solves]
Boundary: [what not to touch — specific files or dirs]
Success: [observable criterion — tests pass, no import from X, function count reduced]

If you get stuck

• Claude rewrites more than the brief asked: check whether your "boundary" sentence was specific enough. "Don't change other things" is not specific. "Don't touch files in src/routes/ or src/tests/" is.
• Claude asks clarifying questions mid-task: answer them. The question usually means the brief had an ambiguity at exactly the place Claude is working. Answer narrowly — one sentence, not a new brief.
• The refactor passes your review but breaks a test you did not know existed: this means the test was testing the structural coupling you just removed. Read the test. Decide whether the test was right or whether it needs to be updated to match the new architecture.

Cross-reference

l6 ("Tests as the safety rail") covers what to do when the function you are refactoring has no tests. Write the tests first. The refactor brief format here works best when there is something to verify against.

Deliverable

Write a refactor brief using the template above for one function or module in your codebase. Run it. Compare the diff against the brief. Note one way the diff diverged from what you specified and whether that divergence was correct or a scope error.