---
type: convention
title: Progressive Disclosure for Codebase Navigation
summary: A working convention for AI agents (and developers) navigating large codebases without pre-reading everything. Answers "how do I get oriented efficiently without burning context on files I don't need?"
tags:
  - type/convention
  - domain/software-engineering
  - domain/ai-agents
scope: global
last_updated: 2026-06-27
---

# Progressive Disclosure for Codebase Navigation

Context is finite. Loading everything upfront wastes it on irrelevant files and crowds out the work. Progressive disclosure is the discipline of loading only what you need, when you need it — oriented by routing files, not by exploration.

## Core Principles

**1. Start local.**
Begin with only the files present in the current working directory or immediate task scope. Do not recursively load parent directories, adjacent modules, or the full project tree before doing anything. Most tasks are resolvable from immediate context.

**2. Routing files over exploration.**
Each directory should have a routing file (e.g., `CLAUDE.md`, `.claude.md`, `README.md`) that explains the directory's purpose, what the key artifacts are, and which files to read next for specific needs. When uncertain, read the routing file — not the directory contents at large.

**3. Retrieve context selectively.**
When a gap appears (something is referenced but not locally defined), open only the one file the routing file points to for that gap. Resolve one gap at a time. Do not open several files speculatively to "just see what's there."

**4. Stop when clarity is achieved.**
Do not continue loading files once you have enough to proceed. The test is: "Can I do the next step?" — not "Do I understand the whole system?" Over-navigation is as costly as under-navigation; it just fails more slowly.

**5. Prefer structured artifacts over prose.**
When both a structured format (JSON, schema, type definitions, AST) and a descriptive format (markdown, comments) exist, reach for the structured one first. It answers questions faster and wastes fewer tokens.

## Patterns

**Layer-by-layer access.** Structure context access in tiers: (1) immediate local files always loaded, (2) routing file consulted on uncertainty, (3) specific referenced file fetched to resolve the gap, (4) deeper documentation fetched only when the card/reference file is insufficient. Each layer has a budget; never skip straight to the deep layer.

**Routing file as the interface contract.** A good routing file names its directory's purpose, lists the key files with a one-line description of what each resolves, and explicitly names what to avoid (generated files, legacy files, large media). When a directory lacks a routing file, creating one is the highest-leverage documentation contribution.

**Explicit gap identification.** Before opening any new file, name the gap: "I need to know X, which is referenced in Y." This prevents reflexive navigation. If you can't name what you're looking for, you're not ready to look.

**Format preference by information density.** Structured formats (`.json`, `.rb`, type signatures, schema files) answer "what is this shaped like?" in fewer tokens than prose explanations. Reach for them first when the question is structural. Reach for prose when the question is intent or rationale.

## Anti-Patterns

- **Loading entire directories at session start** — wastes context on irrelevant files; the right file often becomes clear only after the first tool call
- **Recursive exploration without a named gap** — "let me just look around" is expensive and rarely necessary; explore with a question in mind
- **Reading markdown when a schema exists** — prose descriptions of structure are slower to parse and more ambiguous than the structure itself
- **Fetching multiple context files simultaneously** — resolving several gaps at once compounds uncertainty; resolve sequentially so each fetch is informed by the previous result
- **Skipping the routing file and guessing** — directory contents look similar across projects; routing files encode the conventions specific to this one; guessing wastes turns
- **Treating "I don't know where X is" as license to read everything** — it's license to check the nearest routing file, then ask if still unclear

## Exceptions

**New project orientation.** On first entry to an unfamiliar project, a single broader read of the top-level routing file and directory listing is warranted. This is a bounded exception — one pass to identify the routing layer, then progressive disclosure applies.

**Small projects / flat layouts.** When the entire project is 5–10 files with no routing layer, loading all of them upfront is cheaper than the overhead of the progressive discipline. Apply PD proportionally to project size.

**Explicit search tasks.** "Find every place X is used" requires breadth-first access by definition. Progressive disclosure governs orientation and feature work; it doesn't apply to grep-style search tasks where the goal is coverage.

**When routing files are absent or stale.** If a project has no routing files, invest in creating them before doing deep work. If routing files are stale, update them as part of the task. The convention only works if the routing layer is maintained.