Skip to content
Get packs

Code Refactoring Guide

Guides an agent through safe, test-backed code refactoring based on Fowler's methods

Source Download skill
Repository
luongnv89/claude-howto
Stars
46,401
Licence
MIT
Files
6 files

What it does

When you ask the agent to clean up or restructure code, it follows a phased process: check for tests, identify code smells (signs of poor structure such as long methods or duplicated code), pick named refactorings from Martin Fowler's catalog, and apply small changes one at a time. It asks for your approval at each phase. Optional helper scripts can measure complexity and scan Python, JavaScript or TypeScript files for smells.

Great for

  • Developers with legacy code they want to make more maintainable
  • Teams planning a structured cleanup of technical debt before adding features
  • Anyone who wants refactoring done in small, test-verified steps rather than a big rewrite

Skip it if

  • Projects with no tests and no appetite to write them: the skill itself warns that refactoring without tests is risky, and it can proceed only after you explicitly acknowledge that risk
  • Urgent bug fixes or feature work, since the phased process adds overhead that slows down small changes
  • Non-code documents or languages outside the covered ones, where the bundled analysis scripts will not help

Try asking

  • “Refactor the payment module in this repo to reduce duplicated code, keeping behavior unchanged”
  • “Find the code smells in src/orders.py and propose a prioritized refactoring plan”
  • “Clean up this legacy JavaScript file step by step, starting with low-risk changes”
  • “Measure the complexity of utils/ before and after our refactor”
Step-by-step guide: how to use Code Refactoring GuideInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 original files, the MIT licence and an attribution note.

    refactor.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip refactor.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip refactor.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Ask for tests to be run and passing before any code changes; the skill stops if tests are failing.
  • Point the agent at a specific file or module rather than the whole repo to keep the scope and approval steps manageable.
  • Review the smell report and plan before approving implementation, since the skill expects your sign-off at each phase.

What's inside

  • references/code-smells.md
  • references/refactoring-catalog.md
  • scripts/analyze-complexity.py
  • scripts/detect-smells.py
  • SKILL.md
  • templates/refactoring-plan.md

Redistributed unmodified from luongnv89/claude-howto under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.