Codebase onboarding

Codebase Onboarding

Purpose

Turn an unknown repository into a working mental model in minutes, not hours, by reading artifacts in a fixed high-signal order instead of wandering. The output is a map: what the project does, how it builds and runs, where the entry points are, what is tested, and which patterns are deliberate convention versus accident.

When to Use / When NOT to Use

Use when:

• You are about to make your first change in a repository you have not read.
• Asked to summarize, audit, or evaluate an unfamiliar project.
• A task references files or modules you cannot yet place in the system.
• Resuming work on a repo after long enough that your model may be stale.

Do NOT use when:

• You need to understand why the code is the way it is (past incidents, reverts, hardening arcs) → load failure-archaeology.
• You need to judge module boundaries, error taxonomies, or data flow in depth → load architecture-analysis.
• You are hunting a specific bug, not building a map → load debugging-playbook.
• The question is only about dependencies or lockfiles → load dependency-management.

Core Methodology

Read in this order. Each step answers one question; stop reading a file once the question is answered.

1. README — What does this claim to be? Note install command, run command, and any threat model or design-doctrine statements. A written threat model in a README is a load-bearing document, not marketing.
2. Build/package config (pyproject.toml, package.json, Cargo.toml, pnpm-workspace.yaml) — What language/version, what dependencies (count them — few is a signal of deliberate minimalism, many is a signal of accretion), what scripts/entry points are declared, is it a workspace/monorepo?
3. Environment surface (.env.example, config module) — Every env var is an external coupling: services, secrets, tunables. This is the fastest inventory of what the system talks to.
4. Entry points — The [project.scripts] / bin / main declared in step 2. Read the entry file top to bottom; it shows startup order and the module dependency direction.
5. Tests — What is tested reveals what the authors fear. Note test-to-code ratio and where tests concentrate. A repo with only security tests made a risk decision; record it, don't judge it yet.
6. CI config (.github/workflows/, .gitlab-ci.yml) — What is enforced vs. merely documented. Absence of CI means every README claim is unverified by machinery — trust build/test commands only after running them.
7. Git history, first and last 10 commits — git log --oneline | head and | tail. First commits show the intended skeleton; recent commits show current concerns. Full mining is failure-archaeology's job; here you only want the arc.
8. Directory map — Now, and only now, list the tree. With steps 1–7 done, every directory should be nameable in one sentence. Any directory you cannot explain is your next read.

Decision tree: where to start reading

Is there a README?
├─ yes → read it first; does it name a run command?
│        ├─ yes → find that command's target in build config → that file is the entry point
│        └─ no  → build config scripts/bin section is your entry-point index
└─ no  → build config → declared entry points → largest source file in the
         top-level package → tests (they demonstrate intended usage)
Is it a workspace/monorepo (pnpm-workspace.yaml, cargo workspace, packages/)?
├─ yes → onboard the leaf package the task touches FIRST, root config second;
│        note cross-package version/publish coupling explicitly
└─ no  → proceed linearly through steps 1–8

Convention vs. accident

A pattern is convention (imitate it) if at least two of these hold; otherwise treat it as accident (do not propagate) until proven:

• It appears in 3+ files or in every instance of its situation.
• It is named in README, comments, or a commit message.
• A test enforces it.
• It survived a refactor (visible in git history).

Example conventions worth spotting: frozen dataclasses everywhere = immutability doctrine; custom exception classes with actionable messages = deliberate error UX; zero TODO/FIXME markers = the authors finish or delete, so don't introduce TODOs.

Onboarding checklist

• Can state the project's purpose in one sentence without the README open.
• Know the exact install, run, and test commands (and have run the test command if permitted).
• Can list every env var / external service the system touches.
• Can name the entry point file and the module dependency direction.
• Know where tests concentrate and what is deliberately untested.
• Know whether CI exists and what it enforces (possibly: nothing).
• Have listed 3 conventions to imitate and any accidents to avoid.
• Every top-level directory explained in one sentence.

Discovery Commands

All repo-agnostic; run from the repo root.

# Steps 1-2: identity and build surface
ls -a
cat README.md
cat pyproject.toml package.json Cargo.toml 2>/dev/null   # whichever exists

# Step 3: environment surface
cat .env.example 2>/dev/null
grep -rn "os.environ\|getenv" --include="*.py" .           # Python
grep -rn "process.env" --include="*.ts" --include="*.js" . # Node

# Step 4: entry points
grep -n "scripts" pyproject.toml 2>/dev/null
grep -n '"bin"\|"main"\|"scripts"' package.json 2>/dev/null

# Step 5: tests
find . -path ./node_modules -prune -o -name "*test*" -print
# run them ONLY after the trust gate below: pytest tests/  |  npm test  |  cargo test

# Step 6: CI
ls .github/workflows/ 2>/dev/null || echo "no GitHub CI"

# Step 7: history arc
git log --oneline | head -10
git log --oneline | tail -5
git log --oneline | wc -l

# Step 8: map + size
find . -path ./node_modules -prune -o -path ./.git -prune -o -type f \( -name "*.py" -o -name "*.ts" -o -name "*.rs" \) -print | xargs wc -l | sort -n

# Convention detection
grep -rn "frozen=True" --include="*.py" .
grep -rn "TODO\|FIXME" --include="*.py" --include="*.ts" . | wc -l

Trust gate — before running ANY command that executes repo-controlled code (npm install / npm test run postinstall hooks and arbitrary scripts; pip install -e . executes setup code; pytest imports conftest.py): confirm the repository's provenance is trusted, read package.json "scripts" / setup.py / conftest.py first, or run in a sandbox. Reading files is always safe; executing the repo is not.

