Refactoring Plan Template
Use this template to document and track your refactoring effort.
Project Information
| Field | Value |
|---|---|
| Project/Module | [Project name] |
| Target Files | [List of files to refactor] |
| Date Created | [Date] |
| Author | [Name] |
| Status | Draft / In Review / Approved / In Progress / Completed |
Executive Summary
Goals
- [ ] [Primary goal: e.g., Improve readability of payment processing]
- [ ] [Secondary goal: e.g., Reduce code duplication]
- [ ] [Tertiary goal: e.g., Improve testability]
Constraints
- [ ] [Constraint 1: e.g., Cannot change public API]
- [ ] [Constraint 2: e.g., Must maintain backward compatibility]
- [ ] [Constraint 3: e.g., No changes to database schema]
Risk Level
- [ ] Low - Minor changes, well-tested code
- [ ] Medium - Moderate changes, some risk
- [ ] High - Significant changes, careful attention needed
Pre-Refactoring Checklist
Test Coverage Assessment
| Metric | Current | Target | Status |
|---|---|---|---|
| Unit Test Coverage | __% | ≥80% | |
| Integration Tests | Yes/No | Yes | |
| All Tests Passing | Yes/No | Yes |
Required Before Starting
- [ ] All tests passing
- [ ] Code reviewed and understood
- [ ] Backup/version control in place
- [ ] User approval obtained
Identified Code Smells
Summary
| # | Smell | Location | Severity | Priority |
|---|---|---|---|---|
| 1 | [e.g., Long Method] | [file:line] | High | P1 |
| 2 | [e.g., Duplicate Code] | [file:line] | Medium | P2 |
| 3 | [e.g., Feature Envy] | [file:line] | Low | P3 |
Detailed Analysis
Smell #1: [Name]
Location: path/to/file.js:45-120
Description: [Detailed description of the problem]
Impact: - [Impact 1] - [Impact 2]
Proposed Solution: [Brief overview of how to fix]
Refactoring Phases
Phase A: Quick Wins (Low Risk)
Objective: Simple improvements with immediate value
Estimated Changes: [X files, Y methods]
User Approval Required: Yes / No
| # | Task | File | Refactoring | Status |
|---|---|---|---|---|
| A1 | Rename variable x to userCount |
utils.js:15 | Rename Variable | [ ] |
| A2 | Remove unused oldHandler() |
api.js:89 | Remove Dead Code | [ ] |
| A3 | Extract duplicate validation | form.js:23,67 | Extract Method | [ ] |
Rollback Plan: Revert commits A1-A3
Phase B: Structural Improvements (Medium Risk)
Objective: Improve code organization and clarity
Estimated Changes: [X files, Y methods]
User Approval Required: Yes
Dependencies: Phase A must be complete
| # | Task | File | Refactoring | Status |
|---|---|---|---|---|
| B1 | Extract calculatePrice() from long method |
order.js:45 | Extract Method | [ ] |
| B2 | Introduce OrderDetails parameter object |
order.js:12 | Introduce Parameter Object | [ ] |
| B3 | Move formatAddress() to Address class |
customer.js:78 | Move Method | [ ] |
Rollback Plan: Revert to post-Phase-A commit
Phase C: Architectural Changes (Higher Risk)
Objective: Address deeper structural issues
Estimated Changes: [X files, Y methods]
User Approval Required: Yes
Dependencies: Phases A and B must be complete
| # | Task | File | Refactoring | Status |
|---|---|---|---|---|
| C1 | Replace price switch with polymorphism | pricing.js:30 | Replace Conditional with Polymorphism | [ ] |
| C2 | Extract NotificationService class |
user.js:100 | Extract Class | [ ] |
Rollback Plan: Revert to post-Phase-B commit
Detailed Refactoring Steps
Task [ID]: [Task Name]
Smell Addressed: [Smell name]
Refactoring Technique: [Technique name]
Risk Level: Low / Medium / High
Context
Before (Current State):
// Paste current code here
After (Expected State):
// Paste expected code here
Step-by-Step Mechanics
- [ ] Step 1: [Description]
- Test: Run tests after this step
-
Expected: All tests pass
-
[ ] Step 2: [Description]
- Test: Run tests after this step
-
Expected: All tests pass
-
[ ] Step 3: [Description]
- Test: Run tests after this step
- Expected: All tests pass
Verification
- [ ] All tests passing
- [ ] Behavior unchanged
- [ ] Code compiles
- [ ] No new warnings
Commit Message
refactor: [Describe the refactoring]
Progress Tracking
Phase Status
| Phase | Status | Started | Completed | Tests Passing |
|---|---|---|---|---|
| A | Not Started / In Progress / Done | |||
| B | Not Started / In Progress / Done | |||
| C | Not Started / In Progress / Done |
Issues Encountered
| # | Issue | Resolution | Status |
|---|---|---|---|
| 1 | [Description] | [How resolved] | Open / Resolved |
Metrics Comparison
Before Refactoring
| Metric | File 1 | File 2 | Total |
|---|---|---|---|
| Lines of Code | |||
| Cyclomatic Complexity | |||
| Maintainability Index | |||
| Number of Methods | |||
| Avg Method Length |
After Refactoring
| Metric | File 1 | File 2 | Total | Change |
|---|---|---|---|---|
| Lines of Code | ||||
| Cyclomatic Complexity | ||||
| Maintainability Index | ||||
| Number of Methods | ||||
| Avg Method Length |
Post-Refactoring Checklist
- [ ] All tests passing
- [ ] No new warnings or errors
- [ ] Code compiles successfully
- [ ] Manual verification completed
- [ ] Documentation updated (if needed)
- [ ] Code reviewed
- [ ] Metrics improved
- [ ] User sign-off obtained
Lessons Learned
What Went Well
- [Item 1]
- [Item 2]
What Could Be Improved
- [Item 1]
- [Item 2]
Recommendations for Future
- [Item 1]
- [Item 2]
Approvals
| Role | Name | Date | Signature |
|---|---|---|---|
| Plan Author | |||
| Technical Lead | |||
| Product Owner |
Appendix
A. Related Documentation
- [Link to relevant docs]
B. Reference Materials
- [Link to code smells catalog]
- [Link to refactoring catalog]
C. Tools Used
- [Testing framework]
- [Linting tools]
- [Complexity analysis tools]
Last Updated: August 4, 2026 Claude Code Version: 2.1.220 Sources: - https://code.claude.com/docs/en/skills Compatible Models: Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 5.5, Claude Haiku 4.5