Codebase onboarding map

Time-boxed procedure to map an unfamiliar repo (entry points, layers, entities, commands, hotspots) and persist it to a notes file.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/codebase-onboarding)](https://waxmark.app/items/codebase-onboarding/scan)
Report
---
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.
Codebase onboarding map · Waxmark