AgentSkillsCN

refactoring-surgeon

精通代码重构，能够在不改变程序行为的前提下提升代码质量。适用于以下场景：重构、代码异味、技术债务、遗留代码、代码清理、代码简化、提取方法、提取类、DRY 原则、SOLID 原则。不适用于：新功能开发（应使用功能开发技能）、Bug 修复（应使用调试技能）、性能优化（应使用性能调优技能）。

SKILL.md
--- frontmatter
name: refactoring-surgeon
description: "Expert code refactoring specialist for improving code quality without changing behavior. Activate on: refactor, code smell, technical debt, legacy code, cleanup, simplify, extract method, extract class, DRY, SOLID principles. NOT for: new feature development (use feature skills), bug fixing (use debugging skills), performance optimization (use performance skills)."
allowed-tools: Read,Write,Edit,Bash(npm test:*,npm run lint:*,git:*)
category: Code Quality & Testing
tags:
  - refactoring
  - code-smells
  - solid
  - dry
  - cleanup
pairs-with:
  - skill: code-necromancer
    reason: Refactor resurrected legacy code
  - skill: test-automation-expert
    reason: Tests before refactoring

Refactoring Surgeon

Expert code refactoring specialist focused on improving code quality without changing behavior.

Quick Start

  1. •Ensure tests exist - Never refactor without a safety net
  2. •Identify the smell - Name the specific code smell you're addressing
  3. •Make small changes - One refactoring at a time, commit frequently
  4. •Run tests after each change - Behavior must remain identical
  5. •Don't add features - Refactoring ≠ enhancement
  6. •Document significant changes - Explain the "why" for future maintainers

Core Capabilities

CategoryTechniques
ExtractionExtract Method, Extract Class, Extract Interface
MovementMove Method, Move Field, Inline Method
SimplificationReplace Conditional with Polymorphism, Decompose Conditional
OrganizationIntroduce Parameter Object, Replace Magic Numbers
Legacy MigrationStrangler Fig, Branch by Abstraction, Parallel Change

Code Smells Reference

Bloaters

code
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│    Long Method      │    │    Large Class      │    │   Long Parameter    │
│  > 20 lines?        │    │  > 200 lines?       │    │       List          │
│  → Extract Method   │    │  → Extract Class    │    │  → Parameter Object │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

OO Abusers

code
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Switch Statements  │    │   Refused Bequest   │    │   Parallel          │
│  Type-checking?     │    │  Unused inheritance?│    │   Hierarchies       │
│  → Polymorphism     │    │  → Delegation       │    │  → Move Method      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

Change Preventers

code
┌─────────────────────┐    ┌─────────────────────┐
│  Divergent Change   │    │  Shotgun Surgery    │
│  One class, many    │    │  One change, many   │
│  reasons to change? │    │  classes affected?  │
│  → Extract Class    │    │  → Move/Inline      │
└─────────────────────┘    └─────────────────────┘

Reference Examples

Complete refactoring examples in ./references/:

FilePatternUse Case
extract-method.tsExtract MethodLong methods → focused functions
replace-conditional-polymorphism.tsReplace Conditionalswitch/if → polymorphic classes
introduce-parameter-object.tsParameter ObjectLong params → structured objects
strangler-fig-pattern.tsStrangler FigLegacy code → gradual migration

Anti-Patterns (10 Critical Mistakes)

1. Big Bang Refactoring

Symptom: Rewriting entire modules in one massive change Fix: Strangler fig pattern, small incremental changes with tests

2. Refactoring Without Tests

Symptom: Changing structure without test coverage Fix: Write characterization tests first, add coverage for affected areas

3. Premature Abstraction

Symptom: Creating generic frameworks "for future flexibility" Fix: Wait for three concrete examples before abstracting (Rule of Three)

4. Renaming Without IDE Support

Symptom: Find-and-replace that misses occurrences Fix: Use IDE refactoring tools, search for usages first

5. Mixing Refactoring and Features

Symptom: Adding new functionality while restructuring Fix: Separate commits - refactor first, then add features

6. Ignoring Code Reviews

Symptom: Large refactoring PRs that are hard to review Fix: Small, focused PRs with clear commit messages

7. Over-Abstracting

Symptom: Three layers of abstraction for a simple operation Fix: YAGNI - start concrete, abstract when patterns emerge

8. Incomplete Refactoring

Symptom: Starting Extract Method but leaving partial duplication Fix: Complete the refactoring or revert - no half-measures

9. Refactoring Production During Incidents

Symptom: "I'll just clean this up while I'm here..." Fix: Never refactor during incidents - fix the bug, create a ticket

10. Not Measuring Improvement

Symptom: Refactoring without knowing if it helped Fix: Track metrics: complexity, test coverage, build time

Safety Checklist

Before Refactoring:

  • • Code compiles/runs successfully
  • • All tests pass
  • • Test coverage is adequate for area being refactored
  • • Commit current state (can rollback)

During Refactoring:

  • • Make small, incremental changes
  • • Run tests after each change
  • • Keep behavior identical
  • • Don't add features while refactoring

After Refactoring:

  • • All tests still pass
  • • No new warnings/errors
  • • Code is more readable
  • • Complexity metrics improved
  • • Document significant changes

Quality Checklist

  • • No behavior changes (tests prove this)
  • • Improved readability
  • • Reduced complexity (cyclomatic, cognitive)
  • • Better adherence to SOLID principles
  • • Removed duplication (DRY)
  • • More testable code
  • • Clear naming
  • • Appropriate abstractions (not over-engineered)

Validation Script

Run ./scripts/validate-refactoring.sh to check:

  • •Test coverage presence
  • •Code smell indicators
  • •Duplication patterns
  • •Complexity metrics
  • •SOLID violations
  • •Refactoring safety (git, uncommitted changes)

External Resources