Start with the requested behavior, then trace evidence until you can name the responsible code. You will check the route before editing and preserve useful navigation output when its refresh fails.
The behavior gives search a target
Describe the requested behavior in one sentence before opening files that merely sound relevant. Use the words users see and the events they trigger as your first search terms. Matt Pocock recommends exploring the repository whenever its contents can answer your question directly. The first matching file remains a lead until surrounding evidence confirms its responsibility.
Search builds a working map
Boris Cherny reports that agentic filesystem search outperformed retrieval during codebase navigation in their comparison. Graham Neubig describes agents creating repository maps that help localize likely edits before changing code. A useful map connects the requested behavior to an entry point, responsible definitions, consumers, and nearby checks. Paul Gauthier explains that such a map helps choose which files deserve fuller context for inspection.
Focused context exposes the route
Pull the likely files into focused context instead of loading every available source at once. Follow references both ways to learn what calls this code and what this code requires. Read definitions beside their uses, because familiar names can conceal different behavior in another project. Keep each research conclusion tied to the exact supporting location, so later navigation remains grounded.
Planning separates evidence from action
Your exploration should end with a route from requested behavior to the planned change. Anthropic recommends separating exploration and planning from implementation to avoid solving the wrong problem during coding. Name the entry point, responsible code, inspected callers, relevant checks, and remaining uncertainty. Do not begin editing while any step in that route still depends on an untested assumption.
Limits keep the map honest
Every navigation view omits something, so record what yours cannot prove before relying upon it. Text search may miss runtime registration, while dependency views may omit timing and execution order. Generated context may also hide conditions, stale inputs, or relationships outside its selected boundary. The map guides inspection, while direct evidence confirms which code actually owns the behavior.
Keep the old map when refresh fails
Some maps depend on successful build results and relationship records before they can answer reliably. If either preparation fails, report the missing evidence before trusting the resulting map. Restore the required inputs, then rerun the same question against the newly generated navigation view. Replace the previous useful map only after the refreshed result completes successfully. For broader tool design, continue with the lesson about making missing operations usable.
A checked route earns the edit
Before editing, name the requested behavior, its entry point, the responsible code, and inspected dependencies. Then state what your map cannot show and which direct evidence closed each important gap. Follow the route again from the request to the planned change without skipping an unsupported jump. If another reader can repeat that route and reach the same code, your map has succeeded.
The sources show exploration comes first
The selected sources support direct exploration, repository maps, focused context, grounded conclusions, and separate planning. The videos report particular practitioner experiences, rather than universal performance guarantees for every repository. The documentation explains how maps narrow inspection, while the engineering guide separates research from implementation. The sources do not prove any map is complete, or that one search method always wins.
- Graham Neubig, video, Latent Space LIVE! 2024 in Agents, at 20:42. "they basically create a map of the repo"
- Boris Cherny, video, Inside Claude Code with Boris Cherny, at 51:53. "agentic search just outperformed everything."
- Matt Pocock, video, Agent Skills for Claude Code, at 01:40. "if a question can be answered by exploring the codebase, explore the codebase instead."
- Paul Gauthier, docs, Repository map, at If it needs to see more code, the. "use the map to figure out which files"
- Anthropic, engineering guide, Best practices for Claude Code, at Explore first, then plan, then code. "Separate research and planning from implementation to avoid solving the wrong problem."
Trace one requested behavior from its visible effect to responsible code before making your next edit.