refactoring
Restructure, rename, split, merge or simplify code while preserving its behavior. Use when improving code structure or enforcing a boundary without changing what users observe; use feature-development when behavior changes.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- refactoring
- description
- Restructure, rename, split, merge or simplify code while preserving its behavior. Use when improving code structure or enforcing a boundary without changing what users observe; use feature-development when behavior changes.
03 SKILL.md 正文
<!-- Generated by Paved plugin paved@2.29.0 from core.development.refactoring@0.2.1; edit Paved Core instead. -->
Refactoring
When to use
In the refactor workflow, or when a feature or fix needs the code reshaped first. If
behavior must change too, finish the refactoring, verify it, then change behavior with
feature-development: never both in one step.
Required context
The code to restructure and the tests that cover it. Useful: architecture context for the target structure, and the rules in scope.
Preconditions
- The behavior to preserve is covered by tests that pass now. If coverage is missing,
first add characterization tests that pin the current behavior, including behavior
that looks wrong. Use
unit-testingfor them, orintegration-testingwhen the behavior only shows across a boundary. - The target structure is stated: what moves where, and why.
Procedure
- Record the baseline: run the covering tests and keep the result.
- Pick the smallest step toward the target: one rename, one extraction, one move.
- Apply it without changing any observable result: return values, errors, side effects, ordering, logging that others rely on, public interfaces.
- Run the covering tests. On failure, undo the step rather than repair forward.
- Repeat until the target structure is reached.
- Remove what is now dead: old entry points, forwarding shims nobody calls, duplicate helpers. Search for every reference first, including names in strings, configuration and documentation.
- Compare with the baseline: the same tests pass with the same results; no test was changed to make it pass, except for mechanical renames.
For a Paved workflow, save the reviewed refactoring plan at
.paved/documents/plans/<run-id>.md. Keep any structural task breakdown under
.paved/documents/tasks/<run-id>.md, using the same workflow run id.
Tools
None beyond the verification profile. Search the code for references before removing anything.
Rules
core.architecture.follow-existing-patterns: the target structure is one the repository
already uses. core.architecture.respect-declared-boundaries: a refactor must not
introduce a dependency the boundaries forbid, even temporarily.
Verification
Required: unit. Recommended: integration for code with external collaborators,
architecture when modules or dependencies move, static-analysis and build.
Evidence
The baseline and final check results, and the diff.
Completion criteria
- The covering tests pass, unchanged except for mechanical renames.
- Public interfaces are unchanged, or every caller was updated and the change recorded.
- No dead code remains from the old structure.
Failure modes
| Failure | Signal | Response |
|---|---|---|
| Hidden behavior change | A test assertion had to change | Undo; split out the behavior change |
| Big-bang step | Many files change before tests run | Undo to the last green step; take smaller steps |
| Refactoring without a net | No test fails when the code is broken on purpose | Add characterization tests first |
| Orphaned references | A name survives in configuration or strings | Search again; update or remove them |
References
None.
Paved integration
Use the project-local Paved contract as the source of truth. Discover state with node "<plugin root>/scripts/paved.mjs" status --json, load only relevant .paved/project/ context, and invoke verification with node "<plugin root>/scripts/paved.mjs" verify --json. <plugin root> is the installed Paved plugin directory, two directories above this SKILL.md. Always run the launcher from the repository being worked on, never from the plugin directory. Do not edit generated integration files or bypass Paved lifecycle and ownership checks.
04 同仓库更多 Skills
sample-skill
Does a sample task. Use when a sample is needed.
unexplained-contract
Does a sample task. Use when a sample is needed.
shell-block
Does a sample task. Use when a sample is needed.
project-identifier
Does a sample task. Use when a sample is needed.
oversized
Does a sample task. Use when a sample is needed.
no-activation
Does a sample task.