110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
---
|
||
name: bulk-refactor-workflow
|
||
description: Use when renaming symbols, migrating APIs, or applying safe mechanical changes across many files in the repository.
|
||
---
|
||
|
||
# Bulk Refactor Workflow（批量重构 / 大范围修改）
|
||
|
||
## Overview
|
||
|
||
Guide repository-wide mechanical edits without losing scope control or damaging
|
||
unrelated work. Core principle: enumerate first, transform mechanically, verify
|
||
in loops, and keep every batch auditable.
|
||
|
||
## When to Use
|
||
|
||
- Rename APIs, symbols, file conventions, or repeated string patterns
|
||
- Apply scripted or structural edits across many files
|
||
- Migrate callers to a new interface where the change pattern is repeatable
|
||
|
||
## When Not to Use
|
||
|
||
- One-off logic changes where no repeatable transformation exists
|
||
- Exploratory redesign or feature work that needs new architecture decisions
|
||
- Cleanup that is only formatting/lint alignment; use `style-cleanup` directly
|
||
|
||
## Inputs
|
||
|
||
- Scope: directories, file types, include/exclude rules
|
||
- Transformation: rename, replace, codemod, scripted edit, migration strategy
|
||
- Constraints: behavior-preserving vs. compatibility window vs. staged rollout
|
||
- Verification commands: smallest useful loop plus final gate
|
||
|
||
## Procedure
|
||
|
||
1. **Baseline and bound the scope**
|
||
|
||
- Record `git status --short`.
|
||
- Dirty worktrees are allowed.
|
||
- Do not revert unrelated changes.
|
||
- Mark the exact target file set before editing.
|
||
- Run a baseline verification command so existing failures are not misattributed
|
||
to the refactor.
|
||
|
||
2. **Enumerate every intended hit**
|
||
|
||
- Search before editing with `rg`, `git grep`, or a structured query.
|
||
- Separate real code hits from comments, docs, generated files, and samples.
|
||
- Write down exclusions before running the transformation.
|
||
|
||
3. **Choose the safest mechanical transform**
|
||
|
||
- Prefer deterministic transforms: codemods, scripts, structured edits, or
|
||
narrow search/replace with explicit scope.
|
||
- If compatibility matters, use a staged migration: adapt providers first,
|
||
migrate callers second, remove compatibility layer last.
|
||
|
||
4. **Apply in bounded batches**
|
||
|
||
- First, apply the transformation in bounded batches.
|
||
- Verify each batch before widening scope.
|
||
- Stop immediately if output differs from the expected hit class.
|
||
|
||
5. **Verify in loops**
|
||
|
||
- Run the smallest relevant verification after each batch.
|
||
- Re-check the hit list after edits to confirm the intended pattern is gone and
|
||
unintended patterns were not introduced.
|
||
|
||
6. **Finish with targeted cleanup**
|
||
|
||
- If the mechanical change leaves formatting or lint fallout, Use `style-cleanup` for the final formatting/lint pass.
|
||
- Keep that cleanup scoped to the refactor set unless the user approves a wider
|
||
pass.
|
||
|
||
7. **Report**
|
||
|
||
- Summarize files touched, transform rules used, verification evidence, and any
|
||
residual risk.
|
||
|
||
## Output Contract
|
||
|
||
- `Scope:` files, directories, and exclusions actually used
|
||
- `Transformation:` exact rule or script applied
|
||
- `Batches:` how the work was partitioned
|
||
- `Verification:` commands, exit status, and what each loop proved
|
||
- `Risks:` remaining ambiguous areas, compatibility debt, or deferred cleanup
|
||
|
||
## Success Criteria
|
||
|
||
- Every changed file belongs to the declared scope
|
||
- The transformation is reproducible and explainable
|
||
- Verification passes at both batch level and final gate
|
||
- Unrelated work in the repository is preserved
|
||
|
||
## Failure Handling
|
||
|
||
- If the hit list is ambiguous, stop and refine scope before editing
|
||
- If the transform cannot be expressed mechanically, downgrade to a normal
|
||
refactor plan instead of pretending it is safe bulk work
|
||
- If verification fails mid-batch, stop, inspect the smallest failing delta, and
|
||
correct the transform before continuing
|
||
- If compatibility risk is higher than expected, split the migration into staged
|
||
commits or phases
|
||
|
||
## Guardrails
|
||
|
||
- Never run repository-wide replacement without an explicit hit review
|
||
- Never mix unrelated cleanup into the same batch
|
||
- Never hide a large-scope behavior change behind the label "mechanical refactor"
|