# Refactor

> Use when existing code needs restructuring without behavior change — large functions, code smells, hard-to-maintain structure, or a multi-file refactor plan with tests.

- Skill: `vathymut/refactor` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add vathymut/refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vathymut/refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: vathymut (https://skillmd.com/u/vathymut)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/vathymut/refactor

---


# Refactor

Improve code structure without changing external behavior. The default path:
change structure in small steps, always with tests.

**Not for:** rewrites from scratch, or code without tests. For architectural
deepening (module interfaces, seams, testability), fold that work into the
restructure itself rather than handing off to a separate skill. Scope
discipline (how small is small enough) is a separate concern — this skill
reshapes *structure*, it does not shrink *scope*.

## When to use

- Code is hard to understand or maintain.
- Functions/classes are too large.
- Adding features is difficult due to code structure.
- The user asks for a refactor plan.

## Vocabulary: key terms

- **Deep module** — lots of behaviour behind a small interface.
- **Interface** — everything a caller must know to use a module correctly: type signature, invariants, ordering, error modes, config, performance.
- **Seam** (Feathers) — where a module's interface lives; the place you can alter behaviour without editing in place.
- **Adapter** — a concrete thing that satisfies an interface at a seam.
- **Depth** — leverage at the interface; the deletion test tells you if a module earned its keep.

For deepening clusters or exploring alternatives, see `references/DEEPENING.md` and `references/DESIGN-IT-TWICE.md`.

## Local refactor

1. **Prepare** — Write or confirm tests. Commit working state. Identify the code smell.

2. **Refactor in small steps** — One change, run tests, commit if they pass. Repeat. Never mix refactoring with feature changes.

3. **Verify** — Run full test suite and type checker. Confirm no behavioral changes.

4. **Clean up** — Update comments and docs. Remove temporary markers.

## Multi-file refactor

Adds a written plan step before the local refactor steps above:

0. **Write plan** — Read the code. Identify affected files, dependencies, and hidden coupling. Sequence changes: contracts/types first, then implementations, callers, tests, cleanup. Include verification between phases and rollback for risky phases. Use `references/refactor-plan-template.md`. Confirm with user before implementing.

Then follow Local refactor steps 1-4.

## When NOT to use

- Greenfield feature work — use `test-driven-development` + `ponytail` (scope discipline lives there; this skill only reshapes structure).
- Production code without tests — add tests first (use `test-driven-development`), then refactor.
- Rewrites from scratch.

## Constraints

- **Behavior is preserved** — refactoring changes structure, not behavior.
- **Tests are mandatory** — without tests, you're editing, not refactoring.
- **One change at a time** — don't bundle refactoring with feature work.
- **Small steps** — if a step feels large, split it further.

### When not to refactor

Code that works and won't change again, or production code without tests (add tests first).

## Completion criteria

- [ ] Code smell named and scoped to local or multi-file plan
- [ ] Tests present and green before first structural edit
- [ ] Each step is one edit → tests green → commit
- [ ] Full test suite + type checker green, behavior unchanged

## Related skills

- `ponytail` — scope: smallest slice; this skill: best structure for that slice.
- `test-driven-development` — mandatory failing-test-first when adding behavior after refactor.
- `systematic-debugging` — fix root cause before reshaping.