Coding Workflows Workflow Intermediate

AI Code Refactoring Workflow

Restructure code you own without breaking it — change only what's worth changing, and prove with tests and a diff that behavior held.

The problem

Most refactors start with good intentions and end with a subtle behavior change nobody notices until production. The risk isn't the refactor itself — it's doing it with no way to prove the behavior held. There's also the opposite failure: refactoring everything because you can, instead of the few things that actually hurt. This workflow puts a decision step at the front and a proof step at the end, so you change what matters and can show that nothing else moved.

Recommended workflow

Each step uses an existing NewPrompt tool, pre-filled by a matching resource. Open the resource to read it, or jump straight into the tool with the inputs ready.

  1. Decide what's actually worth refactoring

    Run a review focused on smells and complexity, then ignore most of what it finds. Refactor the parts genuinely costing you — the function everyone fears, the duplication that keeps causing bugs — not every nit.

    Goal A short, prioritized list of changes worth making, and permission to skip the rest.

    Resource Code Review Prompt — the Review Contract
    Tool Code Review Prompt Generator
    Open this step in Code Review Prompt Generator

  2. Lock current behavior with tests

    Before changing structure, capture what the code does now in tests. This is the line you refactor against — if these go red, the refactor changed behavior.

    Goal Green tests that describe today's behavior and will catch any drift.

    Resource Regression Test Prompt — Pin It Before You Change It
    Tool Test Case Prompt Generator
    Open this step in Test Case Prompt Generator

  3. Refactor under a no-regression rule

    Make the structural change with behavior preservation as the explicit constraint and the tests as the referee. Small, sequenced moves beat one heroic rewrite.

    Goal Cleaner structure with every behavior test still green.

    Resource Safe Refactoring Prompt — Zero Regression Tolerance
    Tool Refactor Prompt Builder
    Open this step in Refactor Prompt Builder

  4. Prove only the structure changed

    Diff the relevant output or behavior before and after — same inputs, same results. The diff is your evidence that the refactor was behavior-preserving, not just hopefully so.

    Goal A clean before/after comparison showing behavior is unchanged.

    Resource Compare Two Generated Drafts
    Tool AI Text Diff Checker
    Open this step in AI Text Diff Checker

Expected outcome

The code is cleaner where it mattered, every behavior test is still green, and you hold a before/after diff proving the change was behavior-preserving. The refactor is safe to merge on evidence, not faith.

Best for

  • Cleaning up code you own and understand
  • Reducing complexity in a function that keeps causing bugs
  • Removing duplication without changing behavior

Not for

  • Code you don't yet understand — start with the AI Legacy Code Modernization Workflow
  • Fixing a bug — that's the AI Debugging Workflow; a refactor shouldn't change behavior

FAQ

How is this different from the Legacy Modernization Workflow?

This one assumes you already understand the code and own it. Legacy modernization starts with code you don't understand, so it adds an explicit understanding step and characterization tests before any change. Same care, different starting point.

Why diff at the end if the tests are green?

Tests cover what you thought to test. The diff is a second, cheap check on the actual output for the same inputs — it catches behavior the tests missed. Belt and suspenders for a behavior-preserving change.

Isn't refactoring just one prompt?

The refactor itself can be one prompt. Doing it safely is the workflow — deciding what's worth changing, pinning behavior first, and proving nothing else moved.

Tip: Each step's resource opens its tool pre-filled — start at step one and carry the output forward.

All playbooks