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

• 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)

• 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

References

• Exploration Patterns Examples - Detailed practical examples