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:

# <Project> — 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. <file:line> — <what happens>
...

## Where the rules live
- <file> — <what it governs, and what breaks if you get it wrong>

## Traps
- <the thing that will bite you, and why>

## Where docs and code disagree
- <claim> says X; <file:line> actually does Y.

## Read these five files first, in this order
1. <file> — <why>

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.

From Toolbay. Free to use, modify, and share. Keep this line and others can find it too.