AgentSkillsCN

refactor-guide

当用户提及“重构”“代码清理”“技术债务”“结构调整”“重新组织”“提升代码质量”，或希望在不改变原有行为的前提下优化现有代码时，此技能可提供有力支持。

SKILL.md
--- frontmatter
name: refactor-guide
description: When the user mentions "refactor", "clean up", "technical debt", "restructure", "reorganize", "improve code quality", or wants to improve existing code without changing behavior.

Refactoring Guide

Refactoring Principles

  1. •Tests first - Never refactor without test coverage
  2. •Small steps - One change at a time, commit frequently
  3. •Behavior unchanged - Refactoring ≠ feature change
  4. •Clear purpose - Know WHY you're refactoring

When to Refactor

Good reasons:

  • •Adding a feature is harder than it should be
  • •Bug fixes keep touching the same code
  • •Code is hard to understand after a break
  • •Duplicate code across multiple places
  • •Performance requires structural change

Bad reasons:

  • •"I don't like how it looks"
  • •"I would have done it differently"
  • •"Let's modernize everything"

Code Smells & Fixes

Structural Smells

SmellSymptomRefactoring
Long Function> 30 lines, multiple responsibilitiesExtract Method
Large Class> 300 lines, many concernsExtract Class
Long Parameter List> 4 paramsIntroduce Parameter Object
Feature EnvyMethod uses another class more than its ownMove Method
Primitive ObsessionStrings/numbers representing conceptsValue Object

Code Duplication

TypeFix
Identical codeExtract to shared function
Similar codeExtract with parameters
Parallel inheritanceTemplate Method pattern

Coupling Issues

SmellFix
Inappropriate IntimacyMove methods, introduce interface
Message ChainsHide Delegate
Middle ManRemove unnecessary delegation

Safe Refactoring Steps

Extract Function

code
1. Identify code to extract
2. Create new function with clear name
3. Copy code to new function
4. Replace original with function call
5. Run tests
6. Commit

Rename

code
1. Use IDE rename (not find-replace)
2. Update all references automatically
3. Check for string references manually
4. Run tests
5. Commit

Move Code

code
1. Copy to new location
2. Make old location delegate to new
3. Run tests
4. Update callers to use new location
5. Remove delegation
6. Run tests
7. Commit

Refactoring Strategies

Strangler Fig Pattern:

  • •Build new alongside old
  • •Route traffic gradually
  • •Remove old when unused

Branch by Abstraction:

  • •Introduce abstraction layer
  • •Implement new version behind it
  • •Switch implementations
  • •Remove abstraction if desired

Parallel Change:

  • •Add new, don't modify old
  • •Migrate callers incrementally
  • •Remove old when unused

Red Flags During Refactoring

Stop and reassess if:

  • •Tests are failing
  • •Scope keeps growing
  • •You're fixing bugs while refactoring
  • •Changes cascade unexpectedly
  • •You can't explain the improvement

Output Format

When proposing refactoring:

  1. •Current Issues - Specific problems with current code
  2. •Proposed Changes - What will change and why
  3. •Migration Path - Step-by-step safe transition
  4. •Risk Assessment - What could go wrong
  5. •Verification - How to confirm success