12. Safe Refactoring of Legacy Code (Characterize, Change, Verify)

In Episode 12 of Beyond Prompting, we tackle one of the most high-stakes tasks in software engineering: letting an AI agent refactor an existing codebase. Author Sho Shimoda breaks down why asking Claude to "modernize this module" in one giant prompt usually results in hundreds of changed lines, broken production, and hours spent untangling regressions. In this episode, we cover:

• • The "Big-Bang" Trap: Why a single commit touching twelve files leaves you with twelve suspects when tests go red, and why working in small, single-purpose steps makes debugging instant.
  • Characterization Tests First: How to lock down the current behavior of legacy code by generating tests before refactoring, creating a behavioral safety net when no specification exists.
  • The 4-Step Refactoring Loop: Forcing Claude into a disciplined cycle—list distinct changes smallest first, execute one change, verify against characterization tests, and commit before moving to the next.
  • Reviewing Agent Diffs: How to review AI-generated code for subtle failure modes (like changed return contracts or deleted code paths) and using /code-review as a mechanical first pass.
  • Checkpoint Rewinds: Using Esc Esc or /rewind to instantly restore conversation and file state to an earlier checkpoint when an exploration fails.

(Note for listeners: This episode covers Chapter 12 of Sho Shimoda's book RUNNING CLAUDE: The Operator’s Guide to Chat, Cowork and Claude Code, available on Amazon as the successor book to Master Claude: Chat, Cowork and Code).