Raw view: Codebase onboarding map
No invisible, zero-width, or bidi-control characters detected.
---
name: codebase-onboarding
description: Builds a mental map of an unfamiliar repository (entry points, layers, data flow, build/test commands, conventions, hotspots) and writes it to a notes file for later sessions. Use when the user opens a new or unfamiliar codebase, asks "how does this project work", "where does X live", wants an architecture overview, or is onboarding onto a team repo.
license: CC0-1.0
allowed-tools: Bash(git log *) Bash(git ls-files *) Bash(git shortlog *) Bash(wc *) Bash(find *) Read Glob Grep
metadata:
author: Waxmark
version: "1.0.0"
---
# Codebase Onboarding
Goal: after 10-15 minutes of reading, be able to answer "where would I change X?" for the common cases, and leave notes so the next session does not start from zero.
## Procedure
Time-box each step. Breadth first; depth only where the map has a hole.
1. **Shape.** Size and language mix, then the top two directory levels.
```bash
git ls-files | wc -l
git ls-files | sed 's|/.*||' | sort | uniq -c | sort -rn | head -20
git ls-files | awk -F. 'NF>1{print $NF}' | sort | uniq -c | sort -rn | head -10
```
2. **Front door.** Read, in order, whichever exist: `README*`, `CONTRIBUTING*`, `CLAUDE.md`/`AGENTS.md`, `docs/`, `Makefile`/`justfile`/`package.json` scripts, `Dockerfile`, CI workflow. Extract the exact commands to install, build, test, lint, and run. If two sources disagree, trust CI.
3. **Entry points.** Find where execution starts: `main.*`, `index.*`, `app.*`, `cmd/`, `bin/`, framework routers, `__main__`, `fn main`. Follow one request or command end-to-end and name each layer it crosses.
4. **Data model.** Locate schema, migrations, ORM models, or protobuf/OpenAPI definitions. List the 5-10 core entities and how they relate.
5. **Conventions.** Sample three files from different areas and note: naming, error handling style, logging, DI/wiring, test layout (`__tests__/`, `*_test.go`, `tests/`), and any lint config that encodes rules.
6. **Hotspots and history.** Where change concentrates is where bugs live.
```bash
git log --since=6.months --format= --name-only | sort | uniq -c | sort -rn | head -15
git shortlog -sn --since=1.year | head -5
git log --oneline -20
```
7. **Open questions.** Anything you could not resolve in the time box goes in the notes as a question, not a guess.
## Write the notes file
Write to `{{NOTES_PATH}}` (default `docs/ONBOARDING-NOTES.md`; use `.claude/notes/onboarding.md` if the repo has no `docs/`). Do not overwrite an existing file; append a dated section instead.
```markdown
# Onboarding notes - <repo> - <YYYY-MM-DD>
## One paragraph
<What it is, who uses it, the main runtime shape (CLI / service / library / monorepo).>
## Commands
- Install: `...`
- Test: `...` (full) / `...` (single file)
- Lint/format: `...`
- Run locally: `...`
## Map
| Area | Path | Notes |
|---|---|---|
| HTTP entry | `src/server.ts` | Express; routes mounted in `routes/index.ts` |
| ... | | |
## One request, end to end
`POST /orders` -> `routes/orders.ts` -> `OrderService.create` -> `OrderRepo.insert` -> `migrations/00xx`
## Core entities
User, Org, Order(items[]), Payment -> Order
## Conventions
- Errors: thrown `AppError(code, status)`; handled in `middleware/error.ts`
- Tests: colocated `*.test.ts`, Vitest, factories in `tests/factories/`
## Hotspots (last 6 months)
1. `src/billing/invoice.ts` (41 commits)
2. ...
## Open questions
- Why two HTTP clients (`axios` and `undici`)?
```
## Output to the user
After writing the file, reply with the path, the one-paragraph summary, the commands block, and the open questions. Nothing else; the file holds the detail.