# [Project name]

[One sentence: what this does, and who it is for.]

[Optional: a screenshot, a short recording, or a link to the running app.]

## What it does

Three bullets a non-programmer could follow. Say what the user gets, not which classes you wrote.

- [Thing a user can do.]
- [Thing a user can do.]
- [Thing a user can do.]

## Run it yourself

Someone should get this running in under five minutes, with no help from you.

**You need:** [language and version, database, anything else]

```
[clone command]
[build or install command]
[run command]
```

[What they should see when it works.]

## How it is built

Name the main pieces and why each one is there. Skip anything the code makes obvious.

| Piece | Choice | Why this one |
|---|---|---|
| Language | | |
| Build and tests | | |
| Data | | |
| Checks on every push | | |

## Decisions worth explaining

The interesting part of a project is what you ruled out. Link to the full decision record if you wrote one.

- **[Decision]** — I chose [X] over [Y] because [reason]. The cost is [cost].
- **[Decision]** — I chose [X] over [Y] because [reason]. The cost is [cost].

## How I know it works

Say what the tests cover, and name one case you deliberately tested because it was easy to get wrong.

- Tests: [what they cover] — run them with `[command]`
- Edge case worth naming: [the input or state, and what should happen]
- Checks on every push: [what runs, and a link to a passing run]

## What was new to me

This is the part a reader cannot get from the code. Be specific and be honest.

- [Something you had not done before, and what you now understand about it.]
- [Something that went wrong, and what you changed because of it.]

## What I would do differently

Naming a limit out loud reads as judgment, not weakness.

- [A limit you know about, and what you would do with more time.]

## Status

- Current version: [tag or version]
- What works today: [short list]
- Not built yet, on purpose: [short list]

---

## About this template

A project README is the first thing another person reads, and often the only thing. It should let a stranger understand the project, run it, and judge your decisions in about two minutes.

> **What this teaches:** I can explain my own work to someone who was not there. I can show the decisions and the tests behind it, not just the finished screen.

Before you write it, picture a reader who has ten other tabs open. Ask what they need in the first fifteen seconds.

Keep every claim checkable. Link the commit, the test run, or the passing check that backs it up. Remove any section that does not apply to this project rather than leaving an empty heading.

**Explain it back:** Say what your project does, one decision you made, and how you know it works. Do it in under a minute, without opening the code.

**Delete this whole section once you have filled the document in.** What is left should read as a finished document on its own.