How to Write a README That People (and AI) Can Actually Use

Quick answer
A README answers, in order: what is this, how do I run it, how do I configure it, how do I test it, how do I contribute.
If a stranger can’t run your project from the README in two minutes, the README failed — no matter how complete it is.
AI agents read READMEs to learn how to work on your project; a good one makes agent-generated code fit your conventions.

What sections does a README need?

Six, in order: a one-paragraph description of what the project does and why it exists; install and run instructions that work from a clean clone (exact commands, not ‘install dependencies’); configuration — the environment variables and settings, ideally with a .env.example; test and lint commands; a usage example that shows the happy path; and a short contributing note. Everything else (badges, screenshots, detailed docs) is garnish — these six are the meal.

What makes instructions actually work?

Exactness and completeness: pin versions or ranges, list every prerequisite, show commands as copy-pasteable blocks with expected output, and include the ‘did it work’ check (‘you should see X at localhost:3000’). Test the README the way you’d test code: clone the repo fresh on a clean machine and follow it top to bottom. Most READMEs fail because they assume knowledge — the reader’s environment, the project’s state — instead of stating it.

# A runnable README block looks like this:\n# Prerequisites: Python 3.11+, PostgreSQL 15\ncp .env.example .env   # then edit values\npip install -r requirements.txt\npython manage.py migrate\npython manage.py runserver\n# You should see the app at http://localhost:8000 — log in with the seeded admin account.

Why do AI agents care about your README?

Coding agents read the README to learn the project’s commands, structure, and conventions before generating code. A README that documents the run/test commands, the layout, and the tech stack makes agent output fit your project instead of inventing its own patterns. This is now a practical reason to keep it current: the README is the contract between the project and every future contributor, human or agent.

Where this bites vibecoders
Vibecoders generate projects faster than they document them, and the AI-generated README is often worse than none: a generic template with the wrong commands, no setup steps, and placeholders. The fix is the same discipline as everything else: write the README from a clean clone, run every command it shows, and keep it short. A two-minute setup guide is worth more than a template with badges.

Where AI coding assistants get this wrong

Generating READMEs with placeholder text and commands that were never run.
Documenting setup steps that assume a half-configured environment.
Listing environment variables without a .env.example to copy.
No run/test commands, leaving both humans and agents to guess.

Checklist

Cover the six essentials: what, run, configure, test, usage, contribute.
Verify every command by following the README from a clean clone.
Include a .env.example matching the documented variables.
Keep it short — two-minute setup, not an essay.

FAQ

How long should a README be?

As long as needed to run and understand the project — usually 100-300 lines for a real project. The failure modes are both directions: too short to run anything, or too long to find the run instructions. Put the quick start near the top, everything else after.

Should the README be generated by AI?

As a draft, yes — then verify every command by running it and replace anything the assistant guessed. A README full of unverified commands is worse than none because it burns the reader’s trust early. The verification step is non-negotiable.