SPEC — [Project name]
Copy this template
To start your own SPEC.md, open Show the text to copy below and use the copy button at the top right of the block, then paste it into a new file called SPEC.md in your repository. On GitHub, use the Copy raw file button on the template's GitHub page.
Show the text to copy
# SPEC — [Project name]
> **One page.** 🟡 **AI limited:** write this yourself. You may ask an AI to *critique* it ("What is ambiguous? What edge cases am I missing?"), but not to write it.
> A good spec lets a classmate, or an AI agent, build the right thing without asking you questions.
> **Goldfish test** (weeks 3 and 6): paste only this file into a fresh chat and ask what it would build and what it would need to ask you. Wherever it guesses wrong or has to ask, revise the spec.
> Replace every [square-bracket placeholder].
**Author:** [your name or GitHub username] · **Last updated:** [date]
## 1. Problem
Who has what problem, and why does it matter? (2–3 sentences)
## 2. User
Describe one real person who will use this. It can be you.
## 3. User stories
Use the form *As a …, I want to …, so that …*. Mark each one **MUST**, **SHOULD** or **COULD**.
- **MUST** — As a …, I want to …, so that …
- **MUST** — As a …, I want to …, so that …
- **SHOULD** — As a …, I want to …, so that …
- **COULD** — As a …, I want to …, so that …
## 4. Acceptance criteria
Each criterion must be something you can check by using the app. Format: **WHEN** *situation or action*, **THE APP SHALL** *observable result*.
Include at least two edge cases: empty input, very long input, duplicates, reloading the page, a small phone screen, no internet.
| ID | Criterion | Priority | Passes? |
|---|---|---|---|
| AC1 | WHEN I type a name and press Enter, THE APP SHALL add it to the list and clear the input box. | MUST | ☐ |
| AC2 | WHEN I press Enter with an empty box, THE APP SHALL add nothing and SHALL show "Please type a name". | MUST | ☐ |
| AC3 | WHEN I reload the page, THE APP SHALL show the same list as before. | MUST | ☐ |
| AC4 | | | ☐ |
| AC5 | | | ☐ |
## 5. Out of scope
Things you are deliberately **not** building this time. (This list stops you, and the AI, from wandering.)
-
-
## 6. Constraints
- **Technology:** [for example: plain HTML, CSS and JavaScript; no frameworks; no build step]
- **Data:** [for example: saved in the browser with localStorage / in a Supabase table with row-level security]
- **Must work on:** [for example: phone and laptop browsers]
- **Never:** real payments, real personal data about other people, secrets in front-end code
## 7. Wireframe
Sketch the main screen on paper, photograph it and add it to the repo (for example `docs/wireframe.jpg`), then link it here. A text sketch is fine too:
```text
+--------------------------------+
| Title |
| [ input box ] [ Add ] |
| • item one [x] |
| • item two [x] |
+--------------------------------+
```
## 8. Open questions
-One page. 🟡 AI limited: write this yourself. You may ask an AI to critique it ("What is ambiguous? What edge cases am I missing?"), but not to write it. A good spec lets a classmate, or an AI agent, build the right thing without asking you questions. Goldfish test (weeks 3 and 6): paste only this file into a fresh chat and ask what it would build and what it would need to ask you. Wherever it guesses wrong or has to ask, revise the spec. Replace every [square-bracket placeholder].
Author: [your name or GitHub username] · Last updated: [date]
1. Problem
Who has what problem, and why does it matter? (2–3 sentences)
2. User
Describe one real person who will use this. It can be you.
3. User stories
Use the form As a …, I want to …, so that …. Mark each one MUST, SHOULD or COULD.
- MUST — As a …, I want to …, so that …
- MUST — As a …, I want to …, so that …
- SHOULD — As a …, I want to …, so that …
- COULD — As a …, I want to …, so that …
4. Acceptance criteria
Each criterion must be something you can check by using the app. Format: WHEN situation or action, THE APP SHALL observable result. Include at least two edge cases: empty input, very long input, duplicates, reloading the page, a small phone screen, no internet.
| ID | Criterion | Priority | Passes? |
|---|---|---|---|
| AC1 | WHEN I type a name and press Enter, THE APP SHALL add it to the list and clear the input box. | MUST | ☐ |
| AC2 | WHEN I press Enter with an empty box, THE APP SHALL add nothing and SHALL show "Please type a name". | MUST | ☐ |
| AC3 | WHEN I reload the page, THE APP SHALL show the same list as before. | MUST | ☐ |
| AC4 | ☐ | ||
| AC5 | ☐ |
5. Out of scope
Things you are deliberately not building this time. (This list stops you, and the AI, from wandering.)
6. Constraints
- Technology: [for example: plain HTML, CSS and JavaScript; no frameworks; no build step]
- Data: [for example: saved in the browser with localStorage / in a Supabase table with row-level security]
- Must work on: [for example: phone and laptop browsers]
- Never: real payments, real personal data about other people, secrets in front-end code
7. Wireframe
Sketch the main screen on paper, photograph it and add it to the repo (for example docs/wireframe.jpg), then link it here. A text sketch is fine too:
+--------------------------------+
| Title |
| [ input box ] [ Add ] |
| • item one [x] |
| • item two [x] |
+--------------------------------+