refactor-codebase

What our test produced

How it works

1. 1

   One question for every piece of code

   Should these pieces change together? The skill names three ways code gets that wrong: hidden links (copied logic, modules reading state another module sets), needless links (callers reaching into internals, parameters only one caller understands) and surplus (pass-through wrappers, config for things that never vary, dead code).

2. 2

   List everything before changing anything

   It writes every problem and every special case (an if for one value, a swallowed exception, a retry or sleep, a disabled test) into a file. Subagents run the specialist hunts from the same pack: find-state-machines, find-overengineering and ratchet-files.

3. 3

   Redesign, then land one fix at a time

   Each fix is one mechanism written above the problems it removes, and lands as one commit with the project's checks passing, following refactor-change and code-review. Behaviour changes go in the commit message. Fresh subagents then search again, and the run closes with audit-tests over the suites it touched.

4. 4

   You start it; it does not start itself

   The skill sets disable-model-invocation, so the agent never loads it on its own. You type /refactor-codebase, optionally naming an area to start with.

Try it

1. 1
   Install the pack

   npx skills add dzhng/skills

   Copy

   Installs through the Skills CLI for Claude Code, Codex, Cursor, opencode and other agents. Add --list to pick skills; refactor-codebase calls find-state-machines, find-overengineering, ratchet-files, refactor-change, code-review and audit-tests, so keep those too.

2. 2
   Run it

   /refactor-codebase

   Copy

   In a clean git branch with your tests passing. Add an area after the command to start there, e.g. /refactor-codebase the billing module.

Key facts

Author

David Zhang (dzhng)

Licence

MIT

Version checked

Not stated

Works with

Claude Code, Codex, opencode, Cursor, duet and other agents that load skills; tested in Claude Code

Language

English; works with any programming language

What it produces

A refactored codebase landed as one commit per fix, with behaviour changes named in each commit message and an audited test suite

Install

Run npx skills add dzhng/skills (add --list to pick skills, keeping the six review skills refactor-codebase links to), then type /refactor-codebase

From the skill’s own repository. “Not stated” means the repository does not say.

Our test

Our test: we wrote a 419-line TypeScript invoicing CLI with the kind of debt AI-written code piles up (pricing logic copied four times, three status flags, a global state object, a one-plugin plugin system, swallowed errors and a skipped test) and typed /refactor-codebase in Claude Code with Claude Fable 5.2. The skill had subagents hunt for implicit state machines and overengineering, wrote a list of fixes with the problems each one removes, then landed them one commit at a time, re-audited with fresh subagents, and finished by auditing the tests. It ended with 377 lines, 15 passing tests instead of 9 plus a skipped one, and every behaviour change named in its commit message. Three of the problems it fixed were real bugs, two of which we had not planted on purpose. refactor-codebase is one skill in David Zhang's dzhng/skills, an MIT-licensed pack of plan, implement and review skills for Claude Code, Codex and other agents; the author says Claude Fable 5.2 distilled it from his own session history.

Give invoices one status field instead of three flags

isSent/isPaid/isCancelled allowed combinations that mean nothing, and
the status function, the report and the CSV export each derived the
real state their own way. An invoice now has status draft, sent, paid
or cancelled, changed only by the transitions in invoiceService.

Behavior changes:
- A cancelled invoice can no longer be paid ("Invoice is cancelled").
  Before, send, cancel, pay left it listed as cancelled but counted in
  the report's Paid total.
- data.json stores "status" in place of the three flags. Files in the
  old format are upgraded when read (storage.ts withStatus); an invoice
  that was both paid and cancelled becomes cancelled.

const TAX_RATE = 0.1;

// Negotiated discounts, taken off the subtotal before tax.
const DISCOUNT_BY_CUSTOMER = new Map([["acme", 0.05]]);

export function billableTotal({ customerId, lines }) {
  const subtotal = lines.reduce((sum, l) => sum + l.amount, 0)
    * (1 - (DISCOUNT_BY_CUSTOMER.get(customerId) ?? 0));
  return round(subtotal + subtotal * TAX_RATE);
}

Not handled (new behaviour, not a refactor):
- A customer id can be an empty string.
- An amount like 0.001 that rounds to 0 creates a $0 invoice.
- A hand-edited data.json missing the "quotes" key fails with a
  TypeError that doesn't name the file.

FAQ

Repository

1. github.comgithub.com/dzhng/skills ↗