incremental-context-buildinglisted

# Incremental Context Building — Layered Exploration When you land in an unfamiliar codebase (>50 files, or any project you haven't seen this session), do NOT immediately Read 20 files into context. That blows up your context budget and leaves you trying to reason across a wall of code with no mental model. ## Iron Law **Build understanding in layers, decide at each layer whether to go deeper. Never Read a file unless you have a specific question it will answer.** "I should familiarize myself with the code" is not a specific question. ## The Three Layers ### L1 — Orientation (1-2 minutes, <5K tokens) Goal: know what this project IS and where to look next. Read or Glob: - `README.md` (first 100 lines is usually enough) - `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `pom.xml` — whatever declares the stack - Top-level directory listing — names alone reveal a lot - `CLAUDE.md` if present — project-specific instructions Output of L1: a 2-sentence mental model. "This is a Python FastAPI service with a Postgres backend. Entry point looks like `src/app/main.py`. Tests live in `tests/`." If you can't say that after L1, do one more L1 pass (don't escalate to L2 blindly). ### L2 — Shape (3-5 minutes, ~15K tokens) Goal: know the major modules and how they connect. Read: - The entry point file (e.g., `main.py`, `index.ts`, `App.tsx`) - 1-2 representative core modules (e.g., one route handler, one model, one service) - Config files (settings, environment, build