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

<p>In Episode 12 of <strong>Beyond Prompting</strong>, 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 &quot;modernize this module&quot; in one giant prompt usually results in hundreds of changed lines, broken production, and hours spent untangling regressions. In this episode, we cover:</p><ul><ul><li><strong>The &quot;Big-Bang&quot; Trap:</strong> 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.</li></ul><ul><li><strong>Characterization Tests First:</strong> How to lock down the current behavior of legacy code by generating tests <em>before</em> refactoring, creating a behavioral safety net when no specification exists.</li></ul><ul><li><strong>The 4-Step Refactoring Loop:</strong> 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.</li></ul><ul><li><strong>Reviewing Agent Diffs:</strong> 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.</li></ul><ul><li><strong>Checkpoint Rewinds:</strong> Using Esc Esc or /rewind to instantly restore conversation and file state to an earlier checkpoint when an exploration fails.</li></ul></ul><p><em>(Note for listeners: This episode covers Chapter 12 of Sho Shimoda&#39;s book </em><a href="https://www.amazon.com/dp/B0HJKBWKVQ" target="_blank" rel="noopener noreferer"><strong>RUNNING CLAUDE: The Operator’s Guide to Chat, Cowork and Claude Code</strong></a><em>, available on Amazon as the successor book to </em><strong>Master Claude: Chat, Cowork and Code</strong><em>).</em></p>