| name | onboarding-and-archaeology |
| description | Ramp up quickly on an unfamiliar codebase by reading strategically, mapping invariants, and making safe first changes. Use when joining a project, reviewing a legacy system, or orienting in a large monorepo. |
| license | Apache-2.0 |
| compatibility | Works with coding agents that support Agent Skills. |
| metadata | {"agentpacks.version":"0.1.0"} |
Onboarding and Code Archaeology
An unfamiliar codebase is an archaeological site. Read the strata before you dig.
Orientation Pass (First Hour)
- Start with the entry point:
main, index, app.py, cmd/. Follow the startup sequence to understand what the process does before it handles any request.
- Read
CLAUDE.md, CONTRIBUTING.md, README.md, and any docs/ folder. These record decisions that are no longer visible in the code.
- Check the CI definition (
.github/workflows/, .circleci/, Makefile). The build steps tell you what the maintainers consider essential.
git log --oneline -50 gives you recent momentum: what changed, at what frequency, and by whom.git log --oneline --follow -- <file> on the most-changed file shows what's been fought over.
Mapping the System
- Draw a box diagram of the major components from
git log and directory structure before reading any code deeply. Hypothesize, then verify.
- Identify the seams: where do modules call each other? Grep for import statements and function call sites to find the dependency graph.
- Find the data model first — it's the stable substrate everything else is built on. Schema files, ORM models, and proto definitions are high-leverage reads.
- Identify the top-level invariants: what must always be true? Look for comments marked
// INVARIANT, // IMPORTANT, // NOTE, panics, and assertions — they mark the load-bearing assumptions.
Reading Code Strategically
- Read tests before implementation. Tests document intended behavior and reveal edge cases the author thought about. Missing tests reveal gaps.
- Read the error paths as carefully as the happy path. Error handling often contains the most domain knowledge.
- When a function is surprising, read its git history (
git log -p -- <file>): the patch context explains why, not just what.
- Don't read everything. Spend the first day identifying which 20% of the code is responsible for 80% of the behavior — focus there.
Safe First Changes
- Before touching anything, add a test for the behavior you're about to change. If no test exists, write one that passes today. This is your safety net.
- Make the smallest possible change first: a one-line fix, a renamed variable, a new test. Running the full test suite on a trivial change validates your local setup.
- Prefer additive changes (new function, new flag) over modifications. Modifications break callers you haven't found yet.
- When changing behavior, use the expand-contract pattern: add the new path, migrate callers, delete the old path — three separate, reviewable steps.
- Flag your assumptions in PR descriptions: "I believe X is always true here because Y. If that's wrong, this change will break Z."
Asking the Right Questions
- Don't ask "what does this code do?" — read it. Ask "why does it do it this way?" and "what would break if it did it differently?"
- When something looks wrong, assume you're missing context before assuming it's a bug. Check git blame, linked issues, and ADRs first.
- Document what you learn in the code or in ADRs as you go — future contributors (including you in 6 months) will have the same questions.
Checklist
