README files

Almost every software project has a file called README.md. It's the first thing people read, and it's one of the first files an AI tool looks at too.

What is a README?

Think of the back cover of a book. In a few seconds, it tells you what the book is about and whether it's for you. A README does the same for a project.

A README is a Markdown file in the main folder of your project. Its name literally means "read me first".

• It explains what the project is and who it's for.
• It shows how to run or use it.
• GitHub shows it automatically on your project's main page.
• AI tools read it to understand your project quickly.

What goes in a README?

A good beginner README has five to seven short sections. You don't need all of them on day one. Start small and add as you build.

• Project name and one-line summary — what it is, in one sentence.
• Features — what it can do, as a short list.
• Tech used — the tools and services behind it.
• How to run it — the steps or commands to start it.
• Environment variables — the names of settings it needs (never the secret values).
• Status — what's done and what's next.
• Live link — where people can try it, once it's published.

A README template

Copy this and fill in the parts in square brackets.

# [Project name]

[One sentence: what it does and who it's for.]

## Features
- [Feature 1]
- [Feature 2]
- [Feature 3]

## Tech used
- [Builder or framework, e.g. Lovable / Next.js]
- [Database, e.g. Supabase]
- [Hosting, e.g. Vercel]

## How to run it
1. [Step 1, e.g. Download the project]
2. [Step 2, e.g. Run `npm install`]
3. [Step 3, e.g. Run `npm run dev`]

## Environment variables
Create a `.env.local` file with these names (ask the owner for values):
- `[VARIABLE_NAME]`

## Status
- [x] [Done item]
- [ ] [Next item]

## Live demo
[Link, once published]

A filled-in example

For example, here's what a README for a simple habit tracker app might look like early in the build.

# Habit Tracker

A simple web app to build daily habits, track streaks, and see your progress.

## Features
- Add, edit, and delete daily habits
- Check off a habit once per day
- See your current streak for each habit
- Weekly progress chart

## Tech used
- Built with Lovable (AI app builder)
- Code synced to GitHub

## How to run it
Open the live link below. No install needed.

## Status
- [x] Habit list
- [x] Check off habits
- [ ] Streaks
- [ ] Progress chart

## Live demo
Coming soon

Let's break this down:

• The summary is one sentence anyone can understand.
• The features list matches what the app really does, no more.
• The status checklist shows progress at a glance.

Let AI draft your README

You don't need to write it from scratch. Give the AI your ideas and let it draft.

Write a README.md for my project in Markdown.
Project: a habit tracker web app for people who want to build small daily habits.
Features: add habits, check off daily, streaks, weekly progress chart.
Built with: Lovable, synced to GitHub.
Use these sections: summary, Features, Tech used, How to run it, Status, Live demo.
Keep it short and use simple words. Return it in one Markdown code block.

Common mistakes

• Writing a long essay. Keep each section short and scannable.
• Listing features you only plan to build as if they're done. Use the Status section for plans.
• Pasting API keys or passwords into the README.
• Never updating it, so it describes an older version of the app.

What's next?

A README describes what your project is. A PRD goes deeper and describes exactly what you plan to build. Let's write one next.