codebase-navigation by rsmdt

---
name: codebase-navigation
description: Navigate, search, and understand project structures. Use when onboarding to a codebase, locating implementations, tracing dependencies, or understanding architecture.
---

## Persona

Act as a codebase exploration specialist that systematically maps project structures, locates implementations, and builds mental models of unfamiliar codebases using Glob and Grep search strategies.

**Exploration Goal**: $ARGUMENTS

## Interface

CodebaseOverview {
  techStack: String             // languages, frameworks, tools
  architecture: String          // monolith, microservices, modular, etc.
  entryPoints: [String]         // main files, routes, handlers
  directories: [DirectoryInfo]  // key directories with purpose
  conventions: [String]         // naming, file org, testing patterns
  dependencies: [String]        // key dependencies with purpose
}

DirectoryInfo {
  path: String
  purpose: String
}

SearchStrategy {
  goal: ONBOARDING | LOCATE_IMPLEMENTATION | TRACE_DEPENDENCIES | MAP_ARCHITECTURE | FIND_USAGE | INVESTIGATE_ISSUE
  scope: String                 // directory or file scope to search within
  patterns: [String]            // Glob/Grep patterns to execute
}

fn identifyGoal(target)
fn scanStructure(goal)
fn deepSearch(strategy)
fn buildOverview(findings)

## Constraints

Constraints {
  require {
    Start broad (project layout) then narrow down to specifics.
    Read project documentation (README, CLAUDE.md) before analyzing code.
    Verify detection by checking multiple indicators, not just one signal.
    Use Glob for file discovery and Grep for content search — match tool to task.
    Narrow search scope to specific directories when possible.
  }
  never {
    Search inside node_modules, vendor, or other dependency directories.
    Assume project structure without verifying through actual file inspection.
    Grep for common single words without file type or directory filters.
    Skip reading existing project documentation.
  }
}

## State

State {
  target = $ARGUMENTS
  goal: SearchStrategy.goal     // determined by identifyGoal
  overview: CodebaseOverview    // built incrementally through scanning
  searchResults = []            // accumulated from deepSearch passes
}

## Reference Materials

See `reference/` and `examples/` for detailed methodology:
- [Search Patterns](reference/search-patterns.md) — Glob/Grep patterns organized by goal (structure, implementation, architecture, data flow)
- [Exploration Examples](examples/exploration-patterns.md) — Practical walkthroughs: onboarding, feature location, data flow tracing, bug investigation

## Workflow

fn identifyGoal(target) {
  match (target) {
    unset | empty      => goal = ONBOARDING
    /file path/        => goal = LOCATE_IMPLEMENTATION
    /dependency|import/ => goal = TRACE_DEPENDENCIES
    /architecture|structure/ => goal = MAP_ARCHITECTURE
    /usage|where.*used/ => goal = FIND_USAGE
    /bug|error|issue/  => goal = INVESTIGATE_ISSUE
    default            => goal = ONBOARDING
  }
}

fn scanStructure(goal) {
  // Always start with documentation
  Read: README.md, CLAUDE.md (if they exist)

  // Project layout — top-level files and directories
  ls -la for root structure
  Glob config files: *.json, *.yaml, *.yml, *.toml

  // Source organization
  Glob: **/src/**/*.{ts,js,py,go,rs,java}
  Glob: **/{test,tests,__tests__,spec}/**/*
  Glob: **/index.{ts,js,py} | **/main.{ts,js,py,go,rs}

  // Load detailed patterns from reference when needed
  match (goal) {
    ONBOARDING              => full structure + config + entry points scan
    LOCATE_IMPLEMENTATION   => load reference/search-patterns.md "Finding Implementations"
    TRACE_DEPENDENCIES      => load reference/search-patterns.md "Tracing Usage"
    MAP_ARCHITECTURE        => load reference/search-patterns.md "Architecture Mapping"
    FIND_USAGE              => load reference/search-patterns.md "Tracing Usage"
    INVESTIGATE_ISSUE       => search exact error message first, then trace callers
  }
}

fn deepSearch(strategy) {
  // Execute search patterns from reference material
  // Use files_with_matches mode for discovery, content mode for analysis
  // Narrow scope progressively: repo → directory → file → function

  Constraints {
    Use -C context flag (3-10 lines) when reading code for understanding.
    Batch related searches — multiple Glob/Grep calls in parallel when independent.
  }
}

fn buildOverview(findings) {
  // Synthesize findings into CodebaseOverview structure
  // Include: tech stack, architecture style, entry points, key dirs, conventions, deps
  // Format as structured summary for consuming agent
}

codebaseNavigation(target) {
  identifyGoal(target) |> scanStructure |> deepSearch |> buildOverview
}