Lesson 2.4 — Multi-File Simultaneous Refactor: Renames Across a Codebase

Lesson 2.4 — Multi-File Simultaneous Refactor: Renames Across a Codebase

THE NAIVE APPROACH TRAP

When a developer used to Claude.ai chat needs to rename PaymentProcessor
to TransactionHandler across a 40-file Python codebase, the instinct is
to open the IDE's find-and-replace, swap the string, and commit. When that
produces an AttributeError from a logging.getLogger("PaymentProcessor")
call that wasn't a class reference, they pivot to pasting files into
Claude.ai one at a time — copy file, ask Claude to rename, paste back, repeat.

This fails at team scale for three concrete reasons. First, IDE
find-and-replace doesn't distinguish between the class name, a docstring
that explains the class, a pytest.mark.parametrize string fixture, and a
TYPE_CHECKING-block string annotation — each requiring different rename
semantics. Second, the developer misses at least one file (typically a
serializer or migration that references the name as a string literal).
Third, the process is unreproducible: when a reviewer asks "how did you
verify completeness?", there is no defensible answer.

Claude Code solves this by holding all affected files in one shared context
window, generating diffs for every file in a single pass, and writing each
accepted diff to disk before the session ends.

THE FAILURE MODE

The specific Claude Code failure for this lesson: **silent context overflow
from naive glob loading**.

A developer who absorbed Lesson 2.3's glob patterns writes:

On a 60-file codebase this adds ~18,000 tokens — fine. On a 200-file
codebase it adds 70,000–120,000 tokens. Still within the 200k session
limit — until you add the model's output, Claude's internal scratchpad,
and the diff for every file. The session quietly degrades: Claude drops
earlier-loaded files from its effective attention window **without any
warning in the CLI**. It renames the files it still "sees" and silently
skips the rest.

The second failure is non-atomic writes. Claude Code writes each
accepted diff to disk immediately. Accept file A, accept file B, abort
before file C is written: your codebase has TransactionHandler in A and
B but PaymentProcessor in C — and C imports from A. The import fails at
runtime. There is no automatic rollback.

A third failure specific to this lesson: if ANTHROPIC_API_KEY is set in
your shell (leftover from Module 8 testing), it silently overrides Pro
subscription billing for the entire Claude Code session. Every /add
draws from API credits at per-token rates. Check before starting:

THE CLAUDEFORGE ARCHITECTURE

Lesson 2.4 sits at the junction of Lesson 2.3 (glob patterns, which taught
deliberate context loading) and Lesson 3.1 (headless --print mode, which
will automate what you do manually here). It is the bridge lesson: you
execute the refactor interactively so you understand the state transitions
the headless script in 3.1 will manage programmatically.

Files this lesson introduces:

CLI primitives introduced or deepened:

• /add <path> — loads a specific file into context; used deliberately rather than via glob

• /status — reports Context: N / 200,000 tokens; your gate before each /add batch

• --allowedTools Edit — restricts Claude to file edits only; prevents accidental shell execution during the rename session

• The diff loop — Claude proposes; you accept y or reject n per file; accepted diffs write immediately

This lesson feeds forward into Lesson 3.3 (batch type-hint adder), which
automates this exact pattern — one Claude Code call per file, driven by a
bash loop with a state file tracking which files have been processed.

IMPLEMENTATION DEEP DIVE

Token budgeting with /status:
Each invocation returns Context: 12,847 / 200,000 tokens. The practical
ceiling for a rename session is 60% of the limit (~120,000 tokens): Claude
needs headroom to generate diffs for all loaded files simultaneously.
token_budget.py uses a conservative 3.5-chars-per-token estimate to
scan files before you open the session, letting you predetermine load order
and batch boundaries.

Rename prompt structure — specificity matters: