Reading A Codebase It Has Never Seen
The first job in an unfamiliar codebase is to stop being lost, cheaply. Read the names, then search, then open a file. Each step costs more than the one before it, so judge an agent by how few files it opens.
A coding agent almost never knows the codebase it walks into. How cheaply it gets oriented sets the price of everything after.
Codebase model
Drop the agent into a huge house it has never seen and ask it to find one toy. The agent can hold only a few boxes at a time. Opening every box in every room is the slow way.
The fast way costs almost nothing. Read the door labels first: kitchen, garage, kids' room. That alone rules out most of the house. Then search the one likely room, and open a single box at the end.
The best agents open the fewest boxes, because they spend their first moves on the labels.
That house is the codebase, and the boxes are its files. I watched agents read far more than they needed to answer one question. Reading costs tokens and time, and most files hold nothing the agent needs. So the agent has to find the one part that matters and read only that. Watch the candidates fall from 1,840 to one, step by step.
01The constraint is the whole story
The codebase does not fit in the context window. Every file the agent opens spends tokens it does not get back, and pushes something else out. So the agent narrows its way to the answer instead of reading its way there. By narrowing I mean cutting the candidate set before spending a read on it. This is a search on a tight budget.
02Go wide and cheap before deep and expensive
The order of the moves is the plan. It runs from cheap and wide to costly and exact. Four moves sit in that order: list the tree, search the contents, read a range, read a whole file. The agent starts at the top, where reading the names covers the whole codebase for almost nothing.
Search comes next, and it is the second cheapest of the four. Only then does the agent open a file at all. The exact look comes last: jump to the definition and the callers. The context idea and the planning idea in this guide set the same rule: spend the cheap move first.
A lost agent runs the order backwards. It opens a promising file and reads every line on the chance the answer is there. The most expensive move goes first, in place of the two cheap ones. It burns the budget before it narrows anything, and it is still lost.
Rule out, then read
Orientation is the work of ruling rooms out until one is left. The agent buys that with names and search, and both are close to free. The savings pay for the few reads that matter.
03Names are the cheapest signal there is
A task about login needs no search when one directory is called auth. The agent narrows the work from directory names, file names, and the shape of the tree. A name is a guess, and a free guess is worth making first. Four of five directories drop out before the agent opens anything. Knowing a codebase is mostly knowing what everything is called.
04Search is how it turns a haystack into a shortlist
Give search a symbol, an error message, a route, or a setting. It sweeps all 1,840 files and reports the exact lines where the term appears. The contents never enter the window. Then the agent spends its expensive reads on the places search named. Change the term and the shortlist stays small: six files, or three, or nine.
05Reading is the last resort, not the first move
Only when the list is down to a few does the agent open a file. Even then it opens a range of lines. It keeps a record of those reads, so the same lines never cost twice. The tool idea in this guide holds that record, and the context budget is why it pays. By the time the agent reads, it is confirming a hunch it already has.
The cost
The failure that bit me most is ruling out the right directory. Search the obvious word and you miss the file that named it differently. Read the wrong file with confidence and you build a confident wrong map, which is worse than no map. When the narrow path stops making sense, widen the search again.
Decision
Watch the order of an agent's first moves. Names and search come before any read, and a range comes before a whole file. Then count the files it opened before it found the answer. The lowest count wins, and that is the test I run on anything I build.
An agent that opens big files top to bottom skipped the cheap moves. It will be slow, expensive, and lost. The next idea is the control you keep while the agent works.