Write a codebase onboarding guide
Gives a reading order instead of trying to explain everything.
| Category | Development › Technical writing |
|---|---|
| Tags | DraftingChecklistDeveloper |
Write a codebase onboarding guide. Structure: 1. **The mental model** — what this system does, in the terms the team uses. Three or four sentences, including the two or three domain words that appear everywhere. 2. **Reading order** — five to eight files or modules, in order, with one line each on why it comes at that point. *Not a directory tour.* Someone who reads these should be able to follow a request end to end. 3. **Trace one path all the way through** — a single common operation from entry to storage to response. This teaches more than any diagram. 4. **Their first task**, broken into steps with which parts of the reading it needs. 5. **Where the surprises are** — the parts that do not work the way the naming suggests, the historical decisions that look wrong, the file everyone is afraid of. *This is the section that only exists in people's heads and is the most valuable thing here.* 6. Look it up when you need it — everything else, as a list, not explained. Rules: - Assume they can program and do not know this system. Do not explain the language. - *Do not attempt completeness.* Say explicitly what this guide leaves out. - Where I did not tell you something, mark it as a question for the team rather than guessing at how the code works. - Name who to ask for what.
After pasting, fill in the fields at the bottom (Codebase · Their first task · Team context)
What this prompt does
Onboarding docs fail by attempting completeness and going unread. This keeps only what the first week needs and demotes the rest to a look-it-up list.
More in this category
| Act as an FTTH Telecommunications Expert | |
| Architect Guide for Programmers | |
| Beginner's Guide to Building and Deploying LLMs | |
| Building a Comprehensive Programming Team | |
| CLAUDE.md Assembly |