The definitive, no-BS guide to writing README files that people actually read.
A comprehensive, opinionated specification for writing high-quality README files. Built from analyzing top-tier open-source projects, it covers structure, formatting, visual content, and mandatory elements — so you never have to guess what a great README looks like.
The guide lives in The Ultimate README Guide.md.
This README is an example of what it produces.
The guide is a single Markdown file designed to be consumed in multiple ways.
Feed the guide to any LLM-based coding assistant (GitHub Copilot, Claude, Cursor, ChatGPT, etc.) as a system prompt or reference document. The agent will then write or review READMEs that follow the spec.
Example workflow:
- Copy the contents of
The Ultimate README Guide.md - Paste it into your AI agent's system prompt, custom instructions, or context window
- Ask the agent to write a README for your project
- The agent produces a README that follows every rule in the guide
Tips for best results:
- Provide your project's source code alongside the guide so the agent can extract real details (tech stack, structure, dependencies)
- If the output is too long, ask the agent to prioritize sections relevant to your project type (e.g., skip EDA for a CLI tool)
- Use the guide's checklist as a validation step — ask the agent to verify its output against every checkbox
Use the checklist section to review existing READMEs. Ask your AI agent:
"Review this README against the checklist in the guide. Flag any missing sections or violations."
The guide contains copy-pasteable template blocks for every section. Find the sections you need, assemble them, and fill in your project's details.
New contributors can read the guide to understand what's expected in project documentation. Share it with your team to establish a consistent standard.
| Section | What It Covers |
|---|---|
| Purpose & Philosophy | Why READMEs matter, core principles |
| Core Structure | 25 ordered sections with rationale |
| Detailed Breakdown | Every section with examples and rules |
| Formatting Best Practices | Markdown elements, visuals, consistency, accessibility, SEO |
| Template Outline | Copy-paste skeleton for any project |
| Checklist | 25-item verification list before pushing |
The guide covers general software projects, data science/ML projects, and everything in between. Skip sections that don't apply to your project type.
- opensource.guide — GitHub's official open-source docs
- Readme Driven Development
- Awesome README
- shields.io — badge generator
Distributed under the MIT License. See LICENSE for more information.
Made with ❤️ by dimassaa