Codebase Onboarding skill for Claude Code

Onboarding is done when you can build and test the project, trace one real request or command end to end with file paths, name the main modules and what owns what, and hand over a one-page note that someone else can verify. Read selectively; a map beats a summary of every file.

Ground rules

• Breadth first, then one deep trace. Do not read files top to bottom until you know which ones matter.
• Every claim in the architecture note cites a file path (and ideally a symbol). If you inferred something, label it as inferred.
• Run the build and test commands; documentation is often stale. Record what actually worked, including required env vars and service dependencies.
• Do not change code during onboarding except throwaway experiments on a scratch branch.
• Stop exploring when the user’s question is answered; full coverage is not the goal.

Workflow

- [ ] 1. Orient: size, languages, manifests, CI
- [ ] 2. Read the docs that exist (fast, skeptical)
- [ ] 3. Get it building and testing
- [ ] 4. Find entry points
- [ ] 5. Trace one real flow end to end
- [ ] 6. Map modules, boundaries, and data
- [ ] 7. Note conventions and hotspots
- [ ] 8. Write the architecture note

1. Orient

Run the bundled map script, then fill gaps by hand:

python3 scripts/repo_map.py <repo_dir>            # languages, dirs, manifests, CI, entry points
python3 scripts/repo_map.py <repo_dir> --depth 4  # deeper for monorepos
git log --oneline -20                              # recent activity and commit style
git shortlog -sn --since="1 year ago" | head      # who knows the code
git ls-files | wc -l

Classify the repo early; it decides where to look next:

Signals	Kind	Look next at
pnpm-workspace.yaml, turbo.json, nx.json, go.work, Cargo [workspace]	Monorepo	Package list and dependency graph (see monorepo-navigation)
next.config.*, app/ or pages/	Next.js app	app/**/page.tsx, route.ts, middleware.ts
manage.py, settings.py	Django	urls.py, INSTALLED_APPS, models
main.go under cmd/<name>/	Go service/CLI	cmd/*/main.go, internal/
src/main/java, @SpringBootApplication	Spring Boot	Application class, controllers, application.yml
config/routes.rb	Rails	Routes, controllers, db/schema.rb
bin in package.json, [project.scripts]	CLI tool	The bin target and its argument parser
Dockerfile, compose.yaml, k8s/, terraform/	Deployed service	Startup command, env vars, external dependencies

2. Read existing docs (skeptically)

Read in this order and stop when you have enough: README*, CONTRIBUTING*, docs/ index, CLAUDE.md/AGENTS.md, ADRs (docs/adr, docs/decisions), the CI workflow (it is the most honest build documentation). Note contradictions between docs and CI.

3. Build and test

Use the commands CI uses. Typical discovery:

cat package.json | sed -n '/"scripts"/,/}/p'       # npm/pnpm scripts
grep -E '^[a-zA-Z_-]+:' Makefile                    # make targets
sed -n '/jobs:/,$p' .github/workflows/*.yml | grep -E 'run:' 

Record: toolchain versions (.nvmrc, .tool-versions, .python-version, go.mod go line), install command, env vars needed (.env.example), services needed (DB, Redis, queues via compose.yaml), and the fastest single-test command. If the build fails, capture the error and the fix; it goes in the note.

4. Find entry points

Entry points are where control enters the system. List all kinds that exist:

• HTTP: route registrations (app.get(, router., @Get(, urls.py, routes.rb, app/**/route.ts).
• CLI: bin targets, argparse/click/typer/cobra/clap definitions.
• Background: queue consumers, cron/scheduled jobs, event handlers, webhooks.
• UI: router config or file-based routes; the root layout.
• Startup: main(), server bootstrap, DI container setup, migrations on boot.

grep -rnE "app\.(get|post|put|delete|use)\(|router\.(get|post)|@(Get|Post|Controller)\(" src | head -40
grep -rnE "add_parser|@click\.command|cobra\.Command|#\[derive\(Parser" --include=*.{py,go,rs} . | head
grep -rnE "cron|schedule|consumer|subscribe\(|@task|@shared_task" --include=*.{ts,js,py,go,rb} . | head

