project-onboarding-context
verified95aec968-5f90-40bd-8c17-03beebb606c1
Build a mental map of an unfamiliar repo before editing it — read AGENTS.md/README, structure, tests, and conventions. Use on first contact with a codebase.
Metadata
Skill file
# Project Onboarding Context
Use on first contact with a codebase you have never seen. Fifteen minutes of
oriented reading saves hours of editing blind based on filenames. The goal is a
mental map: entry points, data model, conventions, and where your change will
actually live.
## 1. The read order (do it in this order)
```text
1. AGENTS.md / CLAUDE.md / .cursorrules -> agent + project conventions (if present)
2. CONTRIBUTING.md -> how changes are expected to be made
3. README.md -> what the project is, how to run it
4. Top-level directory tree -> the lay of the land
5. Test layout -> where tests live and how they're named
6. Build/run commands -> the exact commands to build and test
7. Recent git log -> what's actively being worked on
```
```bash
# 4. Directory tree (depth-limited, not a full dump)
find . -maxdepth 2 -type d -not -path '*/.git*' -not -path '*/node_modules*' | sort
# 5. Test layout
find . -path '*test*' -name '*.py' | head -30 # or *_test.go, *.spec.ts, etc.
# 6. Build/run commands (from README, Makefile, pyproject, package.json)
cat Makefile 2>/dev/null || cat pyproject.toml 2>/dev/null || cat package.json
# 7. Recent history — what is active, who is doing what
git log --oneline -15
```
## 2. Identify the three things you must find
| Thing | How to find it | Why it matters |
|---|---|---|
| **Entry points** | `if __name__ == "__main__"`, `main()` funcs, `routes/`, `cmd/`, `app/` | Where execution starts; where to add a feature |
| **Data model** | `models/`, `schema/`, `migrations/`, `entities/`, `*.sql` | The shape of the domain; what "a user" or "an order" is |
| **Where your change lives** | Follow the entry point to the module that owns the concern | The specific file(s) you will actually edit |
Do not stop at "it's a FastAPI app." Find the *specific* file your change touches
before you start editing.
## 3. Run the baseline first
Before touching anything, confirm the tree is green:
```bash
pytest -q # Python
# or: go test ./... / cargo test / npm test / yarn test
# or: make test
```
If the baseline is **red**, note it immediately — you did not break it, and you
must not be blamed for it (or waste time "fixing" pre-existing failures). If it
is green, you now have a safety net for your changes.
## 4. Read a small representative slice
After the map, read one real example end-to-end before editing:
- One model + one migration + one endpoint + its test, or
- One function + its callers + its test.
This teaches the *idioms* (naming, error handling, test style) far better than
reading any number of docs.
## Guardrails
- Do **not** edit blind based on filenames. A file named `user.py` may be the model,
the service, or a stale utility. Read before editing.
- Do **not** skip the baseline test run. Inheriting a pre-broken tree without
knowing it wastes hours.
- Do **not** dump the whole tree or read every file — onboarding is about a *map*,
not a full read-through. Read strategically.
- Do check for `AGENTS.md`/`CLAUDE.md`/`.cursorrules` first — they encode conventions
that override generic defaults.
## Pitfalls
- **Editing blind** — you guess where the code lives from filenames and end up
patching the wrong layer.
- **Skipping the baseline test run** — you make a change, tests fail, and you can't
tell whether you broke it or it was already broken.
- **No mental map** — you read a few random files but cannot say where the entry
point is or how data flows.
- **Ignoring agent/convention files** — `AGENTS.md` says "always use X" and you
ignored it, producing a change that violates project norms.
- **Over-reading** — spending three hours reading every file and never writing
code; onboarding is bounded, not exhaustive.
## Verify / Checklist
- [ ] Read AGENTS.md / CONTRIBUTING / README (whichever exist).
- [ ] Viewed the top-level directory tree and test layout.
- [ ] Identified entry points, the data model, and the specific files your change touches.
- [ ] Ran the test suite / build and recorded whether the baseline is green or red.
- [ ] Read one representative model→endpoint→test slice to learn idioms.
- [ ] Confirmed build/run commands (Makefile / pyproject / package.json).
- [ ] Can state in one sentence: what the project does, how it is structured, and where your change lives.Attached files
No attached files.