Skip to content
Skills Library
Programming · Building & coding

safe-refactoring-engineering

/safe-refactoring-engineering

Engineering practice: Safe refactoring — Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it.

Licence
Apache-2.0
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Engineering practice: Safe refactoring — Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it.

Original author description

Engineering practice: Safe refactoring — Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it.

How it works

  1. How to do it
  2. Checklist
  3. Rules
  4. Do
  5. Don't
  6. Quality gates
  7. Workflow
  8. Further reading
Original SKILL.md headings · 60 lines, 678 words
SKILL.md preview
---
name: safe-refactoring-engineering
description: "Engineering practice: Safe refactoring — Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it."
type: engineering
stack: practice
core: "1.0"
checked: 2026-10-26
---

# Safe refactoring

Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs.

Use this before adding a feature to code that resists change, or when cleaning up duplication, long functions or tangled modules. Keeping every step behaviour-preserving and tested prevents the big-bang rewrite that breaks things nobody knew depended on the old shape.

## How to do it
1. **Name the goal** — Write one sentence on the structure you want and why, for example 'move pricing rules out of the controller so the new tax rule has one home'.
2. **Secure a safety net** — Run the tests that cover the code. If coverage is thin, add characterisation tests that pin current behaviour, including odd behaviour, before changing anything.
3. **Separate refactoring from behaviour change** — Do the refactor on its own branch or in its own commits. Feature or bug-fix changes come after, in separate commits.
4. **Take one small step** — Apply one named move: rename, extract function, inline, move module, introduce parameter. Prefer the editor's automated refactorings where they exist.
5. **Run tests after every step** — Run the relevant tests and the type checker. If anything fails, undo the step rather than debugging forward.
6. **Commit each green step** — Commit after each working step with a message naming the move. Small commits make bisecting and review simple.
7. **Keep public interfaces stable** — When a widely used function or API must change, add the new form, migrate callers, then remove the old form in a later step.
8. **Review the diff as pure structure** — Before the pull request, read the diff and confirm no logic, output or test expectation changed. Note any deliberate exception.

## Checklist
- [ ] Tests covering the touched code passed before and after the refactor
- [ ] No test expectations were changed except renames that follow the code
- [ ] Refactoring commits contain no feature or bug-fix changes
- [ ] Each commit builds and passes tests on its own
- [ ] Old interfaces kept during migration are marked deprecated with a removal plan
- [ ] Type checker and linter report no new errors

## Rules
- Never refactor code that has no tests covering it; add characterisation tests first. _(Without a safety net you cannot tell a refactor from a rewrite.)_
- Keep each refactoring pull request focused on one structural goal. _(Reviewers can verify behaviour is unchanged only when the diff has one purpose.)_
- Benchmark before and after when refactoring a hot path. _(Cleaner code can still be slower, and that is a behaviour change users notice.)_
- Preserve error types, messages and status codes callers rely on. _(Callers often branch on errors, so changing them breaks contracts silently.)_

## Do
- Use automated rename and extract tools to avoid manual slips
- Leave the code slightly better each time you touch it, in small moves
- Stop and ship when the goal is met rather than polishing further

## Don't
- Do not mix a refactor and a behaviour change in the same commit
- Do not push through a red test by changing its expectation
- Do not rewrite a module from scratch when a sequence of small moves will do

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Behaviour unchanged | Full test suite + snapshot or contract tests | All pass with no changed expectations | Every refactoring pull request |

## Workflow
**Review**
- Confirm the diff changes structure only; ask for any logic change to be split out

**Definition of done**
- Stated structural goal met with all tests green and no changed expectations

## Further reading
- [Refactoring](https://refactoring.com/) — The catalogue of named refactorings to use as small, safe steps.
- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) — Engineering skills for coding agents, including code-simplification and cleanup workflows.
- [mattpocock/skills](https://github.com/mattpocock/skills) — Agent skills that pair test-first work with improving code structure.

_Written for Celestial; the sources above inspired it._
Files in this package (4)
  • AGENTS.md 3 KB
  • README.md 2 KB
  • SKILL.md 4 KB
  • rules/safe-refactoring-engineering.mdc 3 KB

Versions

The database has no other skills named safe-refactoring-engineering.

Database snapshot: 13.11.2026 · package version 23e57a23fe4f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100test-first-development-engineering
    Engineering practice: Test-first development — Write a failing test for one small behaviour, make it pass with the least code, then tidy up, so every line you ship is already proven. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it.
  • 100task-breakdown-engineering
    Engineering practice: Task breakdown — Turn a spec into small, ordered tasks that each have acceptance criteria and a check that proves them done, so work can be reviewed, handed to an agent and finished one piece at a time. Use in any language or framework whenever this…
  • 90guiding-refactoring-with-code-health
    Use when refactoring unhealthy code and needing Code Health findings to choose small safe steps and verify improvement.
  • 100safe-refactor
    Restructures code without changing its behavior by first pinning behavior with characterization tests and then applying small, individually verified refactoring steps. Use when the user asks to refactor, clean up, simplify, modernize, split a large file or function, or pay down tech debt.
  • 100refactoring-specialist
    Plans and performs behaviour-preserving refactoring in small, test-protected steps, starting with characterisation tests for untested code. Use when improving structure without changing behaviour.
  • 100refactoring-specialist
    Plans and performs behaviour-preserving refactoring in small, test-protected steps, starting with characterisation tests for untested code. Use when improving structure without changing behaviour.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.