A map of the code beats reading the code
Opening the whole folder to answer where something happens feels complete, but it becomes a fixed cost. A small scoped map answers better.
When an agent wants to find where something happens in code, the default answer is to open a file. First the obvious folder, then a utility, then the test, then another folder that looked related. By the time you notice, the session has already spent context reading code that did not need to be there to answer the original question.
I did this for too long. It felt careful: read more, make fewer mistakes. In practice, it was an expensive way to compensate for not having an index.
The concrete problem appears when the question is not "what does this file do", but "who uses this function", "where is this route mounted", "which component calls this hook". Reading the whole repository for that treats a navigation question as if it were an interpretation question.
The cost of reading the folder
Asking "read the folder" has a hidden cost: you pay it again in every session. The agent does not wake up remembering the whole repository faithfully. It receives context, uses it for a while, and then the next session repeats the same ritual.
The cost is not only tokens. It is focus. The more irrelevant files enter the window, the more the original question competes with accidental detail. A similar name, an old function, a stale test. The agent now has enough material to build a plausible answer on top of the wrong place.
What a map stores
A code map does not need to store the whole codebase. What I want from it is drier: symbol, file, definition, import, call. If the question is "who uses this function", the answer comes from the relationship between symbols, not from reading every consumer line by line.
An AST index solves this class of question better because it sees structure, not loose text. It knows that one name is a function, another is a method, and a call sits inside a component. That does not replace reading the file when it is time to change behavior, but it keeps the initial search from becoming a trip through the repository.
The distinction that organizes everything is this: reading code is for deciding a change; querying a map is for deciding where to look. Mixing the two makes every question expensive.
Scope before root
The next mistake is trying to build a map of the whole root and calling that context. An index of everything becomes another object too large to fit inside the question. It also ages quickly, because any change anywhere threatens trust in the whole set.
What works better is a map by scope. A product, a module, a domain area, a layer. When I am working on authentication, I do not need to load the marketing map. When I am working on the blog, I do not need the index to tell me about billing.
The small scope has another advantage: it can be rebuilt without ceremony when it changes. The query needs to be cheap and predictable. Rebuilding can be more expensive, as long as it does not happen in the middle of the question.
A query does not rebuild
This rule sounds like a detail, but it changes the system: querying the map never triggers a rebuild. If the first question in a session has to wait for the index to be born, the index has become another form of "read the folder".
The map is prepared outside the hot path. At the end of a task, when files changed, the affected scope is updated. In the next session, the query only asks. If the map does not exist or is stale, it should say that instead of pretending to be precise.
After that, reading becomes smaller and more intentional. The agent asks the map where to start, opens a few files, confirms the interpretation in the real code, and only then edits. The map does not decide the change. It cuts the dumb part of navigation.
Where it breaks
A stale map answers with the same confidence as an updated one. And because the answer arrives quickly, cleanly, and formatted, it looks more trustworthy than a messy manual search.
That is the real risk: an old index is the silent version of a stale comment. It does not fail loudly. It points to the old place, lets the agent open the wrong file, and the session takes a few steps before anyone notices.
That is why updating has to live at the end of the task. If code changes and the scope map is not updated, it is better not to have a map. An index that does not follow the work does not reduce cost; it only trades excessive reading for false certainty.