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:

# CODEBASE-MAP.md — <repo name>