# Writing Guide: Business Spec, Requirements Document, and Mockup

> A template for business-side owners preparing a development request. When you start
> drafting with an AI, paste this whole file in and say "follow this guide."
>
> Source: https://www.uniflow.kr/en/requirements-document-vs-product-spec/
> Copy and adapt it freely.

---

## 0. Thirty Seconds Before You Start — What Are You Writing?

The three artifacts answer **different questions**. One file or three, they must not blur together.

| | Question it answers | Who reads it |
|---|---|---|
| Business spec | Why are we doing this, and for whom | Decision-makers, stakeholders |
| Requirements document | What must be true | Engineering, QA, operations |
| Mockup | So what does it look like on screen | Everyone |

Engineering planning — how it gets built, how it attaches to legacy — is **done separately by the
engineering team.** Don't write that part here. You'll usually get it wrong, and a wrong answer
that becomes the reference point is worse than no answer.

### When you don't need all of this

- Copy changes, value changes, toggling something on or off — **simple operational work.** One line is enough
- Backend work with no screen — write input and output examples instead of a mockup

---

## 1. Business Spec — Why Are We Doing This

When you hand this to an AI, say:

> Write a business spec from the notes below. **Do not describe implementation.**
> Leave out screen design, data structures, and technology choices. Keep it to the
> objective and the reasoning behind it.

### What has to be in it

- [ ] **Background** — what's wrong right now. Include one number if you have it (ticket volume, drop-off point, handling time)
- [ ] **Objective** — what changes if we do this. One sentence
- [ ] **Audience** — who uses it. Write roles, not names (e.g. "sales rep," "external partner contact")
- [ ] **Success criteria** — what we'd have to see for this to have worked. Measurable
- [ ] **Priority** — three buckets: must have this round / nice to have / later
- [ ] **Out of scope** — what you're explicitly not doing. This line gets used more than any other

### What to leave out

- Table structures, API design, framework names — that's engineering planning's job
- "As fast as possible," "flexible," "scalable" — unjudgeable, so they only produce arguments later
- A deadline — that arrives after engineering planning. A **target date with a reason** is fine
  (e.g. "before the November campaign"); a reason makes it negotiable

---

## 2. Requirements Document — What Must Be True

This is the document engineering stares at longest. Each sentence becomes a pass/fail test.

> Write a requirements document for the feature below.
> Phrase every item so it can be **judged true or false — "does X" / "does not do X."**
> Where something is ambiguous, don't guess. **Put it in a separate question list.**

### The shape of one item

```
[Feature] Status change from the list
- Behavior: the status cell in each row becomes a dropdown
- Permissions: visible only to the owner and admins; the cell is not rendered for anyone else
- Exceptions: closed items show the dropdown disabled
- Concurrency: the later save is rejected and the latest value is reloaded
- Empty state: with no items, show only "No items yet"
- Acceptance: signed in as a non-owner, the status cell is not visible
```

### The six that always come back if you skip them

Write in prose and these drop out almost every time. Skip them and the ticket reopens after launch.

- [ ] **Permissions** — who sees it, who changes it. "Not visible" and "visible but disabled" are different requirements
- [ ] **Empty state** — what's on screen when there is no data at all
- [ ] **Failure** — what the user sees when a save fails, and whether their input survives
- [ ] **Concurrency** — when two people edit the same item, who wins
- [ ] **Existing data** — what happens to everything already in the system. Left alone, or migrated
- [ ] **Both extremes** — how the screen behaves at zero rows and at tens of thousands

### Writing acceptance criteria

End each requirement with one line describing **what passing looks like.**
You'll reuse it verbatim at review, and engineering uses it to know when they're done.

- Good: "Signed in as a non-admin, open the list and the status cell is not visible"
- Bad: "Permissions should be handled properly"

---

## 3. Mockup — What It Looks Like on Screen

The prompt to use when asking an AI to build an HTML mockup.

> Build a **single HTML file** mockup for the requirements below.
> - No external libraries. Put dummy data inline
> - Do not implement real saving, login, or API calls
> - Make **empty list / loading / error / no permission** states each viewable
> - Label every screen with its name
> - At the bottom, add: "This mockup exists to show requirements. It is not implementation code."

### Can the spec live inside the mockup?

**Yes.** Writing each screen's purpose and requirements right above it makes the whole thing
easier to read. There's no rule saying three files. There is exactly one thing to get right:
**make it obvious where confirmed requirements end and illustration begins.**

- Confirmed requirements: number them, phrase them as "does X"
- Dummy content you added to make it look real: mark it as an example. Every name, figure, and amount goes here

### The one line to put on your mockup

Before you send it, put this sentence at the top of the file or in the message body.

> This mockup is **a picture of the requirements**, not a draft of the product.
> The code will not be reused; implementation starts after engineering planning.

That one line heads off both "why didn't you use what I built?" and "isn't this basically done?"

### What a mockup does not settle

However good the mockup, the right-hand column stays blank. Engineering planning fills it in.

| Visible (the mockup answers) | Invisible (engineering decides) |
|---|---|
| Flow, button placement, wording | Which tables and APIs get used |
| Empty states, what an error looks like | How existing data migrates |
| Input fields and their order | How concurrent edits are prevented |
| Branches and conditions | Whether performance holds, what else breaks |

---

## 4. Final Check Before Sending

- [ ] Are spec content and requirements content **kept apart** (one file is fine, but the sections must be distinct)?
- [ ] Is every requirement a **judgeable sentence** (no "properly," "as much as possible," "flexible")?
- [ ] Did you cover all **six** — permissions, empty state, failure, concurrency, existing data, both extremes?
- [ ] Does the mockup carry the **"picture of the requirements"** line?
- [ ] Is confirmed content **visually distinct** from illustration?
- [ ] Did you write the **out of scope** list?
- [ ] Did you place the "when will it be done" question **after engineering planning**?
- [ ] Did you leave a place to receive engineering's **question list**?

---

## 5. Cautions When Working With AI

- **Don't forward the AI's questions to engineering as-is.** Split them first into what you can
  answer yourself and what only engineering can answer
- **Verify every number, regulation, and policy the AI filled in.** A number that lands in the
  requirements document gets implemented exactly as written
- **Keep client names, contract amounts, and personal contact details out.** Roles and conditions
  summarize just as well
- **The better the mockup looks, the more explicit that one line needs to be.** Unlike a hand-drawn
  wireframe, a screen with correct spacing and color reads as finished