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.
1---2name: repo-onboarding3description: 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?".4license: MIT5---67# repo-onboarding89Resist editing until you can answer: *how do I run it, how do I test it, where10does the change go, and what style does this house write in?*1112## Procedure (15 minutes, in order)13141. **The README + manifest first.** `README.md`, then the manifest15 (`package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`): name, scripts,16 dependencies. The `scripts` block is the repo telling you its verbs.172. **Find the entry points.** `bin`/`main` fields, `src/index.*`, `cmd/`,18 `__main__.py`. Trace one request/command end-to-end at skim depth — names19 only, no line-reading.203. **Establish the test loop before touching anything.** Run the test command;21 record how long it takes and whether it's green at HEAD. A red baseline22 changes everything you conclude later.234. **Map the directories** (one line each, only top two levels). Mark the ones24 that are generated/vendored so you never read them again.255. **Sample the house style.** Open the 2–3 most-recently-changed source files26 (`git log --name-only -10`): error handling pattern, naming, comment density,27 test structure. Your changes should be indistinguishable from these.286. **Find the seams.** Where does config enter? Where is I/O isolated? What is29 the one module everything imports? That module is load-bearing — changes30 there need the most care.317. **Check the repo's own rules:** `CONTRIBUTING.md`, `CLAUDE.md`, `.github/`32 workflows (what CI actually enforces), lint configs.3334## Output3536Write a short map (10–20 lines) before starting the actual task:3738```39run: npm start (src/cli.js) test: npm test, ~6s, green at HEAD40flow: cli.js → commands/* → store.js (all persistence) → index.json41style: ESM, no deps, errors thrown as plain Error, tests in test/*.test.js42care: store.js is imported everywhere; schema changes ripple43rules: CI runs lint+test on 3 OS; commits are conventional44```4546Keep it honest — list what you *didn't* look at, so later-you knows where the47map has blank spots.
jnMetaCode