safe-refactoring
Skill2 starsChanged 6 months agoMITView on GitHub
Restructure code without changing behavior, verified by tests at every step.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- yuchi-chang/no-capetheir own version, first seen Oct 8, 2026
- caiaffa/claude-code-ultimate-engineering-systemtheir own version, first seen Sep 14, 2026
- codecharmhq/claude-code-skillstheir own version, first seen May 17, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- caiaffa/claude-code-ultimate-engineering-system★ 17same name
- yuchi-chang/no-cape★ 2same name
- codecharmhq/claude-code-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- codebase-navigationSkill
- context-window-managementSkill
- dependency-assessmentSkill
- error-interpretationSkill
- human-escalationSkill
- incremental-verificationSkill
- multi-agent-collaborationSkill
- production-awarenessSkill
- requirement-extractionSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 9 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Not every piece of ugly code needs attention right now.
- Distinctive: line 40
If no tests exist and writing them is impractical, add at minimum a characterization test: call the function with known inputs and assert …
- Distinctive: line 60
After each move, run:
- Distinctive: line 66
If the project has snapshot tests, expect them to remain identical.
- Distinctive: line 70
Never combine a refactoring commit with a feature or bug-fix commit.
- Distinctive: line 71
Never refactor code that lacks test coverage without adding coverage first.
- Distinctive: line 72
Never perform more than one named refactoring move per commit.
- Distinctive: line 73
Always run the test suite after every individual move, not just at the end.
- Distinctive: line 74
If tests fail after a move, revert the move immediately rather than attempting to fix forward.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Safe Refactoring
What This Skill Enables
Agents with this skill can improve code structure -- readability, modularity, performance -- while guaranteeing that external behavior stays identical. Without it, agents tend to rewrite large sections at once, introduce subtle regressions, and produce diffs that are impossible for humans to review confidently. Safe refactoring turns a risky "big bang" rewrite into a chain of small, provably correct transformations.
Core Competencies
1. Decide Whether to Refactor at All
Not every piece of ugly code needs attention right now. Before touching anything, answer these questions:
| Question | If "No", stop here |
| Is this code on the path of the current task? | Do not refactor drive-by style. |
| Do passing tests already cover the behavior? | Write tests first (see competency 2). |
| Is the improvement worth the review cost? | A rename across 200 files is noisy for little gain. |
| Is there a deadline within hours? | Ship first, refactor in a follow-up branch. |
Refactoring that is not motivated by a concrete upcoming change is speculative. Avoid it.
2. Lock Behavior with Tests Before Changing Structure
The "lock then change" pattern is non-negotiable:
Step 1 -- Write or confirm tests that cover the code you are about to move.
Step 2 -- Run the full relevant test suite. It must pass.
Step 3 -- Perform ONE refactoring move (see competency 3).
Step 4 -- Run the suite again. It must still pass.
Step 5 -- Commit with a single-purpose message.
Step 6 -- Repeat from Step 3 for the next move.If no tests exist and writing them is impractical, add at minimum a characterization test: call the function with known inputs and assert on the current outputs, even if those outputs look wrong. The point is to detect change, not to validate correctness.
3. Use Named Refactoring Moves
Each commit should contain exactly one kind of transformation. Mixing moves makes regressions hard to bisect.
| Move | When to Use | Key Risk |
| Extract Function | A block inside a function has a clear name and purpose. | Getting the parameter list wrong; forgetting closures. |
| Inline Function | A wrapper adds no clarity and just indirects. | Callers may depend on the wrapper's name in tests or logs. |
| Rename | A name is misleading or does not match domain language. | Must update every reference, including strings and config. |
| Move to Module | A function lives in the wrong file or layer. | Import paths change; circular dependencies may surface. |
| Simplify Conditional | Nested if/else can be replaced with guard clauses or a lookup table. | Subtle short-circuit logic may be intentional. |
4. Keep Commits Single-Purpose
A refactoring commit must never include behavioral changes. If you realize a bug while refactoring, stash the refactoring work, fix the bug in its own commit with its own test, then resume. This keeps git bisect useful and code review fast.
5. Verify No Behavioral Change
After each move, run:
- The unit tests covering the changed code.
- Any integration tests that exercise the changed module.
- A type check or linter pass if the language supports it.
If the project has snapshot tests, expect them to remain identical. If a snapshot changes, the refactoring altered behavior -- revert and investigate.
Behavioral Rules
- Never combine a refactoring commit with a feature or bug-fix commit.
- Never refactor code that lacks test coverage without adding coverage first.
- Never perform more than one named refactoring move per commit.
- Always run the test suite after every individual move, not just at the end.
- If tests fail after a move, revert the move immediately rather than attempting to fix forward.
Failure Modes
| Failure | Symptom | Correction |
| Big-bang rewrite | Single commit touches dozens of files with mixed intent. | Break into one-move-per-commit sequence. |
| Refactoring without tests | "It looks the same" is offered instead of proof. | Write characterization tests before starting. |
| Drive-by refactoring | Unrelated files are cleaned up while working on a feature. | Limit scope to files on the current task's path. |
| Rename avalanche | A rename propagates across the entire codebase. | Assess review cost first; use IDE tooling; split across commits. |
| Fix smuggled in refactor | A bug fix hides inside a "refactoring" commit. | Separate the fix into its own commit with its own test. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.