---
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:

```
# <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](https://toolbay.ai/product/codebase-onboarding-map). Free to use, modify, and share.
Keep this line and others can find it too.