| name | repo-onboarding |
| description | Systematically map an unfamiliar codebase before changing it — entry points, build/test loop, conventions, data flow. Use when starting work in a repo you haven't seen, or asked "how does this codebase work?". |
| version | 1.0.0 |
| license | MIT |
| keywords | ["onboarding","codebase","exploration","architecture","conventions"] |
repo-onboarding
Resist editing until you can answer: how do I run it, how do I test it, where
does the change go, and what style does this house write in?
Procedure (15 minutes, in order)
- The README + manifest first.
README.md, then the manifest
(package.json / pyproject.toml / go.mod / Cargo.toml): name, scripts,
dependencies. The scripts block is the repo telling you its verbs.
- Find the entry points.
bin/main fields, src/index.*, cmd/,
__main__.py. Trace one request/command end-to-end at skim depth — names
only, no line-reading.
- Establish the test loop before touching anything. Run the test command;
record how long it takes and whether it's green at HEAD. A red baseline
changes everything you conclude later.
- Map the directories (one line each, only top two levels). Mark the ones
that are generated/vendored so you never read them again.
- Sample the house style. Open the 2–3 most-recently-changed source files
(
git log --name-only -10): error handling pattern, naming, comment density,
test structure. Your changes should be indistinguishable from these.
- Find the seams. Where does config enter? Where is I/O isolated? What is
the one module everything imports? That module is load-bearing — changes
there need the most care.
- Check the repo's own rules:
CONTRIBUTING.md, CLAUDE.md, .github/
workflows (what CI actually enforces), lint configs.
Output
Write a short map (10–20 lines) before starting the actual task:
run: npm start (src/cli.js) test: npm test, ~6s, green at HEAD
flow: cli.js → commands/* → store.js (all persistence) → index.json
style: ESM, no deps, errors thrown as plain Error, tests in test/*.test.js
care: store.js is imported everywhere; schema changes ripple
rules: CI runs lint+test on 3 OS; commits are conventional
Keep it honest — list what you didn't look at, so later-you knows where the
map has blank spots.
