codebase-navigation

Codebase Exploration

Systematic patterns for navigating and understanding codebases efficiently.

When to Use

• Onboarding to a new codebase - Understanding project structure and conventions
• Locating specific implementations - Finding where functionality lives
• Tracing dependencies - Understanding how components connect
• Architecture analysis - Mapping system structure and boundaries
• Finding usage patterns - Discovering how APIs or functions are used
• Investigating issues - Tracing code paths for debugging

Quick Structure Analysis

Start broad, then narrow down. This three-step pattern works for any codebase.

Step 1: Project Layout

# Understand top-level structure
ls -la

# Find configuration files (reveals tech stack)
ls -la *.json *.yaml *.yml *.toml 2>/dev/null

# Check for documentation
ls -la README* CLAUDE.md docs/ 2>/dev/null

Step 2: Source Organization

# Find source directories
Glob: **/src/**/*.{ts,js,py,go,rs,java}

# Find test directories
Glob: **/{test,tests,__tests__,spec}/**/*

# Find entry points
Glob: **/index.{ts,js,py} | **/main.{ts,js,py,go,rs}

Step 3: Configuration Discovery

# Package/dependency files
Glob: **/package.json | **/requirements.txt | **/go.mod | **/Cargo.toml

# Build configuration
Glob: **/{tsconfig,vite.config,webpack.config,jest.config}.*

# Environment/deployment
Glob: **/{.env*,docker-compose*,Dockerfile}

Deep Search Strategies

Finding Implementations

When you need to locate where something is implemented:

# Find function/class definitions
Grep: (function|class|interface|type)\s+TargetName

# Find exports
Grep: export\s+(default\s+)?(function|class|const)\s+TargetName

# Find specific patterns (adjust for language)
Grep: def target_name  # Python
Grep: func TargetName  # Go
Grep: fn target_name   # Rust

Tracing Usage

When you need to find where something is used:

# Find imports of a module
Grep: import.*from\s+['"].*target-module

# Find function calls
Grep: targetFunction\(

# Find references (broad search)
Grep: TargetName

Architecture Mapping

When you need to understand system structure:

# Find all route definitions
Grep: (app\.(get|post|put|delete)|router\.)

# Find database models/schemas
Grep: (Schema|Model|Entity|Table)\s*\(
Glob: **/{models,entities,schemas}/**/*

# Find service boundaries
Glob: **/{services,controllers,handlers}/**/*
Grep: (class|interface)\s+\w+Service

Exploration Patterns by Goal

Goal: Understand Entry Points

# Web application routes
Grep: (Route|path|endpoint)
Glob: **/routes/**/* | **/*router*

# CLI commands
Grep: (command|program\.)
Glob: **/cli/**/* | **/commands/**/*

# Event handlers
Grep: (on|handle|subscribe)\s*\(

Goal: Find Configuration

# Environment variables
Grep: (process\.env|os\.environ|env\.)

# Feature flags
Grep: (feature|flag|toggle)

# Constants/config objects
Grep: (const|let)\s+(CONFIG|config|settings)
Glob: **/{config,constants}/**/*

Goal: Understand Data Flow

# Database queries
Grep: (SELECT|INSERT|UPDATE|DELETE|find|create|update)
Grep: (prisma|sequelize|typeorm|mongoose)\.

# API calls
Grep: (fetch|axios|http\.|request\()

# State management
Grep: (useState|useReducer|createStore|createSlice)

Best Practices

Search Efficiently

1. Start with Glob for file discovery - faster than grep for locating files
2. Use Grep for content search - supports regex and context
3. Narrow scope - search in specific directories when possible
4. Check output modes - use files_with_matches for discovery, content for analysis

Build Mental Models

1. Map the layers - presentation, business logic, data access
2. Identify patterns - repository, service, controller, etc.
3. Note conventions - naming, file organization, code style
4. Document boundaries - where modules connect and separate

Avoid Common Pitfalls

• Do not search entire node_modules/vendor directories
• Do not assume structure without verifying
• Do not skip reading project documentation (README, CLAUDE.md)
• Do not grep for common words without filtering (use glob filters)

Output Format

After exploration, summarize findings:

## Codebase Overview

**Tech Stack:** [Languages, frameworks, tools]
**Architecture:** [Monolith, microservices, modular, etc.]
**Entry Points:** [Main files, routes, handlers]

## Key Directories

- `src/` - [Purpose]
- `lib/` - [Purpose]
- `tests/` - [Purpose]

## Conventions Observed

- Naming: [Pattern]
- File organization: [Pattern]
- Testing: [Pattern]

## Dependencies

- [Key dependency]: [Purpose]
- [Key dependency]: [Purpose]

References

• Exploration Patterns Examples - Detailed practical examples