Codebase overview

Codebase Overview

Produce a high-level overview of a codebase that orients a developer (or Claude) in about 5 minutes of reading. The output captures the big picture: what the project is, how it's organized, what tech it uses, what's currently being worked on, and how it deploys.

Scope

This skill is intentionally scoped to the big picture. It does NOT cover:

• Naming conventions or recurring code patterns → codebase-conventions
• Error handling and observability patterns → codebase-error-handling
• Testing framework, structure, mocking → codebase-testing-guide
• Domain vocabulary → codebase-glossary

If the user wants depth in any of those areas, mention the relevant sister skill at the end of the output rather than trying to cover it here.

What to Produce

A single Markdown file with these sections, in this order:

1. Project description — one paragraph: what the app does, who uses it, what tech stack it sits on top of.
2. Tech Stack — a table of layer → technology (Frontend, Backend, Database, Auth, Payments, Monitoring, etc.).
3. Directory Structure — annotated 2-level tree showing what each top-level folder is for.
4. Architecture — the major components and how they relate. Include at least one traced end-to-end flow (e.g., "API request → route → service → repo → database").
5. Key Design Decisions — 3–5 non-obvious technical choices, each with what was decided and why it matters.
6. Current State & In-Flight Work — current branch, what's actively being worked on, untracked or uncommitted files, in-progress refactors, known cleanup needed.
7. Deployment — environments, CI/CD pipeline, deployment trigger, where secrets/env vars live.

Aim for 150–300 lines total. If you're going beyond that, you're either including detail that belongs in a sister skill, or padding.

Output Template

# {Project Name} — Codebase Overview

> Generated by codebase-overview on {YYYY-MM-DD}

{One paragraph describing what the project does and the tech it runs on.}

## Tech Stack

| Layer | Tech |
|-------|------|
| Frontend | ... |
| Backend | ... |
| Database | ... |
| Auth | ... |
| ... | ... |

## Directory Structure

\```
{annotated 2-level tree}
\```

## Architecture

{Major components and how they relate. 2–4 paragraphs.}

**Traced flow:** {one real end-to-end flow showing the layers in action — e.g., "POST /api/users → user.routes.ts → user.service.ts → user.repository.ts → Firestore users collection"}

## Key Design Decisions

### {Choice 1}
{What was decided, why it matters}

### {Choice 2}
...

### {Choice 3}
...

## Current State & In-Flight Work

- **Current branch:** `{branch}` — {what recent commits suggest is being worked on}
- **Untracked / uncommitted files:** {list significant ones, or "none"}
- **In-progress refactors:** {parallel directories like v0/, legacy/ — what's being replaced and target end state, or "none detected"}
- **Known cleanup needed:** {dead code, debug logs, files that should be gitignored, TODO/FIXME hotspots}

## Deployment

- **Environments:** {staging, prod, etc.}
- **CI/CD:** {GitHub Actions / GitLab CI / etc. — pipeline overview}
- **Deployment trigger:** {merge to main / tags / manual}
- **Secrets / env vars:** {.env files, GitHub Secrets, Firebase Secrets, etc.}

---

## See Also

For deeper dives into specific areas of this codebase, run:
{list relevant sister skills based on what you noticed — e.g., "codebase-conventions for naming patterns", "codebase-testing-guide for the test setup"}

How to Scan

# Project layout (prefer git ls-files — respects .gitignore)
git ls-files --cached --exclude-standard 2>/dev/null | head -100

# Manifests / language detection
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat Cargo.toml 2>/dev/null

# Entry points
find . -maxdepth 3 \( -name "index.ts" -o -name "index.tsx" -o -name "main.py" -o -name "main.go" -o -name "App.tsx" \) -not -path '*/node_modules/*' 2>/dev/null | head -10

# Active work — current branch + recent commits
git branch --show-current 2>/dev/null
git log --oneline -10 2>/dev/null
git status --short 2>/dev/null

# In-progress refactors (parallel/legacy directories)
find . -maxdepth 3 -type d \( -name "legacy" -o -name "_old" -o -name "v[0-9]*" -o -name "deprecated" \) -not -path '*/node_modules/*' 2>/dev/null

# TODO/FIXME hotspots (small sample — just to flag, not enumerate)
grep -rn "TODO\|FIXME\|XXX" --include="*.ts" --include="*.tsx" --include="*.py" 2>/dev/null | head -10

# Deployment configs
ls .github/workflows/ .gitlab-ci.yml .firebaserc 2>/dev/null
cat .github/workflows/*.yml 2>/dev/null | head -40

# Existing docs (don't duplicate)
ls README* CONTRIBUTING* docs/ documentation/ 2>/dev/null

Where to Save

Check for an existing docs location:

• If docs/ exists, save as docs/codebase-overview.md
• If documentation/ exists, save as documentation/codebase-overview.md
• If .claude/ exists, save as .claude/codebase-overview.md
• Otherwise propose docs/codebase-overview.md and ask the user before creating

If the project is a monorepo with distinct packages (multiple package.json / pyproject.toml files at different levels), ask the user whether to produce one overview for the whole repo, or one per package.

Principles

Capture what isn't documented. If something is in the README, reference it briefly ("See README for setup") rather than re-explaining. Spend the depth budget on architectural intuition, design choices, and current state — the things that go stale fast and don't get written down.

Show real names. Use the actual names from the codebase — file paths, function names, route paths, package names. "POST /api/transactions is handled by transactions.routes.ts" beats "the API has transaction endpoints."

Trace one flow. A traced end-to-end flow is worth more than any prose description of architecture. Pick a representative request or interaction (an API call, a UI action, a webhook) and follow it through every layer.

Note current work. Always include the current branch and what's being worked on. This is the highest-value part of an overview because it goes stale within a week — and it's the part nobody writes down.

Stay in scope. Resist the urge to also document naming conventions, error handling, or testing in detail. That's what the sister skills are for. If you find yourself writing a "Naming Conventions" section, stop — note it as something the user might want to run codebase-conventions for, and move on.

After Producing

1. Save the file to the chosen location.
2. In chat, give a 3-sentence summary: the most important things a new developer should know.
3. Suggest which sister skills would be valuable to run next, based on what you noticed during the scan (e.g., "the test setup looks non-trivial — codebase-testing-guide would be worth running"). Only suggest skills that are actually relevant to this codebase, not all of them by default.
4. Provide a path or link to the saved file.