Safe refactoring for legacy or complex codebases: preserve behavior while improving structure, reducing technical debt, and tightening quality gates...
Use this skill to refactor safely: preserve behavior, reduce risk, and keep CI green while improving maintainability and delivery speed.
Defaults: baseline first, smallest safe step next, and proof via tests/contracts/observability instead of intuition.
main green; reproduce the behavior you must preserve.main green; reproduce the behavior you must preserve.| Risk | Examples | Minimum required safety net |
|---|---|---|
| Low | rename, extract method, formatting-only | unit tests + lint/type checks |
| Medium | moving logic across modules, dependency inversion | unit + integration/contract tests at boundary |
| High | auth/permission paths, concurrency, migrations, money/data-loss paths | integration + contract tests, observability checks, canary + rollback plan |
git bisect viable: avoid mixed "mechanical + semantic" changes unless necessary.Do:
Avoid:
| Task | Tool/Pattern | Command/Approach | When to Use |
|---|---|---|---|
| Long method (>50 lines) | Extract Method | Split into smaller functions | Single method does too much |
| Large class (>300 lines) | Split Class | Create focused single-responsibility classes | God object doing too much |
| Duplicated code | Extract Function/Class | DRY principle | Same logic in multiple places |
| Complex conditionals | Replace Conditional with Polymorphism | Use inheritance/strategy pattern | Switch statements on type |
| Long parameter list | Introduce Parameter Object | Create DTO/config object | Functions with >3 parameters |
| Legacy code modernization | Characterization Tests + Strangler Fig | Write tests first, migrate incrementally | No tests, old codebase |
| Automated quality gates | ESLint, SonarQube, Prettier | npm run lint, CI/CD pipeline |
Prevent quality regression |
| Technical debt tracking | SonarQube, CodeClimate | Track trends + hotspots | Prioritize refactoring work |
Code issue: [Refactoring Scenario]
├─ Code Smells Detected?
│ ├─ Duplicated code? → Extract method/function
│ ├─ Long method (>50 lines)? → Extract smaller methods
│ ├─ Large class (>300 lines)? → Split into focused classes
│ ├─ Long parameter list? → Parameter object
│ └─ Feature envy? → Move method closer to data
│
├─ Legacy Code (No Tests)?
│ ├─ High risk? → Write characterization tests first
│ ├─ Large rewrite needed? → Strangler Fig (incremental migration)
│ ├─ Unknown behavior? → Characterization tests + small refactors
│ └─ Production system? → Canary deployments + monitoring
│
├─ Quality Standards?
│ ├─ New project? → Setup linter + formatter + quality gates
│ ├─ Existing project? → Add pre-commit hooks + CI checks
│ ├─ Complexity issues? → Set cyclomatic complexity limits (<10)
│ └─ Technical debt? → Track in register, 20% sprint capacity
../qa-debugging/SKILL.md../data-sql-optimization/SKILL.md../software-architecture-design/SKILL.mdCC-*) for citationRULE-01–RULE-13, decision trees, and operational proceduresSee references/operational-patterns.md for detailed refactoring catalogs, automated quality gates, technical debt playbooks, and legacy modernization steps.
Use copy-paste templates in assets/ for checklists and quality-gate configs:
Use deep-dive guides in references/ (load only what you need):
Do:
Avoid:
See data/sources.json for curated external references.
