Answer
How do you get a coding agent to understand a large codebase?
You do not. You give it a way to find the part that matters and enough orientation to use it.
You do not make it understand the whole thing. You give it search, a short map of what lives where, and the facts that reading cannot reveal. Comprehension of the relevant part is achieved per task, not held in advance.
The framing of the question contains the mistake. No individual holds a large system in mind, and the productive practice of experienced engineers is not comprehension but navigation: knowing roughly where things live, being able to search effectively, and knowing which few facts about the system are not visible in any single file. That is what an agent needs, and it is a much smaller thing to supply than understanding.
Search is the foundation and it is worth taking seriously rather than assuming. An agent that can search by symbol, by string and by path, and that can read the results, will locate the relevant code reliably. An agent restricted to files someone remembered to attach is working from a sample, and the quality of its work is bounded by the quality of that sample.
The map is the second piece and should be short. What the top-level areas are, what each is for, and where the entry points are. Not a description of every module, which duplicates something inspectable and will drift, but the orientation that lets a search be aimed. A page is usually enough, and the test is whether a competent stranger could use it to find where a given kind of change belongs.
The third piece is what reading cannot supply. Which of two similar implementations is live. Where the real invariants sit, as opposed to where they are documented. What breaks if a given assumption changes. Which parts are being replaced and should not be extended. These facts are the difference between a change that fits the system and one that is locally correct and wrong in context, and every one of them exists only in someone's head until it is written down.
Scope is the fourth and is often what actually determines success. An agent asked to change something in a defined area, with the tests for that area named, does markedly better than one pointed at the repository and given a goal. This is not about capability; a narrow scope makes both the search and the verification tractable, and it makes the resulting diff reviewable.
A final observation that is easy to miss. The things that make a codebase workable for an agent are the same things that make it workable for a new engineer, and the reverse is also true: if the answer to how does anyone find anything is that Sara knows, that is a real cost being paid already, and agent work simply makes it visible and repeated.
Nobody understands a large codebase, including the people who wrote it; they understand how to find the part that matters, which is the thing to reproduce.
Siddharth Sharma, Context Theory
Related questions
Should you generate documentation of the codebase for the agent?
Generated descriptions of structure are the least valuable kind, because they duplicate something inspectable and go stale silently while continuing to be believed. What is worth generating and then editing is the map and the non-obvious facts, and the editing is the part that matters, since a generated document cannot know which invariants are real.
Does a large codebase need a bigger context window?
It needs better navigation. Holding more of the repository at once produces a diluted working set rather than a comprehending one, and the retrieval quality on the specific file that matters gets worse rather than better. The pattern that scales is a small working set with a good search, at any window size.
METHOD
Every figure below carries its source and the date it was verified. Nothing on this page is asserted.
The numbers on this page.
| What | Value | Specific to |
|---|---|---|
| Visibility lift in AI-generated answers from GEO methods | up to 40% | Category-wide |
| Sub-15-minute compliance — automated routing vs manual only | 62.5% vs 39.1% | Category-wide |
Aggarwal et al., "GEO: Generative Engine Optimization", Princeton / Georgia Tech / IIT Delhi / Allen Institute for AI — KDD 2024 · GEO-bench · 10,000 queries across 8 domains · verified
2026 speed-to-lead benchmark · verified
What is specific to this page.
| Kind | Claim | Check it against |
|---|---|---|
| Workflow | Experienced engineers operate large systems by navigation rather than comprehension, so the requirement to reproduce is effective search plus orientation plus the few facts invisible in any single file, not whole-system understanding. | Asking an engineer familiar with the system to describe how they locate the code for an unfamiliar change. |
| Software | An agent restricted to files a person attached is working from a sample, so its output quality is bounded by that sample regardless of capability, which makes symbol, string and path search a prerequisite rather than a convenience. | Comparing outcomes on the same task with attached files only and with search available. |
| Response | Facts such as which of two similar implementations is live, where real invariants sit, and which areas are being replaced exist only in individuals' knowledge until written, and they determine whether a change fits the system or is locally correct and contextually wrong. | Listing the questions a new engineer asks in their first fortnight and checking which are answered anywhere in the repository. |
| Buying behaviour | Narrowing the scope of a task to a defined area with named tests improves outcomes independently of model capability, because it makes both search and verification tractable and keeps the resulting diff reviewable. | Comparing diff size and review time for the same change requested at repository scope and at module scope. |
Each row would be wrong on another industry's page. Where a sourced figure exists it is in the table above instead; these are the constraints that shape the work and do not happen to be numbers.
Start with the measurement.
Reading about a benchmark is not the same as knowing your own number. The audit produces yours, measured rather than estimated.
$497 · delivered in 5 business days · credited against month one