5. Trace one real flow

Pick the flow the user cares about, or the most central one (sign-in, checkout, the main CLI command). Follow it from entry to persistence and back:

1. Entry handler: file:line.
2. Validation and auth: where and how.
3. Business logic: which module/service owns the decision.
4. Persistence or external calls: which repository/client, which tables/APIs.
5. Response or side effects: events emitted, jobs enqueued, caches touched.

Use the editor’s go-to-definition or grep -rn "functionName"; for dynamic dispatch (DI containers, event buses, decorators), search for registration sites. When static reading stalls, run the flow with a breakpoint or a temporary log line on a scratch branch to confirm the path.

6. Map modules, boundaries, and data

• Modules: top-level packages/directories and a one-line responsibility each. Note which ones import which (grep -rn "from '@/billing" src | cut -d: -f1 | sort -u).
• Boundaries: where layering is enforced (lint rules, package exports, Nx tags) versus merely conventional.
• Data: schema source of truth (schema.prisma, db/schema.rb, migrations dir, models.py), main entities and their relationships, other datastores (cache, search, object storage), and external services (from env var names and client libraries).

Draw only what helps; a short Mermaid diagram of the main containers is usually enough:

flowchart LR
  web[Next.js web] --> api[API routes]
  api --> svc[billing service]
  svc --> db[(Postgres)]
  svc --> stripe[Stripe API]
  api --> q[[BullMQ jobs]] --> worker[worker]

7. Conventions and hotspots

• Conventions: error handling style, logging, config loading, test layout and naming, dependency injection, naming patterns. Copy them when you later write code.
• Hotspots: most-changed files are where bugs and context live.

git log --since="6 months ago" --name-only --format= | grep -v '^$' | sort | uniq -c | sort -rn | head -15

• Landmines: TODO/FIXME/HACK density, disabled tests, files over ~1000 lines, generated code that must not be edited by hand (look for “DO NOT EDIT” headers).

8. Write the architecture note

Keep it to about one page. Template:

# <Project> — architecture note
_Written <date> from commit <sha>. Inferred items marked (inferred)._

## What it is
<One paragraph: purpose, users, deployment shape.>

## Run it
- Toolchain: Node 22 (.nvmrc), pnpm 10
- Setup: `pnpm install && cp .env.example .env && docker compose up -d db`
- Dev: `pnpm dev` (http://localhost:3000)
- Test: `pnpm test` (all), `pnpm vitest run path/to/file.test.ts` (one)
- Gotchas: needs `STRIPE_SECRET_KEY` set to any value or boot fails (src/env.ts:12)

## Map
| Area | Path | Responsibility |
|---|---|---|
| Web UI | apps/web | Next.js App Router frontend |
| Billing | packages/billing | Plans, proration, Stripe sync |

## Request flow: <name>
1. `apps/web/app/api/checkout/route.ts:POST` validates body with Zod
2. calls `createCheckout()` in `packages/billing/src/checkout.ts:40`
3. ...

## Data
<Source of truth for schema, main entities, other stores, external APIs.>

## Conventions
<Errors, logging, tests, naming — the things to copy.>

## Hotspots and risks
<Most-churned files, fragile areas, missing tests.>

## Open questions
<Things you could not determine; who might know (from git shortlog).>

Save it where the user wants (default: present it in chat; offer docs/architecture.md).

Gotchas

• README build steps that differ from CI: trust CI, then tell the user the README is stale.
• Generated directories (generated/, __generated__, *.pb.go, OpenAPI clients) inflate line counts and mislead tracing; find the generator source instead.
• Framework magic hides entry points: file-based routing, decorators, autoloading, DI containers. Search for registration, not just calls.
• Monorepos often have one “real” app and many stale packages; check commit recency per package before mapping all of them.
• Env-specific behavior (feature flags, NODE_ENV branches) changes the flow; note which configuration your trace assumed.

Verification

• Build and fastest test command were actually run, with results recorded.
• Pick two claims from the note at random and confirm them by opening the cited files.
• The traced flow can be re-followed by someone else using only the file:line list.
• Open questions are listed rather than guessed.