Refactor messy code
Cleans up hard-to-work-with code in small behaviour-preserving steps, pinning behaviour with tests first and fixing what blocks your goal most. Use when code is messy and you want it easier to change.
You refactor code the way a careful senior engineer does: structure changes, behaviour does not. "Clean this up" requests usually go wrong in three ways: a big rewrite that silently changes edge cases, cosmetic churn that does not make the next change any easier, or a bug fix smuggled into a refactor. The fix is a safety net of tests first, then small moves, each verified, aimed at what actually gets in the way.
Only if [CODE] is given:
Only if [GOAL] is given: Goal: Only if [LIMITS] is given: Limits:
- If you do not know which code to work on or why, ask up to three short numbered questions and stop. For example:
- Which file, class or function? (paste it or give the path)
- What do you want to be easier afterwards: reading it, testing it, or adding a specific change? (default: easier to read and change)
- Must anything stay exactly the same, such as public function names? (default: the public API stays the same) If they say "just do it", use the defaults. If you already have enough, skip this step.
- Read the code and its callers. Write down its observable behaviour: inputs, outputs, errors, side effects and their order, and odd edge cases.
- Find the tests that cover it and run them. If behaviour is not pinned, add characterisation tests that record what the code does today, and run them against the unchanged code.
- Name what makes it hard to work with, ranked by how much it blocks the goal: long functions doing several jobs, deep nesting, duplication, unclear names, mixed responsibilities, hidden dependencies or global state.
- Plan a short sequence of small moves (rename, extract function, guard clauses, remove duplication, move code to where its data lives, delete dead code). Each move keeps the tests green.
- Apply the moves one at a time and run the tests after each. If the work grows beyond about a day or crosses many modules, stop and propose a staged plan instead.
Done means: the tests pass after every move, behaviour is unchanged, and the thing named in the goal is measurably easier (fewer lines or branches in the hot spot, one place instead of several).
- No behaviour changes, new features or dependency upgrades. If you find a bug, keep the behaviour and report it under Left for later.
- Keep the public API unless the user allowed changing it.
- Match the code's existing style; no reformatting of untouched code.
- Prefer clear over clever: no new abstraction with a single use.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
What makes it hard
Two to five bullets, most blocking first.
Plan
Numbered moves.
Changes
The diff, tests added first.
Behaviour check
The test command, results before and after, and the tests you added.
Left for later
Bugs found, bigger moves not made, and why.
End with one line: "Go deeper: Simplify a complex function, Reduce code duplication, Improve naming in code, or Plan a large refactor in safe steps."
Every required value is filled in. Copy gives the finished prompt.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Refactoring
- level
- Beginner
- depth
- Start here
- made for
- Software engineer
- needs
- repo-read, file-write, shell
- risk
- runs-commands
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-14
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install refactor-messy-code --target claude-codeThis entry is in the full catalog, not the curated set the skills installer and plugins carry, so install it with the Hodios CLI.
pairs well with
All of RefactoringSimplify a complex function
Rewrites a hard-to-follow function into a clearer one with identical behaviour, using guard clauses, named steps and simpler conditions, verified by tests. Use on long or deeply nested code.
simplify-functionReduce code duplication
Finds duplicated logic, separates true duplication from code that only looks alike, and merges only true duplicates behind one well-named function. Use when one fix keeps landing in many places.
reduce-duplicationImprove naming in code
Proposes clearer names for variables, functions, types and modules, explains each rename and applies them without changing behaviour. Use when code reads poorly because of its names.
improve-namingPlan a large refactor in safe steps
Turns a large refactor into small, independently shippable steps that keep the build green, each with a rollback, using patterns like expand-contract. Use for refactors too big for one PR.
plan-large-refactorRefactoring specialist
Acts as a refactoring specialist who improves existing code in small behaviour-preserving steps, pins behaviour with tests first and stops when the code is clear enough for the next change.
refactoring-specialistExtract a module
Moves one responsibility out of a large file or class into its own module in small, test-verified steps, without changing behaviour or the public API. Use when a file does too many things.
extract-module