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 (a program set up to carry out tasks) wants to find where something happens in code, it often opens a file. Then it opens the obvious folder, a utility, a test, and another related folder. Before long, the session has already spent context reading code that was not needed to answer the question.
I did this for too long. It felt careful: read more, make fewer mistakes. In practice, it was an expensive way to make up for not having an index.
This happens when the question is not "what does this file do?" but "who uses this function (a piece of code that performs a task)?", "where is this route (path in the system) set up?", or "which component (part of the interface) calls this hook (a reusable code function)?" Reading the repository (the project files) as a whole treats a question about where to look as a question about what the code does.
The cost of reading the folder
Asking "read the folder" has a hidden cost. You pay again in every session. The agent does not remember the whole repository accurately. It receives some information, uses it for a while, then repeats the search in the next session.
Reading also takes focus away from the question. The more unrelated files enter the session, the more the original question competes with accidental details. A similar name, an old function, or an outdated test can lead the agent to the wrong place.
What a map stores
A code map (an index that points to where each part lives) does not need to store the whole codebase. It needs to show names, files, where each part was defined, which other files it uses, and where it is used. To find who uses a function, follow those links. You do not need to read every file line by line.
An index built from an AST (a structure showing how parts of the code relate) helps with this kind of question. It recognizes functions, methods, and calls inside components. It does not replace reading a file when it is time to change behavior. But it keeps the first search from becoming a trip through the repository.
I separate the jobs this way: read code to decide on a change. Check the map to decide where to look. Mixing them makes every question more expensive.
Start with one area
The next mistake is mapping the whole main folder and calling that context. An index of everything gets too large for a specific question. It can also go stale quickly. Any change anywhere makes the whole map less trustworthy.
It works better to map one area: a product, part of the system, business area, or layer. When I work on authentication, I do not need the marketing map. When I work on the blog, I do not need the billing index.
A small map is also easier to rebuild when it changes. Checking it needs to be cheap and predictable. Updating it can take longer, as long as it does not happen while someone waits for an answer.
Checking the map does not update it
This rule sounds small, but it changes the system. Checking the map should never start an update. If the first question in a session has to wait for the index to be created, the index has become another way to say "read the folder".
The map is prepared before anyone asks a question. At the end of a task, I update the area affected by changed files. In the next session, checking the map only asks a question. If the map is missing or old, it needs to say so instead of pretending to be accurate.
After that, reading is smaller and more focused. The agent asks the map where to start, opens a few files, checks the answer against the real code, and only then edits. The map does not decide the change. It only shortens the first search.
Where it breaks
An outdated map answers with the same confidence as an updated one. Because the answer arrives quickly and in a clean format, it can look more trustworthy than a manual search.
The risk is that an old index works like an old comment. It does not give a clear error. It points to the wrong place, the agent opens the wrong file, and work begins before anyone notices.
That is why I update the map at the end of the task. If the code changes and the area map is not updated, it is better to have no map. An outdated index trades too much reading for false certainty.