codebase-overview

name	codebase-overview
description	Systematically explore and present the full architecture, structure, and content of any repository. Use when onboarding to a new codebase, before major refactors, or when the user asks "how does this project work?"

Codebase Overview

Provide a comprehensive, structured understanding of a repository's architecture, components, and conventions by systematically exploring its structure top-down.

When to Activate

• User asks "what does this project do?" or "how is this structured?"
• Onboarding to a new or unfamiliar repository
• Before planning a major refactor or feature
• User says "explain the codebase" or "give me an overview"
• Starting work on a project for the first time in a session

Exploration Strategy

Follow this top-down algorithm. Each step builds on the previous one.

Step 1: Project Identity

Read these files first (if they exist):

README.md / README.rst / README.txt
CLAUDE.md / .claude/rules/**
package.json / pyproject.toml / Cargo.toml / go.mod / *.csproj / build.gradle

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:

Pattern	Signals
MVC / MVVM	controllers/, models/, views/ directories
Layered	domain/, application/, infrastructure/
Microservices	Multiple services/ with independent configs
Monorepo	packages/, apps/, workspace config
Event-driven	Event emitters, message queues, pub/sub
Plugin-based	plugins/, hook systems, middleware chains

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

User Intent	Depth	Focus
"Quick overview"	Steps 1-2	Structure and stack only
"How does this work?"	Steps 1-4	Architecture and data flow
"Full deep dive"	Steps 1-6	Everything including config and quality
"Before refactoring"	Steps 1-5	Architecture, patterns, and test coverage

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.