Frontend behavior preserving refactor

Frontend Refactor Skill

For the Simplified Chinese reference, read references/zh-CN.md when the user communicates primarily in Chinese or requests Chinese output.

Purpose

Reduce verified maintenance cost while preserving observable behavior and enabling safe rollback.

When to Use

Use when code works but has duplication, unclear ownership, excessive coupling, weak types, or measured performance cost.

Inputs

• Refactor objective and non-goals
• Existing behavior and tests
• Architecture constraints and consumers
• Baseline metrics when performance is involved

Outputs

• Behavior-preservation plan
• Incremental structural changes
• Validation evidence and migration notes

Workflow

1. Define the exact problem and observable behavior to preserve.
2. Map consumers, public APIs, side effects, and test coverage.
3. Establish a safety net before structural changes.
4. Choose the smallest reversible sequence.
5. Separate mechanical moves from semantic changes.
6. Keep compatibility adapters only when a migration requires them.
7. Validate after each coherent step.
8. Remove obsolete paths after all consumers migrate.

Decision Tree

flowchart TD
  A[Refactor request] --> B{Behavior is covered?}
  B -->|No| C[Add characterization tests]
  B -->|Yes| D{Public API changes?}
  C --> D
  D -->|Yes| E[Plan migration and compatibility]
  D -->|No| F[Refactor internally]
  E --> G[Validate consumers]
  F --> G

Checklist

• Goal and non-goals are explicit.
• Existing behavior is characterized.
• Public consumers are identified.
• Steps are reversible and independently valid.
• Performance claims have measurements.
• Dead compatibility code is removed when safe.

Constraints

• MUST NOT mix unrelated feature behavior into the refactor.
• MUST preserve observable behavior unless a change is explicitly approved.
• SHOULD NOT introduce a new abstraction with only one unstable use case.
• MUST document breaking API changes and migration steps.

Examples

Good: Extract validated request mapping behind the existing public function, migrate callers, then remove duplicate parsing.

Bad: Rename files, rewrite state, replace the UI library, and alter behavior in one pull request.

Anti-patterns

• Refactoring for aesthetic preference alone
• Big-bang migration without checkpoints
• Abstracting before identifying stable variation
• Claiming performance improvement without measurement