What this prompt does
This prompt makes the AI a staff engineer that analyzes a [framework] codebase and writes a comprehensive onboarding guide for a new developer. You provide the [project_name], the [team_size], and the [domain], and it produces seven sections: an architecture overview, local development setup, codebase conventions, key domain concepts, the development workflow, a first-tasks roadmap, and gotchas and tribal knowledge. The guide is structured to take someone from git clone to a first meaningful contribution.
The structure works because it captures what is normally explained verbally and lost. The architecture section gives a 30,000-foot view plus the request lifecycle and a text data-flow diagram. The conventions section documents what the team does differently from framework defaults, steered by [convention_focus]. The gotchas section surfaces intentional confusion and tech-debt landmines, including whatever you flag in [additional_gotcha]. The first-tasks roadmap, with a safe starter PR and week-by-week goals, is what actually gets a new developer productive fast.
When to use it
- You are handing a codebase to a new team or client and need onboarding docs
- You want conventions and gotchas surfaced from the actual code, not your fading memory
- You need a safe first-PR suggestion and a week-by-week ramp plan
- You want the request lifecycle and data flow documented for newcomers
- You need a domain glossary so a new dev understands the team's vocabulary
- You want tech-debt and performance-sensitive areas flagged before someone breaks them
Example output
You get a structured onboarding document with the seven sections, clear headings, code examples drawn from the actual codebase, and references to relevant files. It includes a text-based data-flow diagram, a setup walkthrough with env-var explanations (not values), a domain glossary, a first-tasks roadmap, and a tribal-knowledge section covering intentional quirks and tech debt.
Pro tips
- Set
[framework]accurately so the request-lifecycle and convention sections match how your stack actually routes - Make
[domain]specific so the glossary and business-rules sections reflect real entities, not placeholders - Use
[convention_focus]to spotlight your trickiest area, like Filament resource patterns - Flag the real trap in
[additional_gotcha], such as a model reused intentionally that newcomers try to split - Run it with the codebase actually available to the AI so the file references and examples are real, not invented
- Verify the setup steps on a genuinely fresh machine; onboarding docs rot fastest at the install stage
