How to write a README — step by step, so a human and an AI both get it

A README is the README.md file that sits at the root of a project and opens first when someone lands in your repository. For a long time it was treated as a box-ticking formality. But here's what changed: READMEs aren't read only by humans anymore.

When you ask an AI agent to understand your code, the first thing it opens is the README — that's its briefing on the project. A good README instantly tells the agent: what this is, how to run it, where things live. A bad (or empty) one makes both a human and the AI guess. Let's put together a decent one in 15 minutes — step by step.

Step 1. A name and one line about the point

At the top — a level-one heading (#) with the project name. Under it — one sentence that explains what it is and who it's for. No fluff.

• Bad: "An innovative next-generation platform."
• Good: "A Telegram bot that sends tomorrow's weather at 8 a.m."

This is the most-read line in the whole file. If a person can't tell in five seconds what the project is, they won't go further. And the agent leans on it too, to grasp the context.

Step 2. How to run it — the most important section

The "Install and run" section is what people open a README for most. Here go the exact commands, in order, that turn a clean copy of the project into a working app. Not a description — literally commands you can copy:

1. clone the project: git clone <link> (you'll need Git);
2. enter the folder: cd my-project;
3. install dependencies: npm install;
4. run it: npm run dev.

The rule is simple: if a stranger couldn't launch the project from these lines, the section isn't done. Test it on yourself: delete the project, clone it fresh, and walk through your own steps.

Step 3. Environment variables and secrets

Almost any project needs keys: access to a database, to a model's API. You don't store them in the code — but in the README you must say which variables are needed, without revealing the values.

Add a "Setup" section and list the variable names from the .env file: e.g. SUPABASE_URL, OPENAI_API_KEY. You never write the keys themselves in a README — only their names and a short "where to get it." More on the mechanism itself in what environment variables are.

Step 4. Structure and the rest — keep it short

If the project is more than a couple of files, add a short "Structure" section: where the frontend is, where the backend is, where the content lives. Three or four lines, not a map of the whole repo. Beyond that, optionally: how to run tests, how to deploy, the license. Don't turn the README into a book — it should read in a couple of minutes.

A ready skeleton — copy and fill in

Here's the minimal frame. Replace the contents with your own and you've got a decent README:

# Project name

One sentence: what it is and who it's for.

## Install and run

1. `git clone <link>`
2. `cd project`
3. `npm install`
4. `npm run dev`

Open http://localhost:3000

## Setup

Copy `.env.example` to `.env` and fill in:

- `DATABASE_URL` — the database connection string
- `API_KEY` — the model key (get it from your provider's dashboard)

## Structure

- `src/` — app code
- `public/` — static files

What you'll get

A file that saves everyone time. A newcomer runs the project without pinging you in DMs. You yourself, six months later, remember how the thing even worked. And an AI agent, landing in the repo, immediately grasps the context and hallucinates less about your code. Fifteen minutes on a README pay off with every person who opens the project after you.

FAQ

Do I need a README if the project is only mine?

Yes — if only for "future you." In three months you'll forget which command launched it and why that variable is there. A README is a note to yourself you don't mind losing from your head.

How detailed should a README be?

Exactly detailed enough for a stranger to run the project and understand what it is. Anything beyond that is a bonus. A bloated README with the whole architecture gets read even less than an empty one — you never reach the point. Short and precise beats long.

Is Markdown hard?

No, it's plain text with a couple of symbols: # for headings, - for lists, backticks for commands. Everything you need for a README you've already seen in this article. Half an hour and the syntax is in your head.