Master Codebase Navigation and Context Engineering in Claude Code

Quick answer

Context engineering is the practice of putting the smallest set of decision-relevant facts in front of the agent. In a large repository, have Claude build an evidence map, trace one behavior end to end, and progressively disclose detail. Do not ask it to read everything.

Use Anthropic's context window guide alongside this lesson for the current behavior of compaction, memory, skills, and subagents.

Build a repository map

Start with structure and execution paths:

Map this repository for an engineer joining the team. Identify applications,
packages, runtime entry points, build/test commands, generated-code boundaries,
and local instruction files. Cite paths. Limit the map to facts needed to work
on the payments API.

Then narrow:

Trace POST /payments from routing through authentication, validation, domain
logic, persistence, and outbound events. Cite symbols and tests. Mark any step
you inferred rather than observed.

The inference label matters. It turns false certainty into an explicit research queue.

Search in layers

Use this order:

1. Discover filenames and configuration.
2. Search exact route names, types, or error strings.
3. Read the smallest relevant regions.
4. Follow imports, callers, and tests.
5. Run the system to validate the static model.

Static reading cannot prove runtime wiring when dependency injection, code generation, feature flags, or environment-specific configuration is involved.

Create an evidence table

Ask Claude to return a compact table:

Question	Evidence	Confidence	Next check
Where is input validated?	src/payments/schema.ts	High	Run invalid-body test
Is retry idempotent?	Key passed to provider client	Medium	Inspect DB uniqueness constraint
What emits the receipt?	Event handler name found	Low	Confirm handler registration

This format is excellent for debugging, migrations, and security work.

Manage the context window

Long sessions accumulate tool output, abandoned hypotheses, and duplicate explanations. Use several controls:

• Ask for compact summaries after exploration.
• Put stable rules in CLAUDE.md, not repeated prompts.
• Put large reference material in skills that load on demand.
• Delegate noisy research to a subagent and return only findings.
• Use /clear when the objective changes.
• Resume a relevant session instead of mixing unrelated tasks.

The official context guidance explains that when context fills, Claude Code can compact earlier conversation. Compaction preserves a summary, not every detail. Preserve critical decisions in a file or concise checkpoint before that happens.

Example: investigate a slow page

Investigate why /reports takes 8 seconds in production. Begin with the request
path and data dependencies. Inspect query construction, caching, and waterfall
behavior. Use existing logs or profiling commands if available. Do not optimize
until you identify the dominant cost. Return evidence and a baseline number.

After measurement:

The trace shows 78% of time in 240 sequential account queries. Propose the
smallest change that removes the N+1 behavior. Preserve authorization filtering.
Add a query-count regression test and compare before/after measurements.

Context hygiene checklist

• Is every included file relevant to the current decision?
• Did generated artifacts or vendor directories add noise?
• Are instructions current and scoped correctly?
• Are assumptions clearly marked?
• Is there a runnable check for the runtime path?
• Would a fresh session understand the handoff summary?

FAQ

Should Claude read the whole repository first?

Usually no. Repository-scale reading consumes context and dilutes signal. Map broadly, then trace narrowly.

How do I stop Claude from hallucinating architecture?

Require file-and-symbol citations, label inference, and validate runtime wiring with tests or commands.

What belongs in the main context?

The goal, constraints, current evidence, active decisions, and verification results. Background references should load only when needed.