When an agent encounters a 500-file codebase it has never seen, reading every file is wasteful. The efficient approach: search for entry points, read key files, then follow imports outward. Build understanding incrementally from high-level structure to specific details.
The incremental strategy
- Grep for entry points:
main,app.listen, route definitions,export default, top-level configurations - Read the identified entry point files to understand high-level architecture
- Follow imports: Grep for imported modules, Read those files to understand dependencies
- Expand as needed: continue tracing the dependency graph based on the task’s requirements
This builds a mental map of the codebase from the top down, using context only for relevant files.
Why not read everything?
500 files won’t fit in context. Even if they did, the lost-in-the-middle effect makes most content unreliable. Reading everything also wastes context on irrelevant files (utility functions, config templates, boilerplate).
The incremental approach uses context efficiently: only relevant files are loaded, and each read is informed by what was found in previous searches.
Why not ask the user?
Users may not know all codebase details or may describe outdated architecture. The agent should build its own understanding from the actual code. User descriptions can supplement, not replace, code-level exploration.
The tool sequence
Grep finds the files that matter. Read loads their content. Glob finds related files by pattern when needed (all test files, all config files). This Grep→Read→Glob workflow is the standard codebase exploration pattern.
One-liner: Explore unfamiliar codebases incrementally: Grep for entry points → Read key files → trace imports outward. Never try to load an entire codebase at once.