Executes refactoring changes in small, test-backed steps so behavior is preserved while structure improves. Each refactoring operation—rename, extract, inline, move—is validated by the test suite before proceeding to the next, preventing the common pattern of refactoring into subtle behavioral regressions that are only caught in production.
Use cases
- Renaming a widely-used function or variable that appears across multiple files
- Extracting a long function into smaller, focused units with clear responsibilities
- Moving code between modules or packages to improve the dependency structure
- Replacing a complex conditional with a polymorphism-based approach that is easier to extend
- Converting procedural code to use a defined data structure or class hierarchy
Key features
- Before refactoring, establish a test harness or characterization suite that pins the current behavior—run it and confirm all tests pass
- Perform one refactoring operation at a time (rename one variable, extract one function) and run the test suite after each change
- Keep commits small and focused: a commit per refactoring operation makes it easy to bisect if a regression is introduced
- Use automated refactoring tools where available (IDE rename, extract method) rather than manual search-and-replace to avoid typos
- After the full refactor, run the complete test suite and verify the behavioral output is identical to the pre-refactor baseline
When to Use This Skill
- When legacy code needs structural improvement and there are no existing tests to serve as a safety net
- When a code review identifies a pattern (long function, deep nesting, duplicated logic) that should be improved
- When preparing code for a new feature that would be significantly easier to implement in a well-structured codebase
Expected Output
Refactored code with improved structure, a passing test suite that confirms behavior is unchanged, and a commit history that isolates each refactoring operation.
Frequently Asked Questions
- How do I refactor code that has no tests?
- Write a characterization test first: run the code, capture the actual output, then write a test that asserts that output. This pins behavior before you change structure. Without this step, you have no way to know if your refactor changed behavior.
- Should I refactor and add features in the same PR?
- Ideally no—keep them separate so the refactor can be reviewed and merged independently. If a feature depends on a refactor, complete the refactor first, merge it, then build the feature on the improved structure.
- What if the existing tests are poor quality?
- Poor tests that pass are still useful as a behavioral anchor. Do not delete them without replacing them with better coverage. A bad passing test protects against regressions better than no test at all.
Related
Related
3 Indexed items
Test-driven development
Drives development through red-green-refactor cycles where you write a failing test that names the desired behavior before writing any implementation code. TDD produces tests that document intent, catches regressions immediately, and forces small, verifiable increments—making it especially valuable for complex features, bug fixes with known failure cases, and any code that needs a long-term safety net.
Contract testing
Locks API expectations between services using consumer-driven contracts so that when one team changes their implementation, it fails in CI rather than during a coordinated production deployment. Contract testing prevents the common integration failure pattern where both sides of an API appear to work in isolation but break when connected in production.
Executing implementation plans
Executes a pre-written implementation plan in disciplined order, stopping at defined checkpoints to verify assumptions before moving forward. This skill prevents the common pattern of diverging from the plan silently when reality proves it wrong, and it creates natural opportunities to course-correct before small errors compound into large rework.