Codebase Onboarding

Codebase onboarding — get oriented fast, leave a map

You have just landed in a codebase you did not write: a fresh clone, an inherited project, an acquired repo, an abandoned side project someone handed you. The instinct is to start reading files top-to-bottom. Resist it. That is how a week disappears and you still cannot answer "where does X happen". This skill runs a disciplined breadth-first reconnaissance pass and produces one durable artifact: a map a teammate can trust and you can re-read tomorrow.

The payoff is measured. Engineers using AI to onboard reach the same milestones roughly 2x faster — productive in 1–2 weeks instead of 4–6 — and the biggest gains are exactly in searching for code, decoding undocumented patterns, and tracing data flows (super-productivity.com, accessed 2026-06-02). That is what the recon pass below targets, in order.

Lead with the deliverable

Before you grep a single line, know the target: a single living file, CODEBASE-MAP.md, committed at the repo root. You work backward from its sections — every recon step fills one. Minimal schema:

markdownCopy code
# CODEBASE-MAP.md — <repo name>

## Stack          # languages, framework + versions, package manager, run scripts
## Entry points   # main / server bootstrap / route registration / CLI commands
## Request flow   # one real path traced transport -> business logic -> persistence
## Module ownership   # who owns transport / business logic / persistence / UI
## Hidden behavior    # cron, webhooks, queue workers, event listeners, env branches
## Hotspots       # most-churned + most-complex files = highest risk
## How to run     # the exact commands to boot it and hit one path locally

Why a file and not a chat answer: a map that lives only in the conversation dies when the session ends, and the next agent re-does the work. The artifact is the point. verify.sh checks these sections exist (structure, not content).

Two operating rules

1. Breadth before depth. First pass maps where things are, not how they work. You are drawing the subway map, not reading every passenger's diary. Depth is analyze/debug work, on demand, later. — Reading everything is the failure mode onboarding exists to replace.
2. Hypothesis before answer. Spend ~5 minutes forming your own guess ("auth probably lives in src/middleware"), then grep to confirm or kill it. — Verifying a hypothesis builds the mental model that makes you fast; a handed-to-you answer does not stick (martinfowler.com, Böckeler, accessed 2026-06-02).

The recon pass — ordered

Run these in order. Each step writes one map section. Stop escalating the moment the section is answerable.

a. Orient — read the manifest, size the repo. Read the manifest(s) and lockfile, not the README first: package.json / pyproject.toml / go.mod / Gemfile / pom.xml tell you the real stack, framework version and run scripts; the lockfile tells you what is actually installed. Then size it:

bashCopy code
scc --by-file --sort lines .   # LOC, complexity, COCOMO estimate per file

scc (Sloc Cloc and Code, pure-Go, v3.7.0 Apr 2026) is the fast structural counter of record — materially faster than cloc/tokei and it reports per-file complexity, which you reuse for hotspots. Why manifest-first: the README describes intent (often stale); the manifest describes reality.

b. Find the entry points. Where does execution start? Look for main, the server bootstrap, route registration, CLI command definitions. Let the framework's convention guide you (Next.js app//pages/, Express app.use/router mounts, Django urls.py, FastAPI @app/APIRouter, Rails routes.rb, Spring @RestController). See references/recon-playbook.md for per-ecosystem patterns.

c. Trace one real request end-to-end. Pick a single meaningful path (a login, a checkout, the main CLI command) and follow it: transport (route/handler) → business logic → persistence → response. One path traced beats ten skimmed. This is the spine of the map.

d. Map module ownership. For the directories scc flagged as large, label each: transport, business logic, persistence, UI, shared/util. You are answering "if I need to change pricing, which folder do I open" — the question teammates actually ask.

e. Hunt hidden behavior. The bugs live in what runs without a request. Grep for cron schedules, webhook receivers, queue/background workers, event listeners and env-driven branches (see the appendix). Why this step is non-negotiable: side effects are invisible in a top-down read and they are where inherited codebases bite.

f. Rank hotspots. Git churn is the cheapest risk signal — no extra tooling, and high-churn files are a proxy for "lacks tests/abstraction":

bashCopy code
git log --format=format: --name-only --since=12.month \
  | grep -v '^$' | sort | uniq -c | sort -nr | head -50

The richer move is churn × complexity: the top-right quadrant (changes constantly and is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough: references/recon-playbook.md has the churn×complexity recipe (code-maat) and when codegraph PageRank / FileScopeMCP earn their setup cost.

g. Confirm hands-on. Run the app, walk one end-user journey, send a real request, watch the logs. Reading alone leaves the map unverified; a single real request validates the whole trace in step c.

Scope the effort

Match the pass to the repo. Do not stand up heavy tooling on a small project.

Command appendix

Language-tagged, copy-ready. Per-ecosystem depth lives in references/recon-playbook.md.

bashCopy code
# Size + complexity (reuse the complexity column for hotspots)
scc --by-file --sort complexity .

# Route registration (adjust per framework)
rg -n "app\.(get|post|put|delete|use)\(|@app\.(get|post)|APIRouter|router\.(get|post)" --type-add 'web:*.{js,ts,py}' -tweb

# Cron / scheduled jobs
rg -n "cron|schedule|@scheduled|setInterval|celery\.beat|node-cron" -i

# Webhook receivers
rg -n "webhook|/hooks/|stripe.*signature|x-hub-signature" -i

# Queue / background workers
rg -n "queue|worker|bull|sidekiq|celery|sqs|rabbitmq|kafka|@task" -i

# Env-driven branches (hidden config-conditional behavior)
rg -n "process\.env\.|os\.environ|ENV\[|getenv" 

Writing & maintaining the map

• Commit it. CODEBASE-MAP.md at the repo root, in version control. A map outside the repo rots silently.
• Keep it living. When the recon reveals you guessed wrong, fix the line — the map is the record of what is true now, not your first impression.
• Link out, do not duplicate. The map says what is. For why a choice was made, write an ADR (../decision-records/SKILL.md). To scaffold project tooling and a wiki, that is ../harness/SKILL.md. To write the agent-memory CLAUDE.md, that is ../init/SKILL.md — onboarding is the broader recon that feeds it. For generic note/wiki capture, ../knowledge-ops/SKILL.md.
• Hand off to depth tools. Once the map exists, a deep correctness/security read of one module is ../analyze/SKILL.md; chasing a specific failure through the system is ../debug/SKILL.md. Onboarding builds the map you debug with.

Anti-patterns