How to Write a README for Your Project

A README is the file people read first when they open your project. On GitHub it's displayed automatically below the file list. A good one answers "what is this, and how do I run it?" in under a minute. A missing one means every newcomer — including you, in six months — starts by guessing.

What a README is

A text file named README.md, in your project's top folder, written in Markdown — plain text with simple formatting like # for headings. (What Is Markdown?.)

Its readers:

You, later. You will forget how to run this project. Everyone does.
Collaborators and new developers. (How to Onboard a New Developer on Day One.)
Clients, if you hand the project over. (How to Hand Off an AI-Built App to a Client.)
AI tools, which read it to understand the project.

What to include

1. Name and one-line description

What it is, for whom.

Plant Tracker

A web app that reminds you when to water each of your plants.

2. Screenshot or link

A picture of the app, or the live URL, shows in two seconds what a paragraph takes thirty to explain.

3. How to run it locally

The most important section. Exact, copy-pasteable steps, starting from nothing:

## Getting started

Requirements: Node.js 24, PostgreSQL 17

```bash
git clone https://github.com/you/plant-tracker.git
cd plant-tracker
npm install
cp .env.example .env    # then fill in the values
npm run db:migrate
npm run dev             # http://localhost:3000
```

Test these steps on a clean machine, or ask someone else to follow them. Any step you "just know" and didn't write down is a step someone will get stuck on.

4. Configuration

A list of the environment variables and what each one is for. Never real values — those go in .env, which isn't committed. (What Is an Environment Variable?.)

Variable	What it's for
`DATABASE_URL`	Postgres connection string
`STRIPE_SECRET_KEY`	Stripe API key (use a test key locally)
`EMAIL_FROM`	Sender address for reminder emails

5. Common commands

- `npm run dev` — start the development server
- `npm test` — run tests
- `npm run build` — production build
- `npm run db:migrate` — apply database migrations

6. How it's deployed

Where it runs, how changes get there, and where to find logs. Even one paragraph helps.

7. Project structure (optional)

For bigger projects, a short map: "src/app — pages; src/lib — shared logic; src/db — schema and migrations."

A template to copy

# Project Name

One sentence on what it does and who it's for.

Live: https://yourapp.com

## Getting started
Requirements: …
Steps: …

## Configuration
| Variable | Purpose |

## Commands
- `npm run dev` — …

## Deployment
How and where it's deployed; where logs live.

## License

README vs CLAUDE.md

If you use Claude Code, you may also have a CLAUDE.md. They overlap but serve different readers:

README — for humans: what the project is and how to start.
CLAUDE.md — for the AI: conventions, commands to run, rules like "never edit migrations after they're applied."

Keep them consistent, and don't duplicate long sections — CLAUDE.md can say "see README for setup." (How to Write a CLAUDE.md.)

Claude Code can draft a README from your project in one step — ask it to "write a README with setup steps, then verify every command in it actually works." The verification is the valuable bit.

Mistakes to avoid

Setup steps that don't work. Out-of-date instructions are worse than none: they waste time and mislead.
Real secrets in examples. Use placeholders.
Marketing copy instead of instructions. Save the pitch for your website.
Walls of text. Headings, lists, and code blocks make it skimmable.
Never updating it. When you change how the project runs, update the README in the same commit.

EasySpawn workspaces start with your repository, dependencies, and database already running, so the "getting started" section of your README becomes "open the workspace." See how it works or join the waitlist.