Key Principle
Claude can process many tokens "but not your entire project at once." The whole discipline of large-project work is simulating full-repo understanding within that limit by controlling what Claude sees per turn, reading the codebase iteratively, refactoring incrementally, and pinning conventions across prompts. Context is the causal lever: output quality scales with context richness, not prompt length (Chapter 10).
Why This Matters
Dumping every file into a prompt "would waste tokens and overwhelm the context window," and accuracy drops as the window fills. At the same time, Claude "doesn't store long-term memory between separate prompts; it only uses the context you provide" (Chapter 10) — so without deliberate management, output drifts across sessions and teammates (sync-vs-async variants, inconsistent naming, missing docstrings). The techniques here let Claude "reason across large codebases as if it had read the entire project — without ever exceeding token limits or losing precision" (Chapter 10).
Good Examples
- File Context Management, three techniques (Chapter 10): selective loading (provide just the target file plus its config), dependency awareness (give summaries or references such as "imports from utils/helpers.py" so Claude infers relationships rather than ingesting full dumps), and context linking (structured metadata describing how files relate). A script that reads the first ~30 lines of each file (imports, docstrings, class definitions) gives Claude enough to map a whole project cheaply (Chapter 10).
- Iterative contextual reading. Summarize one module at a time, then combine summaries into a project map. Summaries "preserve intent, not just syntax" — they capture why code exists, which is what makes them valuable for onboarding, audits, and refactors (Chapter 10).
- Layered monolith refactor, four moves (Chapter 10): (1) isolate data access behind a repository, (2) move business rules into a service layer so routes stay thin, (3) keep I/O at the edges, (4) introduce a composition root (
create_app()instead of globals). The payoff: you "changed structure, not behavior, and introduced seams" — enabling a SQLite→Postgres swap or caching "without touching route code."
Counterpoints
- Refactoring "the project" in one shot. "Claude performs best given concise context and clear goals" — incremental refactoring is scoped to one module, class, or function; broad "refactor everything" prompts produce unreviewable, drift-prone output (Chapter 10).
- Front-loading every file. Dumping all files wastes tokens and overwhelms the window, losing accuracy. Use progressive context feeding — "add files only when Claude asks" (Chapter 10).
- Relying on Claude to remember last session. It does not. Conventions must be re-supplied each session via a persistent context file, or output will silently diverge (Chapter 10).
Key Quotes
"Managing file context effectively allows Claude to reason across large codebases as if it had read the entire project — without ever exceeding token limits or losing precision." — Kilian Voss, Chapter 10
"Claude doesn't store long-term memory between separate prompts; it only uses the context you provide." — Kilian Voss, Chapter 10
Rules of Thumb
- Three Principles of Incremental Refactoring: scope (one unit at a time), validation (test each step → fewer regressions), traceability (autogenerated docs/commits record why). Small validated steps let code "evolve gracefully rather than through massive disruptive rewrites" (Chapter 10).
- Cross-Prompt Consistency Strategy: maintain a persistent
claude_context.md(conventions, architecture, goals) pasted into each session as the single source of truth, add style anchoring (state the convention explicitly), and use incremental session linking (carry summaries forward). Claude can then audit its own drift (e.g.,user_idvsuid). - Feed context progressively; let Claude ask for the next file rather than pre-loading the repo.
- Prefer file summaries and reference lines over full file contents to convey dependencies.
- Refactor toward seams (repository, service layer, composition root) — seams are where Claude can iterate safely afterward.
Related References
- Core Framework — Partner Not Autocomplete, Mastery Through Understanding - the context-richness lever this chapter applies at repo scale
- Refactoring and Optimization with Claude - incremental refactoring and layered architecture moves
- Project Workflows (API, DevOps, Multi-Agent) - structured, stepwise prompting that keeps generations consistent
- Rules of Thumb — Heuristics Across All Chapters - condensed heuristics