--- name: codebase-onboarding-map description: Produce an accurate orientation guide to an unfamiliar codebase — how a request flows end to end, where the real rules live, what the traps are, and what to read first — grounded in the code rather than the README. Use when joining a project, inheriting a repo, returning to old code, or onboarding someone else. --- # Codebase Onboarding Map ## Install Save this file as `~/.claude/skills/codebase-onboarding-map/SKILL.md`, or `.claude/skills/codebase-onboarding-map/SKILL.md` to scope it to one repo. Claude Code auto-discovers it. Invoke with `/codebase-onboarding-map` or by asking "help me understand this codebase". ## Why this exists The expensive part of a new codebase is not reading it. It is not knowing which 10% matters, which parts are load-bearing, and which comment is a lie left over from a refactor two years ago. READMEs describe intent at the moment someone had time to write. Code describes what is true now. Where they disagree, the code wins, and the gap between them is one of the most useful things you can hand a newcomer. **This produces a map, not a summary.** A summary tells someone what exists. A map tells them where to go and what will hurt. ## Step 1 — Establish the shape before reading anything deeply ``` git log --oneline -20 git log --format='%an' | sort | uniq -c | sort -rn | head cat package.json 2>/dev/null || cat pyproject.toml go.mod Cargo.toml Gemfile 2>/dev/null rg --files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -25 ``` You are answering: what kind of project, what stack, how many people, still moving or dormant, and which directories carry the weight. Directory file counts beat any architecture diagram, because they are generated from reality. ## Step 2 — Trace ONE request end to end This single step teaches more than any amount of file browsing. Pick the most representative user action (a page load, an API call, a job) and follow it all the way down, naming the real files: entry point → routing → auth → validation → business logic → data access → response Write it as a numbered path with `file:line` at each hop. When you hit a helper that seems important, open it rather than assuming from the name. Then do it a second time for a WRITE path, because reads and writes usually pass through different guards, and the interesting rules live on the write side. ## Step 3 — Find where the real rules live Every codebase has a few files where violating them breaks things badly. They are rarely the biggest files. Look for: - **Single sources of truth.** A pricing constant, a permissions table, a status enum. `rg -n "export const [A-Z_]{4,}"` finds many of them. - **Choke points.** Modules imported nearly everywhere. High import counts mean high blast radius: ``` rg -o "from ['\"](@/[^'\"]+|\.\./[^'\"]+)['\"]" -r '$1' | sort | uniq -c | sort -rn | head -15 ``` - **Guards.** Auth checks, validation schemas, rate limits, feature flags. - **The comments that sound like scar tissue.** Search for the tone of someone who got burned; these mark real traps: ``` rg -n "HACK|XXX|do not|don't|careful|NOTE:|WARNING|must|never|deliberately|on purpose" -g '!node_modules' ``` That last search is the highest-value grep in this skill. A comment saying "must stay in sync with X" or "deliberately not cached" encodes an incident someone already paid for. ## Step 4 — Find the traps Report these plainly, because they are what actually bites a newcomer: - **Duplicated logic that must agree.** Two places computing the same thing. - **Stale documentation.** Test the README's setup commands. If they fail, say so; that is the newcomer's first hour and it should not be spent debugging docs. - **Scripts that touch real infrastructure.** Anything that seeds, migrates, deploys, or sends. Note whether a guard stops it running against production. - **Dead code that looks alive.** Exported, plausible, imported by nothing: ``` rg -n "^export (function|const) (\w+)" -o -r '$2' | sort -u | while read -r s; do [ "$(rg -c "\b$s\b" | wc -l)" -le 1 ] && echo "possibly unused: $s" done ``` - **Conventions with no enforcement.** A pattern followed in 9 of 10 places is a trap for the person writing the eleventh. ## Step 5 — Write the map Structure it for someone with one hour, not one week: ``` # — orientation ## What it is Two sentences. What it does and who for. ## Stack + shape Language, framework, datastore, hosting. Directory count table. ## The path of one request 1. — ... ## Where the rules live - — ## Traps - ## Where docs and code disagree - says X; actually does Y. ## Read these five files first, in this order 1. — ``` Five files, ordered, with reasons. Fewer is more useful than a complete index nobody finishes. ## Rules - Cite `file:line`. An orientation guide that cannot be checked is a rumour. - Where the README and the code disagree, believe the code and record the gap. - Do not summarise every directory. Rank by what a newcomer will touch in week one. - Say plainly when something is a mess. A map that flatters the codebase gets someone hurt on their second day. - Verify each claim before writing it. Confident and wrong is the one failure mode that makes this worse than nothing.