Codebase Overview

Extract:

• Project name and purpose (one sentence)
• Primary language(s) and framework(s)
• Key dependencies (top 5-10 that define the stack)
• Build/run commands (dev, build, test, lint)

Step 2: Directory Layout

Run a top-level directory listing, then explore 1-2 levels deep in key directories.

# Top-level structure
ls -la

# Key directories (explore selectively)
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' -not -path '*/__pycache__/*' -not -path '*/target/*' -not -path '*/.next/*'

Classify directories by role:

• Source code: src/, lib/, app/, pkg/, internal/
• Tests: test/, tests/, __tests__/, spec/
• Configuration: config files, .env.example, CI/CD
• Documentation: docs/, doc/
• Build artifacts: dist/, build/, out/, target/
• Infrastructure: docker/, k8s/, terraform/, infra/

Step 3: Entry Points and Data Flow

Identify how the application starts and how data moves through it:

• Entry points: main.*, index.*, app.*, server.*, CLI entry, route definitions
• API surface: Route files, controller directories, GraphQL schemas, RPC definitions
• Data layer: Models, schemas, migrations, ORM configuration
• External integrations: API clients, SDK usage, message queues

Step 4: Architectural Patterns

Look for evidence of these patterns:

Step 5: Testing and Quality

Identify:

• Test framework (Jest, pytest, Go testing, etc.)
• Test structure (co-located vs. separate directory)
• Coverage configuration (if any)
• Linting/formatting (ESLint, Prettier, Black, golangci-lint)
• CI/CD pipeline (GitHub Actions, GitLab CI, etc.)

Step 6: Configuration and Environment

Look for:

• Environment variables: .env.example, config/ directory
• Feature flags: LaunchDarkly, custom flag systems
• Multi-environment setup: staging, production configs
• Secrets management: vault references, KMS usage

Output Format

Present findings using this template:

# Codebase Overview: {project-name}

## Summary
{1-2 sentences: what this project does and its primary technology}

## Tech Stack
- **Language**: {language} {version}
- **Framework**: {framework} {version}
- **Database**: {if applicable}
- **Key Dependencies**: {top 5-10}

## Directory Structure
{annotated tree showing key directories and their roles}

## Architecture
- **Pattern**: {MVC, layered, microservices, etc.}
- **Entry Point**: {file path}
- **Key Modules**:
  - `{path}` — {purpose}
  - `{path}` — {purpose}
  - ...

## Data Flow
{how a request/action flows through the system, 3-5 steps}

## Development
- **Run**: `{command}`
- **Test**: `{command}`
- **Build**: `{command}`
- **Lint**: `{command}`

## Key Files
| File | Purpose |
|------|---------|
| {path} | {description} |
| ... | ... |

## Conventions
- {notable coding conventions observed}
- {naming patterns}
- {error handling approach}

## Notes
- {anything unusual, notable, or worth highlighting}

Best Practices

DO

• Start broad, then drill down — read project metadata before source code
• Follow imports — trace how modules connect by reading import statements
• Check git history — git log --oneline -20 reveals recent focus areas
• Read tests — tests often explain intended behavior better than source code
• Note what's missing — absent tests, docs, or CI config is valuable information

DON'T

• ❌ Read every file — focus on entry points, public APIs, and key modules
• ❌ Get lost in implementation details — stay at the architectural level first
• ❌ Assume from directory names alone — verify by reading key files
• ❌ Skip configuration files — they reveal the real runtime behavior
• ❌ Ignore .gitignore and CI config — they show what the project considers important

Exploration Depth Guide

Related Skills

• update-codemaps — generates persistent code map artifacts (complementary: overview explains, codemaps document)
• security-review — use after overview to audit security posture
• plan — use overview findings to inform implementation planning

Understanding a codebase is not reading every line — it's knowing which lines matter.