Vibe Coding: build real apps with AI · Episode 5. Everything below was really run on 6 November 2026 with Claude Code 2.1.318 in print mode (claude -p), allowed to use only its file tools (--tools Read Write Edit Glob, --permission-mode acceptEdits). Replies are quoted exactly, shortened only where marked .... The pages were opened in a real browser (Chromium) and every acceptance criterion was tested by script. AI replies vary run to run; the lessons don't.
The problem: "Build me an app"
Ravi's settle() function (Episode 4) works, but only Ravi can run it. The flat wants a real app: a form, a list, a settle-up button. Ravi has an AI agent (an AI that can create and edit files itself, Episode 2), so he opens an empty folder and types one line:
ravi@laptop:~/projects/flat-app$ claude -p "Build me an app for my flat's shared expenses."
Real reply (shortened):
I built a single-file app at `~/projects/flat-app/index.html`. I haven't opened it in a browser
or tested it. To use it, open the file in a browser. It has no dependencies or server, and it saves
to your browser's localStorage.
- **Flatmates:** you can add and remove people. ...
- **Expenses:** each one has a description, amount, who paid, a date, and which flatmates share it.
The split is equal, and any leftover cent goes to the first people in the list.
- **Who pays whom:** ... "Mark paid" records a payment and updates the balances.
- **Backup:** Export and Import buttons save and restore your data as JSON.
Because the data lives in one browser, flatmates can't each use their own phone. ...
Splits are equal only. I didn't add custom shares or percentages, or categories such as rent and
utilities. I can add those, or sync across phones, if you want them.
- HTML is the language of web pages;
index.htmlis the page. - localStorage is a small storage space inside one browser on one device.
It works: Ravi 1200 + Neha 300 gives "Sam pays Ravi 500.00, Neha pays Ravi 200.00". But the flat says:
- Neha: "Can I add from my phone?" No: the data lives in one browser.
- Sam: "500.00 what? Where's the ₹?" And what are Export JSON and Mark paid?
- Ravi: "Is it finished?" Nobody can say, because nobody wrote down what finished means.
Why one line can't build your app
A function has five blanks (Episode 4). An app has hundreds of small decisions: who uses it, on which devices, which buttons, where data lives, what counts as wrong input. One line decides almost none of them, so the AI decided them all: reasonable guesses, just not the flat's. And with no finish line, "done" is undefined.
Fix: decide first, on one page, then build. That page is a spec (specification). Companies call a bigger one a PRD, a product requirements document.
A spec is the floor plan before the house
| Building a house | A spec | Meaning |
|---|---|---|
| Who will live here? | User stories | who needs what, and why |
| Rooms, and "no pool" | Features + non-goals | what's in, and what's deliberately out |
| Cupboards, layout | Data + screens | what you store, what people see |
| The inspection list | Acceptance criteria | tests that say "done" |
Ravi's spec: SPEC.md
Markdown is plain text where # makes a heading and - makes a bullet. AI tools read it very well.
# Flat Expenses: one-page spec (v1)
## Problem
Ravi, Neha and Sam share a flat. Every month they argue about who paid what
and who owes whom.
## Users and user stories
- As a flatmate, I want to add an expense (what, amount, who paid, who shares it)
so it's recorded once.
- As a flatmate, I want to see who pays whom, so we can settle up at month end.
- As a flatmate, I want to delete an expense I added by mistake.
## Features (v1)
1. Add an expense: description, amount in rupees (paise allowed), paid by,
shared by (ticked flatmates, all ticked by default).
2. List of expenses, newest first, with a delete button.
3. "Settle up": who pays whom, fewest payments.
## Non-goals (NOT in v1)
- No logins or accounts. No syncing between phones (later, Episode 15).
- No charts (Episode 11). No other currencies.
## Data we store
- Flatmates: fixed list ["Ravi", "Neha", "Sam"].
- Expense: id, description, amount_paise (integer), paid_by,
shared_by (list of names), date (YYYY-MM-DD).
- Saved in the browser (localStorage), so it survives a page reload.
## Screens
One page, three parts: Add expense form → Expense list → Settle up.
## Acceptance criteria (v1 is done when ALL pass)
1. Ravi 1200 + Neha 300, shared by all → "Sam pays Ravi ₹500.00"
and "Neha pays Ravi ₹200.00".
2. Ravi 1000 shared by all → payments add up to exactly ₹666.66.
3. Money shows with ₹ and Indian commas: 120000.5 → "₹1,20,000.50".
4. An empty description or an amount of 0 is rejected with a message.
5. After a page reload, all expenses are still there.
6. Works on a phone screen 360px wide: nothing cut off, no sideways scrolling.
## Tech
A single index.html with plain HTML, CSS and JavaScript. No libraries.
User stories
Pattern: As a someone, I want something, so that a reason. The "so that" tells the AI why, which changes how it builds.
Features vs non-goals
- Features: what v1 will do. Keep each one small enough to check.
- Non-goals: what you will not build (yet), written down so nobody builds it by accident. Neha's phone question now has an honest answer: not in v1, it needs a server (Episode 15).
Data you store, and screens
- Every expense has an id (a unique label), description,
amount_paise(a whole number), payer, sharers and a date. Writing the data down forces decisions, like paise, before code exists. - Screens: even a rough pencil sketch helps.
Acceptance criteria: checkable "done"
| Not checkable | Checkable |
|---|---|
| "The app should be fast and easy to use" | "Ravi 1200 + Neha 300 → Sam pays Ravi ₹500.00" |
| "Money should look nice" | "120000.5 → ₹1,20,000.50" |
Test: could a friend check it in one minute, and get a clear yes or no? A pixel is one dot on the screen; 360 px is a typical phone width.
Feeding the spec to the AI: gaps first
A fresh folder with only SPEC.md and CLAUDE.md. Before any code:
ravi@laptop:~/projects/flat-app$ claude -p "Read SPEC.md. Before writing any code, list anything that is unclear or missing in it, at most 5 points, most important first. No code."
The AI's real reply, in full
I read SPEC.md. These are the gaps, most important first:
1. **Rounding rule for uneven splits.** Criterion 2 says the payments total ₹666.66 when Ravi pays ₹1000 split three ways. The spec doesn't say who absorbs the odd paisa. I'd assume the payer, or the first sharer, takes the extra paisa so the shares always sum to the amount. Is that right? It also needs a rule for the case where the payer isn't one of the sharers.
2. **"Month end" and settling.** The stories talk about settling at month end, but the data model has no month filter and no "settled" state. Should "Settle up" cover all expenses ever recorded, or only the selected month? After people pay each other, is there a way to record that, or do they delete everything by hand? Without this, balances accumulate forever.
3. **Validation beyond the two cases in criterion 4.** The spec doesn't cover:
- negative amounts
- non-numeric amounts
- more than 2 decimal places, such as 10.555 (reject or round?)
- no flatmate ticked in "shared by"
- a very large amount
Is the rule "reject with a message" for all of these?
4. **Date handling.** The expense has a `date` field, but the form lists no date input. Is it set automatically to today, or can the user pick it? Also, "newest first" needs a tie-break for expenses on the same day. I'd assume the most recently added comes first.
5. **Settle-up display details.**
- What does it show when everyone is square or there are no expenses? I'd assume a message like "All settled".
- Is the output order of payments specified?
- Should deleting an expense ask for confirmation? The spec only mentions a delete button.
Five real gaps: the odd paisa, month end, more bad inputs, a date with no date box, the "everyone square" screen. Each would have been a silent guess. Ravi answers them himself:
## Decisions (answers to the AI's questions)
- Leftover paise go to the first people in "shared by", in the order
Ravi, Neha, Sam. The payer always gets credit for the full amount.
- Settle up covers every expense in the list. A "Start new month" button
clears the list after a confirmation.
- Reject with a message: empty description, amount not a number, 0 or less,
more than 2 decimals, over ₹1,00,000, nobody ticked.
- The form has a date input, today by default. Newest first;
same day: last added first.
- No expenses or everyone square: show "All settled".
Deleting asks "Delete this expense?".
Build v1 from the spec
ravi@laptop:~/projects/flat-app$ claude -p "Build v1 of the app described in SPEC.md."
I've written v1 as a single `index.html` in `~/projects/flat-app`. I haven't opened it in a
browser or run any tests. I only traced criteria 1 and 2 by hand. ...
**Acceptance criteria this change affects**
1. **Ravi 1200 + Neha 300:** I worked this through by hand. It gives "Sam pays Ravi ₹500.00" ...
2. **Ravi 1000 shared by all:** The leftover paisa goes to Ravi, ...
3. **Indian commas:** Money is stored as integer paise and formatted with a small function,
so 120000.5 should show as "₹1,20,000.50". I haven't run it.
4. **Rejected input:** Each case in the SPEC shows its own message. ...
5. **Reload:** Expenses are saved to localStorage after every change and loaded on start.
6. **360px phone screen:** ... I haven't checked it at that width.
Please open the file and try 1, 2, 3 and 6 yourself. Criteria 5 and 6 especially need a real browser.
"Should show as" and "I haven't run it" mean not tested yet.
Testing every criterion
| # | Criterion | v1 result |
|---|---|---|
| 1 | 1200 + 300 → Sam pays Ravi ₹500.00, Neha pays Ravi ₹200.00 | pass |
| 2 | Ravi 1000 → ₹333.33 + ₹333.33 = ₹666.66 | pass |
| 3 | 120000.5 → ₹1,20,000.50 | FAIL: "Amount can't be over ₹1,00,000." |
| 4 | empty, 0, -5, abc, 10.555, 100001, nobody ticked → a message each | pass |
| 5 | reload → expenses still there | pass |
| 6 | 360 px wide → nothing cut off, no sideways scroll | pass |
The real mistake
Two functions from the AI's v1 index.html, run in the SyntaxPilot compiler (JavaScript):
// Two functions copied from the AI's index.html (v1)
var MAX_PAISE = 100000 * 100;
function formatMoney(paise) {
var neg = paise < 0; if (neg) paise = -paise;
var rupees = String(Math.floor(paise / 100));
var p = String(paise % 100); if (p.length < 2) p = "0" + p;
var last3 = rupees.slice(-3), rest = rupees.slice(0, -3);
if (rest) rest = rest.replace(/\B(?=(\d{2})+(?!\d))/g, ",") + ",";
return (neg ? "-" : "") + "₹" + rest + last3 + "." + p;
}
function parseAmount(text) {
var t = text.trim().replace(/,/g, "");
if (!/^-?(\d+\.?\d*|\.\d+)$/.test(t)) return { error: "Amount must be a number." };
if (t.charAt(0) === "-") return { error: "Amount must be more than 0." };
var parts = t.split(".");
var frac = parts[1] || "";
if (frac.length > 2) return { error: "Amount can have at most 2 decimal places." };
while (frac.length < 2) frac += "0";
var paise = parseInt(parts[0] || "0", 10) * 100 + parseInt(frac, 10);
if (paise <= 0) return { error: "Amount must be more than 0." };
if (paise > MAX_PAISE) return { error: "Amount can't be over ₹1,00,000." };
return { paise: paise };
}
console.log(formatMoney(12000050)); // criterion 3, on its own
console.log(parseAmount("1200"));
console.log(parseAmount("0")); // criterion 4
console.log(parseAmount("120000.5")); // criterion 3, typed in the form
Real output:
₹1,20,000.50
{ paise: 120000 }
{ error: 'Amount must be more than 0.' }
{ error: "Amount can't be over ₹1,00,000." }
Each function is right. Together they can never pass criterion 3, because our own spec had two rules that clash: "reject over ₹1,00,000" (Decisions) and "120000.5 → ₹1,20,000.50" (criterion 3). The AI read both, built both, didn't flag the clash in its five questions, and reported that criterion 3 "should" pass without running it. A spec can have bugs too, and the AI won't always notice. Test every criterion yourself.
Fix the spec first, then one change
- Ravi changes the Decisions line in
SPEC.md: ₹1,00,000 → ₹10,00,000 (the spec stays the truth). - A one-change prompt with the reason:
ravi@laptop:~/projects/flat-app$ claude -p "I changed one line in SPEC.md: the limit is now ₹10,00,000, because criterion 3 needs ₹1,20,000.50. Make only that change in index.html."
ravi@laptop:~/projects/flat-app$ diff index.v1.html index.html
71c71
< var MAX_PAISE = 100000 * 100;
---
> var MAX_PAISE = 1000000 * 100;
105c105
< if (paise > MAX_PAISE) return { error: "Amount can't be over ₹1,00,000." };
---
> if (paise > MAX_PAISE) return { error: "Amount can't be over ₹10,00,000." };
diff shows exactly what changed: < is the old line, > the new one. Two lines, nothing else (Episode 6 is about reading diffs). Re-running all six criteria: all pass. Done = every acceptance criterion passes.
Project notes: README.md and CLAUDE.md
| Hospital ward | Project | Who reads it |
|---|---|---|
| Patient chart | README.md |
people: what it is, how to run it |
| Handover note ("no sugar for bed 4") | CLAUDE.md |
the agent: rules it reads first |
| A new nurse every shift | every new chat | starts with no memory, so write rules down once |
Ravi's CLAUDE.md:
# Project notes for the AI (read this first)
- The plan is in SPEC.md. Build only what it lists; never add a non-goal.
- Money is stored as integer paise. Show it as ₹ with Indian commas (₹1,20,000.50).
- One file: index.html, plain HTML/CSS/JavaScript, no libraries.
- After a change, list which acceptance criteria you think it affects.
A brand-new session with no tools at all (--tools "", so it can't open a file):
ravi@laptop:~/projects/flat-app$ claude -p "Without opening any files: what rules do you already know for this project? Answer in at most 4 short lines." --tools ""
From the CLAUDE.md already in context:
- Plan lives in SPEC.md; build only what it lists, never add a non-goal.
- Money is integer paise, displayed as ₹ with Indian commas (₹1,20,000.50).
- Single file index.html, plain HTML/CSS/JS, no libraries.
- After any change, list which acceptance criteria it likely affects.
Claude Code loaded CLAUDE.md from the project folder by itself. Other tools have their own rules files (Episode 32). The spec says what to build, CLAUDE.md says how to behave, the README says what it is for humans.
The one-page spec template
# <App name>: one-page spec (v1)
## Problem
<2 lines, plain words>
## Users and user stories
- As a <who>, I want <what>, so that <why>.
## Features (v1)
1. <small, checkable feature>
## Non-goals (NOT in v1)
- <what you won't build yet, and when>
## Data we store
- <thing>: <fields, with units, e.g. amount_paise (integer)>
## Screens
<parts of each screen, in order; a sketch helps>
## Acceptance criteria (v1 is done when ALL pass)
1. <exact input> → <exact expected result>
## Tech
<language, files, libraries (or "no libraries")>
## Decisions
- <answers to the AI's questions>
Common mistakes (real)
| What you did | What you got | Why | Fix |
|---|---|---|---|
| "Build me an app for my flat" | the AI's app: one browser, no ₹, extra buttons | hundreds of decisions left to guesses | write the one-page spec first |
| "It should be easy to use" | nobody can say if it's done | not checkable | exact input → exact expected result |
| limit ₹1,00,000 and 120000.5 → ₹1,20,000.50 | Amount can't be over ₹1,00,000. |
two spec rules clash; the AI didn't flag it | test every criterion; fix the spec, then the code |
| trusting "should show as ..." | a criterion that really fails | the AI reported without testing | run every criterion yourself, every time |
Mini project: a spec for your own app
Pick a small app you want (a study timer, a chai-stall order list, a cricket score keeper). Write the one-page spec with at least three user stories, three features, two non-goals and five checkable acceptance criteria. Then ask an AI: "Read SPEC.md. Before writing any code, list anything unclear or missing, at most 5 points."
Example solution: a study timer
# Study Timer: one-page spec (v1)
## Problem
I lose track of time while studying and forget breaks.
## User stories
- As a student, I want a 25-minute focus timer, so that I study in fixed blocks.
- As a student, I want a 5-minute break timer after each block, so that I rest.
- As a student, I want to see how many blocks I finished today, so that I stay motivated.
## Features (v1)
1. Start / pause / reset a 25:00 timer. 2. A 5:00 break starts automatically. 3. Today's block count.
## Non-goals
- No accounts, no sync, no sounds other than one beep, no statistics beyond today.
## Data we store
- blocks_today (integer), date (YYYY-MM-DD), in localStorage.
## Screens
One page: big timer, three buttons, "Blocks today: N".
## Acceptance criteria
1. Start at 25:00, wait 60 s → shows 24:00.
2. Pause at 24:30, wait 10 s → still 24:30.
3. When focus reaches 00:00 → break starts at 05:00 and blocks_today goes up by 1.
4. Reload the page → blocks_today is unchanged.
5. Next day → blocks_today starts at 0.
## Tech
Single index.html, plain HTML/CSS/JS, no libraries.
Practice questions
- What's the difference between a feature and a non-goal?
Answer
A feature is something v1 will do; a non-goal is something you deliberately won't build (yet), written down so the AI doesn't add it.
- Rewrite as a user story: "add a delete button".
Answer
"As a flatmate, I want to delete an expense I added by mistake, so that the totals stay correct."
- Make this checkable: "the totals should be correct".
Answer
"Ravi 1000 shared by all three → payments add up to exactly ₹666.66."
- Why ask the AI for gaps before asking it to build?
Answer
Gaps found on paper cost nothing to fix; gaps found in code are silent guesses you may never notice.
- The AI says a criterion "should pass". What do you do?
Answer
Test it yourself. "Should" means it wasn't run.
Quiz
A study-timer app for exams. Which one is a good acceptance criterion?
A) The timer should be accurate · B) The app should look modern · C) Start 25:00, wait 60 seconds → it shows 24:00 · D) Users should love it
Answer
C. Only C has an exact input and an exact expected result that anyone can check in a minute.
Interview questions
- What is a PRD? A product requirements document: the problem, users, features, non-goals, requirements and success criteria for a product, agreed before building.
- What makes a good acceptance criterion? It's specific and testable: a given situation or input, and an exact, observable result.
- How do you use a spec with an AI coding agent? Keep it in the repo (e.g. SPEC.md), ask the agent for gaps before code, build in steps, and verify each acceptance criterion yourself.
- Why write non-goals? They prevent scope creep: the AI and the team won't add features nobody agreed to.
Glossary
| Term | Meaning (plain words) | Example |
|---|---|---|
| AI agent | an AI that can create and edit files and run steps itself | Claude Code |
| Spec (specification) | a short document that decides what to build before building | SPEC.md |
| PRD | product requirements document: a company's bigger spec | a 5-page plan for a new app |
| User story | who needs what, and why | "As a flatmate, I want ..., so that ..." |
| Feature | something the app will do | "Settle up" |
| Non-goal | something you deliberately won't build (yet) | "No syncing between phones" |
| Acceptance criterion | a checkable test that says a feature is done | "120000.5 → ₹1,20,000.50" |
| Data model | what you store, and in which fields | amount_paise, paid_by |
| id | a unique label for one record | e_17 |
| Screen | what people see on one page | Add expense form |
| HTML | the language of web pages | index.html |
| localStorage | a small storage space in one browser on one device | survives a reload |
| Markdown | plain text with # headings and - bullets |
SPEC.md |
| Pixel (px) | one dot on a screen | a 360 px-wide phone |
| Validation | checking input and rejecting bad values with a message | "Amount must be more than 0." |
| diff | the exact lines that changed between two versions | < old / > new |
| README.md | the file that explains a project to people | "how to run it" |
| CLAUDE.md | Claude Code's project rules file, loaded at the start of each session | "Money is stored as integer paise" |
| Context | the information the AI has when it answers | the spec, the rules file |
Summary
- "Build me an app" gives you the AI's guesses, even when the code works.
- A spec decides first, on one page: problem, user stories, features and non-goals, data and screens, acceptance criteria, tech, decisions.
- Feed it to the AI, ask for gaps first, then build.
- Test every criterion yourself; specs can have bugs too, and the AI may not notice. Fix the spec first, then make one change.
README.mdis for people;CLAUDE.mdis for the agent and is loaded automatically.
Next episode: How AI coding agents work: the agent loop, context window, tokens, tools and permissions, diffs, and undoing a bad change.