What this prompt does
This prompt generates a real, commit-ready README from a repo's details rather than a template skeleton. It casts the assistant as a senior developer-experience engineer and takes four context variables: [repo_name] and [description], [stack], and [reader] (the primary audience). The deliverables are a title with a one-line tagline and badges (build, license, version), a two-sentence "Why it exists" section, a Quick Start with exact install, run, and test commands, an architecture overview with a Mermaid diagram of the main components, a configuration table (key, type, default, description) and a Common Tasks list, and Contributing and License sections.
The structure works because the README is the first thing a new engineer opens, and a vague one generates endless onboarding questions. Setting [reader] ("a backend engineer joining the team") calibrates the tone and assumed knowledge. The Mermaid architecture diagram and a working Quick Start are the two highest-leverage sections — they cut onboarding questions sharply. Feeding an accurate [stack] is what lets the model produce install and test commands that match what actually runs.
When to use it
- Handing off a service to a client team or new hires who need to get productive fast
- When a repo has no README or only a stub
- When onboarding questions keep landing on you because the docs are thin
- When you want a consistent README structure across many repos
- When a project needs an architecture diagram readers can actually follow
- When the existing README's install or test commands have drifted from reality
Example output
You get ready-to-commit Markdown: a title, tagline, and badges; a short "Why it exists" section; a Quick Start with concrete install, run, and test commands; an architecture overview containing a Mermaid component diagram; a configuration table and a Common Tasks list; and Contributing and License sections. It's scannable and uses real example commands, with badge URLs derived where possible. The aim is a file you can commit after a quick accuracy pass, not a placeholder. The Quick Start and the Mermaid diagram are the two sections a new engineer hits first, so they carry the most weight — a working Quick Start gets someone running in minutes, and a faithful diagram answers the structural questions before they're asked.
Pro tips
- Feed your real composer.json or package.json so the install and test commands match what actually runs, not guesses
- Set
[reader]accurately; a README for a joining engineer differs from one aimed at external integrators - Verify the Mermaid diagram reflects your true component boundaries before committing it
- Check the badge URLs resolve, since the model derives them and may guess at paths
- Keep
[description]tight and accurate, as it seeds the tagline and the "Why it exists" section - Run the Quick Start commands yourself once; a README that fails at step one erodes trust immediately