Ecosystem variants: pip install -e . / npm install / pnpm install / cargo build for the build step; monorepos may need pnpm -r <cmd> or cargo build --workspace.

Failure Modes & Anti-patterns

Symptom	Mistake	Correction
Hours spent, no map	Reading files alphabetically or by directory order	Follow the fixed discovery order; each artifact answers one question
Confident but wrong run instructions	Trusting README with no CI verifying it	No CI = unverified claims; execute install/test commands before repeating them
New code clashes with house style	Skipped convention detection, imported personal defaults	Grep for repeated patterns first; imitate what appears 3+ times
"This repo has no error handling"	Judging by absence of your favorite pattern	Find the repo's own pattern (custom exceptions, observation strings) before declaring a gap
Missing half the system	Onboarding only the package the task names in a monorepo	Check for workspace files first; map package coupling before editing
Treating a hack as gospel	Copying a one-off workaround into new code	One occurrence + no test + no doc = accident; verify before propagating
"Untested = careless"	Assuming missing tests are an oversight	Tests may be concentrated on the highest-risk surface by choice; check what IS tested

Repository Examples

PRISM (~/prism, as of 2026-07-04). Python 3.10+ FastAPI AI code reviewer for GitHub PRs using local Ollama. The full discovery order runs in ~5 minutes: README → pyproject.toml (install pip install -e ., run prism) → .env.example inventories the entire external surface (GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET, OLLAMA_HOST default http://localhost:11434, OLLAMA_MODEL default llama3.2, MAX_FILES_PER_PR=10, MAX_LINES_PER_CHUNK=120) → five modules (prism/config.py, diff.py, github.py, reviewer.py, server.py) → tests are a single file, tests/test_security.py, run with pytest tests/ — a deliberate decision to test only the highest-risk surface → no CI → git log --oneline shows a 4-commit arc: e264a72 initial → b7bbabb README env-var reference → 51b92c9 security hardening → b011239 security tests. Conventions passing the test above: frozen dataclasses (Settings, Hunk, FileDiff, Chunk, InlineComment) with a get_settings() singleton, and zero TODO/FIXME markers.

AGENTIX (~/agentix, as of 2026-07-04). ~700-line local agent framework on Ollama; hatchling build, pip install -e ".[dev]", pytest. README states the threat model explicitly: "the security boundary is you and the model you point it at, not the code" — reading that sentence first reframes every security judgment about the code (e.g. the shell blocklist ["rm -rf /", "sudo", "mkfs"] is documented as a guardrail, NOT a boundary). Prerequisites live outside the package manager: ollama pull llama3.2 and ollama pull nomic-embed-text — README-only setup steps a build-config-first reader would miss. Tests (tests/test_agent.py, test_memory.py, test_tools.py) use only monkeypatch + tmp_path: a minimal-tooling convention to imitate.

RAGIT (~/ragit, as of 2026-07-04). Local RAG CLI (typer): python3 -m pip install -e .; commands models/index/chat/clear; files ragit/cli.py, indexer.py, llm.py, retriever.py. Zero tests and zero CI — combined with tight pins (chromadb>=0.4.0,<0.5.0, numpy<2.0) this tells the onboarder that the pins are the repo's regression defense and must not be "cleaned up". Runtime state lives at ~/.ragit/<sha256-prefix>/: an example of why grepping for home-directory paths belongs in onboarding.

RUFLO (~/ruflo, as of 2026-07-04). pnpm monorepo publishing three synchronized npm packages (@claude-flow/cli, the claude-flow umbrella, and the ruflo alias) at identical versions. Onboarding a single package here without reading the workspace root misses the version-sync and dist-tag coupling; internal docs mark the ruflo dist-tag "EASY TO FORGET".

Validation Criteria

You applied this skill correctly if:

• You can answer, without re-opening files: purpose, run command, test command, env-var list, entry point, test concentration, CI status.
• Your first change matched existing conventions with no style corrections needed.
• You correctly predicted where a named feature lives before opening the file (spot-check yourself twice).
• You flagged at least one deliberate absence (no CI, no tests, no TODO markers) as a decision rather than a defect.
• Total onboarding time for a <2k-line repo was under 15 minutes.

Provenance & Maintenance

• Sources: prism, agentix, ragit, orphy, NYTW, asver, ruflo at ~/<repo>, investigated 2026-07-04. Prism's commit history independently re-verified via git -C ~/prism log --oneline on 2026-07-04; other repo facts from the same-day investigation fact pack.
• Doctrine encoded: these repos are deliberately local-first (local Ollama, no cloud LLM), minimal-dependency, zero-CI, with security proportional to a written threat model. The methodology treats such absences as decisions to detect, not defects to fix.
• Assumptions: repos remain at the listed paths; standard git/grep/find available. Anything beyond the fact pack is marked "(hypothesis — requires verification)".
• Re-verification commands: git -C ~/prism log --oneline; cat ~/prism/.env.example; ls ~/agentix/tests; grep -n "chromadb\|numpy" ~/ragit/pyproject.toml.
• Likely to drift: commit counts and hashes as repos grow; env-var defaults; ruflo package list and versions; the "zero CI anywhere" claim (any repo may add CI).
• Maintenance checklist: quarterly — re-run the re-verification commands; update example hashes/paths; confirm cross-referenced skills (failure-archaeology, architecture-analysis, debugging-playbook, dependency-management) still exist under ~/.claude/skills/; delete any example whose repo no longer matches.