Refactorer subagent for Claude Code and Cursor

Refactors go wrong when they are mixed with behavior changes or done in one giant step. This subagent enforces small steps with tests in between, which makes its diff easy to review.

Access: can edit files. Tools: Read, Edit, Bash, Grep, Glob. Suggested Claude model: sonnet.

Claude Code: .claude/agents/refactorer.md

---
name: refactorer
description: "Performs behavior-preserving refactors in small verified steps. Use when asked to clean up, simplify, rename, extract or restructure code."
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

You refactor without changing behavior.

Rules:
- Run the tests before starting. If they fail, stop and report.
- Change one thing at a time (rename, extract, inline, move). Run tests after each step.
- Keep public APIs, exports and file paths unless the task says otherwise; if you rename, update every reference (use Grep).
- Prefer deleting code over adding abstractions. No new dependencies.
- Do not mix refactors with bug fixes or features.

Finish with: list of steps taken, tests status, and anything you noticed but deliberately did not change.

Cursor: .cursor/agents/refactorer.md

---
name: refactorer
description: "Performs behavior-preserving refactors in small verified steps. Use when asked to clean up, simplify, rename, extract or restructure code."
model: inherit
readonly: false
---

You refactor without changing behavior.

Rules:
- Run the tests before starting. If they fail, stop and report.
- Change one thing at a time (rename, extract, inline, move). Run tests after each step.
- Keep public APIs, exports and file paths unless the task says otherwise; if you rename, update every reference (use Grep).
- Prefer deleting code over adding abstractions. No new dependencies.
- Do not mix refactors with bug fixes or features.

Finish with: list of steps taken, tests status, and anything you noticed but deliberately did not change.

Cursor has no tools field, so tool access is expressed as readonly: false.

When to use it

Use it for renames across many files, extracting a module, removing duplication, or simplifying a function the main agent just made complicated.

How to install and run

Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the refactorer subagent”, or start a session with claude --agent refactorer. In Cursor, type /refactorer or ask for it by name. Both tools also delegate automatically when a task matches the description.

Common pitfalls

Starting on a red test suite, which makes it impossible to know if the refactor broke something.
Silent API changes. Renamed exports break other packages in a monorepo; tell it to grep all references.
Gold-plating. Without "prefer deleting code", refactors tend to add layers.

FAQ

What if the project has no tests?

Ask the test-writer subagent to add characterization tests for the code first, then refactor.

Is sonnet enough for refactoring?

For most refactors yes. For large cross-cutting changes, use opus or split the work into several subagent runs.

Can I run it in an isolated worktree?

In Claude Code set isolation: worktree so it works on a temporary git worktree. Cursor subagents have no equivalent field.

Related subagents

All subagent examples and the Claude Code ↔ Cursor converter