Refactor Code Instant

Refactor a file or function by applying a specified pattern (extract function, rename, simplify conditionals) while preserving behavior and verifying tests still pass.

When to Use This Command

Run this command when...

• A function is too long or too complex and needs to be broken into smaller, focused pieces
• You want to rename variables or functions across a file with consistency
• You need to simplify deeply nested conditionals or convert callback chains to async/await

Avoid this command when...

• You need to change behavior, not just restructure code (that is a feature change)
• The code has no tests and you cannot verify that behavior is preserved after the refactor

Quick Start

Copy
# .claude/commands/refactor-code-instant.md
---
allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep"]
---
Apply the specified refactoring to the target file or function.
Preserve all behavior. Run tests to verify equivalence.

Example usage:

/refactor-code-instant src/handlers/order.ts "extract the validation logic into a separate function"

Example output:

Refactoring: src/handlers/order.ts
===================================
Pattern: Extract Function

Before: handleOrder() - 120 lines, complexity 18

After:
  handleOrder()      - 45 lines, complexity 6
  validateOrder()    - 35 lines, complexity 8
  calculateTotals()  - 40 lines, complexity 4

Verification:
  npm test -- order.test.ts
  12 tests passed, 0 failed

Behavior preserved. Complexity reduced by 67%.

Core Concepts

Concept	Description
Extract function	Moves a block of code into a new named function with clear inputs/outputs
Rename	Updates a symbol name across all references within the file or module
Simplify	Reduces nesting with early returns, guard clauses, or lookup maps
Verify	Runs the test suite to confirm behavior is unchanged after restructuring

Target Code --> Identify Pattern --> Apply Refactor
                                          |
                                    Run Tests
                                          |
                                  PASS? --> Report
                                    |
                                    No --> Revert Changes

Configuration

Option	Default	Description
pattern	auto	Refactoring pattern to apply (extract, rename, simplify)
verify	true	Run tests after refactoring to confirm behavior preserved
scope	file	Scope of the refactoring (function, file, module)
dry-run	false	Show proposed changes without applying them
max-complexity	10	Target cyclomatic complexity after refactoring

Best Practices

1. Always run tests -- refactoring without test verification is guessing, not systematic improvement.
2. One pattern at a time -- apply a single refactoring per command to keep changes small and reviewable.
3. Commit before refactoring -- a clean commit gives you a safe revert point if something goes wrong.
4. Reduce complexity first -- extract functions to bring down complexity, then rename for clarity.
5. Check the diff carefully -- review every change to ensure no subtle behavior alteration slipped in.

Common Issues

1. Tests fail after refactor -- the restructuring may have changed variable scope or this binding. Check closures and class context.
2. Renamed symbol has external callers -- if the symbol is exported, references in other files need updating too. Use module-level scope.
3. Extracted function has too many parameters -- if the new function needs 5+ parameters, consider grouping them into an options object.