Refactoring and Optimization with Claude

Key Principle

Refactoring is behavioral preservation: you change how code reads, never what it does. Optimization, by contrast, must be earned — complexity is only justified when it changes asymptotic behavior on a real (not theoretical) bottleneck. As the book puts it, "the smartest optimization is often restraint" (Chapter 5).

Why This Matters

Developers read code far more often than they write it, so clarity compounds. Without a parity check, "refactoring" silently degrades into "rewriting with bugs" (Chapter 5) — a structurally cleaner function that quietly returns different output. The discipline that prevents this is treating identical input/output before and after as a hard invariant, and asking Claude to explain each change so the team can review and learn rather than blindly accept.

Optimization fails the opposite way: reflexive micro-tuning adds obscurity (lambda chains, manual GC management) while buying microseconds in code that never runs hot. The genuine wins are the ones that change Big-O, found by semantic reasoning about the code before reaching for a profiler.

The Three Golden Rules of Clean Refactoring (Chapter 5)

1. Functional parity — output before and after must be identical for the same input.
2. Simplify structure — reduce nesting, duplication, and incidental complexity.
3. Increase clarity — make intent legible to the next reader.

Good Examples

• Parity verification by generated test. After a refactor, have Claude generate a test that asserts original(input) == new(input) across cases, so behavioral preservation is proven, not assumed (Chapter 5).
• Explainable refactoring. Every change is rationalized ("extracted this branch to remove duplication; behavior unchanged") so teammates trust and learn from it rather than rubber-stamping a diff (Chapter 5).
• Asymptotic optimization found by reasoning. if word not in list (O(n²)) becomes a set lookup (O(1)), making the loop ~O(n); repeated DB reads inside a loop become a single batched read; blocking I/O in an async path becomes async; recomputation becomes memoization (Chapter 5).
• System-scale restraint (scraper project). When network waits dominate, bounded concurrency, connection pooling, and backoff matter; microsecond CPU tweaks do not (Chapter 5).

Counterpoints

• Rewriting under the banner of refactoring. Skipping the parity test lets structural changes alter behavior unnoticed (Chapter 5).
• Reflexive micro-optimization. Complicating code before confirming the bottleneck is real rather than merely theoretical; Claude is positioned to flag over-optimization and recommend restraint (Chapter 5).
• Profiling-first instinct. Reaching for a profiler before reasoning about the algorithm misses the asymptotic wins that semantic analysis surfaces directly (Chapter 5).

Simplicity vs. Efficiency

"simplicity favors human efficiency; optimization favors machine efficiency" (Chapter 5). Default to simplicity; spend complexity only where a real hot path justifies it.

The Four Cost Levers (Chapter 5)

Cost discipline is the same clarity-plus-structure discipline as good prompting:

1. Model selection — cheap models for bulk work, expensive ones for critical review.
2. Context discipline — curate, don't dump.
3. Interaction design — batch requests; reuse a compact BASE_SUMMARY anchor instead of resupplying full context.
4. Output control — constrain output ("≤150 words," "return only the final script") and estimate a token budget before spending it.

"Cost control with Claude Code is a product of clarity and structure." (Chapter 5)

Key Quotes

"the smartest optimization is often restraint." — Kilian Voss, Chapter 5

"simplicity favors human efficiency; optimization favors machine efficiency." — Kilian Voss, Chapter 5

"Cost control with Claude Code is a product of clarity and structure." — Kilian Voss, Chapter 5

Rules of Thumb

• Prove parity with a generated original == new test before accepting any refactor.
• Make Claude explain each change; an unexplained refactor is an unreviewable one.
• Optimize only after confirming the bottleneck is real, and prefer changes that move Big-O.
• Reason about the algorithm before profiling.
• Constrain output length and reuse summary anchors to keep cost measurable.

Related References

• Cost and Latency Optimization — Tokens as a Financial Control - the four cost levers in depth
• The Claude Loop - where verification of parity fits the loop
• Core Framework — Partner Not Autocomplete, Mastery Through Understanding - clarity/structure/verification as shared levers