Directed Codebase Exploration

directed-codebase-exploration

Map component ownership and data flow before exploring a codebase to avoid wasteful, unfocused searches.

Directed Codebase Exploration

When you need to understand or modify a codebase, unfocused exploration (like grepping for keywords without a plan) burns tokens quickly without progress.

Steps

1. Clarify the goal - Write down exactly what you're looking for (e.g., "Find where user settings are loaded and validated")

2. Identify key components - Ask yourself:

   • Which files/modules are most likely involved?
   • What's the entry point (main, config loader, etc.)?
   • Who owns this functionality (which class/module)?

3. Map data flow - Trace how data moves:

   • Where does input come from?
   • What transforms it?
   • Where does output go?

4. Search with direction - Use grep/search strategically:

   • Target specific files or directories first
   • Search for clear identifiers (class names, function signatures)
   • Follow imports and definitions rather than keyword hunting

5. Verify ownership - Confirm which component is responsible before making changes

Tips

• Review directory structure and key file names first to build mental model
• Check README, docs, or comments for architecture hints
• Look at imports to understand component relationships
• Stop searching and ask for clarification if you've done 10+ searches without narrowing down the location

Avoid: Broad grep searches for vague terms across the entire codebase. Do: Understand architecture, identify the likely location, then search there precisely.