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

bash

# 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 Agent.md docs/ 2>/dev/null

Step 2: Source Organization

code

# 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

code

# 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:

code

# 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:

code

# 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:

code

# 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

code

# 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

code

# 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

code

# 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

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

Build Mental Models

•Map the layers - presentation, business logic, data access
•Identify patterns - repository, service, controller, etc.
•Note conventions - naming, file organization, code style
•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, Agent.md)
•Do not grep for common words without filtering (use glob filters)

Output Format

After exploration, summarize findings:

code

## 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