agentleFS
Sign inStart free
DevelopersGlobalDevelopersGlobal/ai-agent-skills/skills/refactoring/SKILL.md

refactoring

Skill216 starsChanged 6 months agoMITView on GitHub

Safe, behavior-preserving code transformation backed by tests. Refactor with evidence, not instinct.

We split this skill into the rules it gives an agent

13 rules. 0 are common, 13 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 47 edited versions we read keep these.

  • 13

    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
  1. Distinctive:

    When code is hard to understand or extend

    line 15
  2. Distinctive:

    When duplication makes maintenance risky

    line 16
  3. Distinctive:

    Before adding a feature to a messy area of code

    line 17
  4. Distinctive:

    Never: "while also adding feature X" — refactor separately

    line 18
  5. Distinctive:

    Before touching a single line: ensure there are tests covering the code to be refactored.

    line 24
  6. Distinctive:

    If tests are missing: add characterization tests first.

    line 25
  7. Distinctive:

    Run the tests. They should all pass.

    line 26
  8. Distinctive:

    Run tests after EVERY change — not after 10 changes.

    line 33
  9. Distinctive:

    If tests break: revert immediately and take a smaller step.

    line 34
  10. Distinctive:

    Never batch multiple refactoring changes together.

    line 35
  11. Distinctive:

    Run the full test suite.

    line 51
  12. Distinctive:

    If integration/E2E tests exist: run them too.

    line 52
  13. Distinctive:

    Verify: All tests pass. No observable behavior change.

    line 55

“Common” is measured: kept by at least 6 in 10 of the 47 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Overview

Refactoring changes the internal structure of code without changing its external behavior. The keyword is "without" — if behavior changes, it's not refactoring, it's modification. This skill enforces safe refactoring with tests as the safety net.

When to Use

  • When code is hard to understand or extend
  • When duplication makes maintenance risky
  • Before adding a feature to a messy area of code
  • Never: "while also adding feature X" — refactor separately

Process

Step 1: Establish a Safety Net

  1. Before touching a single line: ensure there are tests covering the code to be refactored.
  2. If tests are missing: add characterization tests first. These capture current behavior, not desired behavior.
  3. Run the tests. They should all pass. This is your baseline.

Verify: Tests pass. They cover the code being refactored.

Step 2: Refactor in Micro-Steps

  1. Make the smallest meaningful change.
  2. Run tests after EVERY change — not after 10 changes.
  3. If tests break: revert immediately and take a smaller step.
  4. Never batch multiple refactoring changes together.

Verify: Tests pass after every individual change.

Step 3: One Thing at a Time

  1. Refactoring types cannot be mixed in one step:
    • Extract method → separate commit
    • Rename → separate commit
    • Move → separate commit
  2. "Refactor and also fix this" is not refactoring — it's two PRs.

Verify: This commit does exactly one type of refactoring.

Step 4: Verify No Behavior Change

  1. Run the full test suite.
  2. If integration/E2E tests exist: run them too.
  3. Compare external API responses before and after (if applicable).

Verify: All tests pass. No observable behavior change.

Common Rationalizations (and Rebuttals)

ExcuseRebuttal
"I'll add tests after refactoring"You can't verify a behavior-preserving refactor without tests before the refactor.
"This change is obviously safe"Obvious safety is how production incidents happen. Run the tests.
"I'll just do a quick cleanup""Quick cleanup" that changes behavior is a bug, not a refactor.

Verification

  • Tests existed before any code was changed
  • Tests run after every individual change
  • Only one type of refactoring per commit
  • Full test suite passes at the end
  • No behavior change observable externally

References

  • test-driven-development skill
  • simplicity-first skill
  • Martin Fowler, "Refactoring"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

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.

Check your setup, free