codebase-explainer

Codebase Explainer

Produce one Markdown file that lets someone new to this repo understand:

1. what the app does and how it is put together,
2. what every file does and why the app needs it,
3. how a real request or user action flows through the files,

with Mermaid diagrams that render on GitHub, GitLab and VS Code.

The reader is learning. Write in plain language, define jargon the first time it appears, and never state anything you did not see in the code.

Do not modify any project file. The only file you write is the guide.

Arguments

$ARGUMENTS may contain, in any order:

• a folder (e.g. src/api): explain that folder in depth; describe the rest only as context.
• --out <path>: where to write the guide. Default: CODEBASE_GUIDE.md in the repo root. If that file exists and its first line is not the <!-- generated by codebase-explainer marker, write CODEBASE_GUIDE.generated.md instead and say so.
• --quick: overview, stack, diagrams, main flow, learning path and the 15 to 25 most important files only. No full coverage.

No arguments means the whole repo, full depth.

Workflow

Create a task list with these steps and tick them off as you go.

1. Scan the repo

From the repo root run:

python3 ${CLAUDE_SKILL_DIR}/scripts/scan_repo.py . [--focus <folder>]

Use python instead of python3 on Windows. Add --max-list 5000 if the output says the inventory was truncated.

The scan gives you the file inventory (kind, language, lines, how many files import each one), detected stack, run scripts, likely entry points, architecture groups with folder-to-folder import edges, hub files, routes, environment variable names, and files nothing imports.

Treat it as a map, not the truth. It works from heuristics, so confirm everything by reading code.

If Python is unavailable, build the same picture by hand: Glob **/* (skip node_modules, .git, build output, virtualenvs), read the manifests, and Grep for imports, routes and env reads.

2. Read the code in this order

1. README and any docs overview: what the authors say the app is.
2. Manifests (package.json scripts, pyproject.toml, Dockerfile, compose files, Makefile): how it is installed, run, built and tested.
3. Entry points: what happens at startup.
4. Hub files (highest "In" count): the core pieces everything depends on.
5. One main route, screen or command, end to end.
6. Then every remaining file the guide must cover.

Scale the reading to the repo size (count source + config files in the scan):

Size	How to read
up to 150 files	Read every file in full (skim generated or very long data files).
150 to 600 files	Read entry points, hubs and every file under about 300 lines in full. For longer files read imports, exports and signatures, then Grep for the key symbols.
over 600 files, or a monorepo	Run parallel Explore subagents, one per architecture group or package from the scan, with the prompt below. Describe core folders file by file; cover repetitive files (UI kit primitives, generated API clients, migrations, icons, fixtures) with one narrow glob row each.

Subagent prompt (fill in <group>):

Read every file under <group>/. Return one Markdown table row per file: | `full/repo/path` | what it does, one plain-English sentence | why the app needs it: what breaks or is missing without it | imports X / imported by Y |. Merge near-identical files into one row with a narrow glob such as `<group>/icons/*.tsx`. Then list the 3 most important files in this folder and why, plus any env vars, external services or surprising behaviour. Only state what the code shows.

3. Work out the "why" for each file

Ask: if this file were deleted, what would stop working? That answer is the "why".

• Good: "Every service imports the shared database client from here. Without it no request can read or write data."
• Weak: "Contains the Prisma client."

Name the main exported functions or classes for any file longer than about 150 lines.

4. Trace the main flows

Pick the 1 to 3 most important user actions from the routes, screens or CLI commands (for example "sign in", "create an order", "run the CLI on a file"). Follow the real call chain function by function and note each path and function() it passes through. These become the sequence diagrams and numbered walkthroughs.

5. Write the guide

Follow the structure in template.md. Drop sections that do not apply (no database means no data model) and keep the numbering continuous. Draw diagrams by the rules in reference/mermaid-guide.md.

Minimum diagrams:

• architecture flowchart, built from the scan's groups and edges;
• folder map;
• one sequence diagram per main flow;
• an ER diagram when there are models, schemas or migrations;
• a state diagram when the code has an explicit state machine or status field that drives behaviour.

Writing rules:

• Write full repo-relative paths in backticks for every file (src/routes/auth/auth.service.ts, not auth.service.ts). The verifier relies on this.
• A glob row such as `src/components/ui/*.tsx` may cover a set of near-identical files. Bare folder mentions like `src/` do not count as covering the files inside.
• Order each folder's table by importance: entry, core logic, helpers, then tests.
• Environment variables: names and purpose only. Never print values, and never open real .env files; .env.example-style files are fine.
• If you are unsure, say "appears to" and give the evidence.
• On big repos write in stages: header, overview and diagrams first, then append the file-by-file tables folder by folder.
• If examples/example-guide.md exists, skim it once to calibrate depth and tone.

6. Verify and fix

command -v mmdc   # Mermaid CLI available?
python3 ${CLAUDE_SKILL_DIR}/scripts/verify_guide.py <guide-path> --root . [--focus <folder>] [--render]

Add --render only when mmdc exists. With --quick, add --min-coverage 0.

The verifier flags invented or misspelled paths, files the guide never explains, and Mermaid syntax that will not render. Fix every FAIL line and re-run until it prints RESULT: PASS. Read the NOTE lines too, but they do not block.

7. Report back

Reply briefly with:

• where the guide was written;
• 2 to 3 sentences on how the app works;
• the 3 files to read first;
• stats: files explained, number of diagrams, verifier result.

Then offer one next step, for example a deep dive with /codebase-explainer <folder> or a walkthrough of another flow.