/refactor-code - Scoped Refactor Command for Claude Code

/refactor-code is a custom slash command you add to your own project — not a Claude Code built-in. Claude Code's slash-commands documentation describes the mechanism: project commands live as Markdown files under .claude/commands/, the filename becomes the command name, and text typed after the command is passed to the prompt via the $ARGUMENTS placeholder. This entry is one such command recipe, focused on scoped, behavior-preserving refactors.

You give it a single target — a file, a function, or a pasted selection — and it improves that code's structure without changing what it does, staying inside a narrow ownership boundary for a small, reviewable, PR-sized change. It is the focused counterpart to a broad repo-wide refactor pass.

How to create it

Save the prompt below as .claude/commands/refactor-code.md in your project (the .claude/commands/ directory is where Claude Code reads project slash commands, per the docs). Everything you type after the command name arrives as $ARGUMENTS. Example invocations once installed:

/refactor-code src/auth/session.ts
/refactor-code the parseConfig function

Prompt to save at .claude/commands/refactor-code.md:

Refactor the target the user named: $ARGUMENTS

Rules:
- Preserve behavior exactly. Do not change public APIs or observable output.
- Stay inside the named file/function/selection. Do not touch unrelated code.
- Show the proposed change as a diff and explain each step before applying.
- Prefer small, named extractions over large rewrites.
- After editing, suggest how to verify (tests to run, edge cases to check).

What it focuses on

• Behavior preservation: the refactor must not alter functionality; if a change would, it is flagged as out of scope rather than applied silently.
• Scope discipline: edits stay within the named target; unrelated files and incidental cleanups are left alone.
• Reviewability: changes are presented as a diff with reasoning, sized to fit a single pull request.
• Common moves: extracting functions, naming intermediate values, replacing magic literals with constants, simplifying conditionals, and removing duplication — applied locally, not repo-wide.

When to use it (vs. a broad pass)

Use /refactor-code when the work is centered on a concrete selection and you want a tight, low-risk edit: cleaning up one function before extending it, taming a single complex file, or preparing a focused diff for review. Reach for a broader refactor command when you genuinely intend a cross-cutting modernization across many files.

Verifying the change

Because the goal is behavior preservation, verify rather than assume:

• Run the relevant unit tests before and after the change.
• Diff the public surface (exports, signatures) to confirm nothing moved.
• Check the edge cases the original code handled — empty inputs, error paths, and boundary values.

If a desired improvement would change behavior or reach beyond the named target, treat it as a separate, explicitly-scoped task rather than folding it into this one.

• Source repositorygithub.com 2026-07-18T07:31:52+00:00
• Documentationcode.claude.com