Reading begins with a map, not a dump
A large repository can contain millions of lines, generated outputs and multiple applications. Sending it all to a model is usually impossible or wasteful. An agent instead needs a way to discover the project structure, identify likely entry points and test a hypothesis with small reads. Package manifests, workspace definitions, top-level directories and test conventions supply the first map. They show where code is likely to live without pretending to explain every behavior.
This map should be revisable. A monorepo may have duplicated names across packages, compatibility layers or generated clients. The first directory that matches a search term may not own the active runtime path. An effective agent keeps the request in view and narrows the search by package, import path and execution context.
Use the symptom as an anchor
An error message, test name, URL route or exported symbol is a better starting point than a vague request to understand the codebase. Search the exact string first, then inspect the surrounding function and its callers. If the string is absent, search related types or configuration. This yields a trace from observed behavior toward the code that owns it.
For example, a failed login may involve a browser form, an API route and an identity provider. Opening every auth file at once can obscure the boundary that actually rejects the request. Follow the path step by step: where does the form submit, which response arrives, and which code translates that response into the visible error? Each answer suggests the next file.
Read contracts and tests together
A function body explains one implementation, but a type, interface or schema explains what other code expects from it. Tests show examples of intended behavior and edge cases. An agent should inspect these together when planning a change. A caller may pass a nullable value even if the implementation's happy path assumes a string. A test may reveal that a seemingly unused branch protects backward compatibility.
This triangulation also limits hallucination. If the agent claims an API behaves a certain way, ask it to point to the contract or test. If the evidence is missing, the claim remains a hypothesis. The agent may need to run a focused test or inspect runtime logs. Large-codebase reading is a sequence of evidence-backed questions, not a one-time ingestion step.
Static maps are clues, not execution traces
Symbol indexes, reference search and code lenses can locate nearby relationships quickly. Licuse's bounded code-lens view can help surface a target and related callers or callees. Yet static relationships may miss dynamic imports, reflection, configuration-driven wiring and runtime data. A function being referenced does not prove that the failing request executed it.
Use static results to choose where to look next. Confirm the path with tests, instrumentation or logs when the distinction matters. In a typed codebase, references often give a strong map; in a plugin system, runtime registration may be decisive. The method should adapt to the architecture instead of treating one search result as a complete explanation.
Control context size and freshness
A model window is finite, and irrelevant files dilute attention. Give the agent concise excerpts with paths and enough surrounding code to understand the contract. Expand only when a hypothesis requires another module. Summaries can preserve orientation, but exact source should be re-read before editing. An old summary may describe another branch or an earlier revision of the same file.
Freshness matters during collaboration. If a developer or build step changes a file, the agent should not write based on its old copy. Check Git status and reopen the target before applying a patch. The final explanation should distinguish observed current source from recalled history. Memory can point to a likely location but should not substitute for inspection.
Verification completes the read
Reading a repository is ultimately in service of a decision. After a change, run the relevant test, typecheck or build and use the output as new evidence. A failing command may point to a caller the earlier search missed. A passing command supports a narrower claim: the checked path works under that environment. It does not guarantee that every runtime configuration or deployment is safe.
When the task is only explanation, verification can mean tracing a complete call path and naming uncertainty. If no test or runtime observation is available, say so. The value of a coding agent is not that it can produce a confident answer to every question, but that it can show the path from source to conclusion.
A repeatable repository-reading routine
Start with the user-visible symptom and project boundary. Inspect manifests and recent changes, search the exact symbol, read the owning implementation, follow callers and contracts, then check tests. Keep a short note of what each file established. If a theory fails, record the contradiction and search a different boundary rather than collecting unrelated files.
This routine scales because it reduces the search space at each step. It also makes review easier: another engineer can repeat the path and challenge the inference. For a large codebase, the best agent is the one that chooses relevant evidence and updates its model when new evidence appears, not the one that opens the most files.
Large-codebase skill is mostly evidence selection and verification.
Sources & further reading
References support the concepts and product descriptions discussed above. Features, prices and account eligibility can change; check the live documentation. Inclusion here is not a hands-on test or vendor endorsement.