Vibe Coding: build real apps with AI · Episode 38. Every agent run below is real: Claude Code 2.1.323 (model claude-opus-5-5) in print mode (claude -p --permission-mode acceptEdits), on 13 November 2026 (India time), in /home/asha/projects/tuition-register. The agent could edit files and run only npm install, npm test, node --test, npm init, mkdir and ls; anything else needed approval and was refused. Replies are quoted exactly, shortened where marked "...". Every browser test (Playwright Chromium at 360 × 740), sqlite3 query, git command and the "1 December" check below were run by us.
What was written by hand: SPEC.md (the spec and the Decisions) was written by Asha, before any code. All app code is the AI's. Sunita Ma'am, Asha and the students (Riya, Aditya, Sana, Om, Meher) are fictional.
Tools: Node.js v22, Express 4.22.3, better-sqlite3 13.1.1, Node's built-in test runner (node --test), the sqlite3 command-line tool, git 2.43.0, Playwright Chromium.
The project: the full source at the end of this episode (commit 22ba997) is kept for part 2. Nothing was deployed or published: it runs on localhost only.
The problem: a Diwali dinner for twenty guests
You don't start a big family dinner by frying random things.
| A big family dinner | Your capstone |
|---|---|
| A menu for these guests (who's coming, what they eat) | Choose a problem: a real person, a real pain |
| The menu and shopping list, written before you cook | Spec + data model: decided before code |
| One dish at a time, tasted, then covered and set aside | Small steps + checkpoints: test, then commit |
A capstone is the final project that puts the whole course together: a real product, planned and built by you, with an AI agent doing much of the typing.
Choosing a problem
The obvious first idea fails
"An app for every tuition teacher in India!" fails before a single line of code:
- Who do you ask what they need? Nobody in particular. Every teacher wants something different.
- It never ends: logins, online payments, SMS, ten languages...
- You can't say when it's done.
Built for everyone means built for no one. A project too big to finish is too big to learn from.
Four questions
- Is there a real person I can talk to this week?
- Do they feel the pain every week (not once a year)?
- Can version 1 be built in a few evenings?
- Can I write a list that says when it's done?
Version 1 (v1) = the first small version that does the core job and nothing more.
Asha's maths teacher, Sunita Ma'am, passes all four: 3 batches, about 18 students, attendance and fees in one notebook. At month end she can't say who has paid, and "I paid you on the 5th" means searching WhatsApp for twenty minutes. She wants one page on her phone, used between batches.
The one-page spec
A spec (specification) is one page that says what you're building before anyone builds it (episode 5). Teams also call it a PRD, a product requirements document.
# Tuition Register: one-page spec
## Problem
Sunita Ma'am teaches maths at home: 3 batches, about 18 students. Attendance and fees live in
a notebook. At the end of the month she can't say who has paid, and when a parent says
"I paid you on the 5th" she has to search WhatsApp.
## User
Sunita Ma'am, on her phone, at her dining table, between batches. Only she uses it.
## User stories
1. As Sunita, I mark today's attendance for one batch in under a minute.
2. As Sunita, I see who has NOT paid this month's fee, at a glance.
3. As Sunita, I record a payment (amount, date, cash or UPI) when a parent pays.
4. As Sunita, I open one student and see their attendance and payments.
## Features (version 1)
- Students: add, edit, mark as left (never delete: old fees stay).
- Batches: fixed list: "Class 8 (4 pm)", "Class 9 (5 pm)", "Class 10 (6 pm)".
- Attendance: one tap per student, for a chosen date (default today).
- Fees: monthly fee per student; payments recorded against a month.
## Non-goals (not in version 1)
- No parent logins, no WhatsApp messages, no online payments, no marks/tests.
## Data we store
- Student: name, batch, monthly fee (rupees), joined on, left on (optional).
- Attendance: student, date, present or absent.
- Payment: student, for month (e.g. 2026-11), amount, paid on, mode (cash/UPI).
- No phone numbers or addresses (we don't need them).
## Screens
1. Today: pick batch -> list of students with Present/Absent.
2. Fees: this month: paid, partly paid, not paid; tap to record a payment.
3. Student: details, this month's attendance, all payments.
## Acceptance criteria
1. Marking attendance twice for the same student and date keeps ONE record (the last tap).
2. A student who has paid Rs 1500 of a Rs 1500 fee shows "Paid"; Rs 1000 shows "Partly paid (Rs 500 due)".
3. A student who left last month does not appear on Today or as "Not paid" this month.
4. "This month" is the month in India time (Asia/Kolkata), also at 11:30 pm on the last day.
5. Works on a 360 px wide phone screen without sideways scrolling.
6. Restarting the server keeps all data.
- User story: one need, written from the user's side: As Sunita, I .... Every feature should trace back to one.
- Non-goal: something you deliberately won't build yet. Non-goals stop the never-ending app.
- Acceptance criterion: a check that either passes or fails. Together, the criteria define done.
- No phone numbers: we don't need them, so we don't collect them (episode 34).
Ask the AI for gaps first (real)
$ claude -p "Read SPEC.md. Before writing any code: list the gaps or contradictions in this spec that you need me to decide, numbered, at most 6, one line each. Then propose a data model (tables and columns) and a build plan in 3 small steps, each one ending with something I can test. Don't write any files yet."
The real reply (shortened):
Decisions I need from you 1. Hosting and access: where does the server run, and how does her phone reach it? If it's on her home Wi-Fi only, it can skip a login. If it's on the internet, it needs at least a PIN or password, and the spec doesn't mention one. 2. Fee changes: if a student's monthly fee goes from Rs 1500 to Rs 1800, should past months still be judged against Rs 1500? ... 3. Joining or leaving mid-month: does a student who joins on the 20th, or leaves on the 10th, owe the full fee for that month? ... 4. Old dues and extra money: should the Fees screen show unpaid amounts from earlier months? And if a parent pays more than the fee, or pays for two months at once ... 5. Students with no tap yet: on Today, is a student nobody has tapped counted as absent, or shown as "not marked"? ... 6. Past months and dates: can she browse the Fees screen for an earlier month, or only the current one? ...
attendance ... One row per student per date. Each tap overwrites that row, which covers acceptance criterion 1.
Build plan: 1. Students and the Today screen. 2. Payments and the Fees screen. 3. Student screen and phone layout.
A gap is a question the spec doesn't answer. Answering six of them takes a minute now; finding them after the code is written costs a rewrite.
Our answers: the Decisions section
## Decisions (answers to the AI's questions, 13 Nov)
1. Version 1 runs on Sunita's laptop, used from her phone on home Wi-Fi. No login yet (a PIN comes before launch).
2. One current monthly fee is enough.
3. A student owes the full fee for any month they attend at all (joined or left mid-month: full fee).
4. Fees screen shows this month only. One payment = one month; she splits it herself.
5. Not tapped = "Not marked". Two buttons: Present, Absent.
6. Only the current month on Fees. A past date on Today shows the students who were current on that date.
## Stack
Node.js 22, Express, better-sqlite3 (file: data/register.db), server-rendered pages, no front-end framework.
Tests: node --test. Port 3000.
You decide; the AI asks. The stack is the set of tools the app is built with: Node.js runs JavaScript on a computer, Express is a small web-server library, SQLite is a database that lives in one file, used through the better-sqlite3 package. Server-rendered pages = the server builds each HTML page and sends it; there's no front-end framework.
Decisions 4 and 6 come back later.
The data model
A data model is the plan for your data: which tables, which columns, and how they connect.
| Register word | Database word | Example |
|---|---|---|
| A register page | Table | attendance |
| One line on the page | Row | Riya, 13 Nov, present |
| A heading | Column | date |
| What makes a line unique | Key | (student, date) |
The AI's tables (from src/db.js, after step 2):
CREATE TABLE IF NOT EXISTS students (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
batch TEXT NOT NULL,
monthly_fee INTEGER NOT NULL CHECK (monthly_fee >= 0),
joined_on TEXT NOT NULL, -- YYYY-MM-DD
left_on TEXT -- YYYY-MM-DD, first day no longer a student
);
CREATE TABLE IF NOT EXISTS attendance (
student_id INTEGER NOT NULL REFERENCES students(id),
date TEXT NOT NULL, -- YYYY-MM-DD
status TEXT NOT NULL CHECK (status IN ('present', 'absent')),
PRIMARY KEY (student_id, date)
);
CREATE TABLE IF NOT EXISTS payments (
id INTEGER PRIMARY KEY,
student_id INTEGER NOT NULL REFERENCES students(id),
for_month TEXT NOT NULL, -- YYYY-MM
amount INTEGER NOT NULL CHECK (amount > 0),
paid_on TEXT NOT NULL, -- YYYY-MM-DD
mode TEXT NOT NULL CHECK (mode IN ('cash', 'upi'))
);
CREATE INDEX IF NOT EXISTS payments_by_month ON payments (for_month, student_id);
- SQL is the language databases speak.
- Primary key: the column (or pair of columns) no two rows may share.
PRIMARY KEY (student_id, date)means a second tap can't add a second row; the app overwrites it (ON CONFLICT ... DO UPDATE). The data model itself makes criterion 1 true. - Foreign key (
REFERENCES students(id)): a column that points at a row in another table. CHECK: a rule the database enforces (no negative fee, onlypresent/absent).- Money is stored as whole rupees in an
INTEGER, never a decimal. - The AI left the separate
batchestable out and used the fixed batch names; that's fine for three fixed batches. - Notice two dates in one payment row:
for_monthandpaid_on.
Screens
A screen is one page with one job.
| Screen | Job | What she taps |
|---|---|---|
| Today | Mark attendance for one batch | Batch tab, then Present / Absent |
| Fees | Who hasn't paid, first | A student, to record a payment |
| Student | One child's attendance and payments | (step 3, part 2) |
Sketch each on paper first and design for her real phone: 360 px wide (a pixel, px, is one dot on the screen).
Small steps and checkpoints
The plan: three steps, each ending with something we test ourselves. After each one we make a checkpoint: a Git commit of a version that works. If the next step goes wrong, we go back to it (episode 26).
Step 1: students and the Today screen (real)
$ claude -p "SPEC.md now has a Decisions section answering your 6 questions, and the stack. Build step 1 only: students (add, edit, mark as left) with the three batches, and the Today screen. Write tests for acceptance criteria 1, 3 and 6 and run them. Don't build Fees or the Student screen yet. When you're done, tell me exactly how to test it myself."
Bash npm install express@4 better-sqlite3
Write src/db.js, src/dates.js, src/views.js, src/app.js, server.js
Bash npm test # Error: Cannot find module '/home/asha/projects/tuition-register/test'
Edit package.json "test": "node --test \"test/**/*.test.js\""
Write test/acceptance.test.js, test/pages.test.js
Bash npm test # tests 13 pass 13 fail 0
From its reply:
Criterion 3 is only half tested. The "not shown as Not paid" part belongs to the Fees screen, so it gets tested when Fees is built.
Criterion 5: on the phone, check that nothing scrolls sideways. I designed for 360 px but couldn't check it on a real screen here.
Fees and the Student screen are not built, and nothing is committed yet.
Its first test command failed with a real error (node --test test/ tried to load a folder as a module); it fixed the script itself.
Our checks

We added five students to Class 9 in Chromium at 360 × 740, then tapped Riya: Present, Present, Absent, Present.
$ sqlite3 data/register.db "SELECT s.name, a.date, a.status FROM attendance a JOIN students s ON s.id = a.student_id;"
Riya Sharma|2026-11-13|present
Aditya Kulkarni|2026-11-13|present
Sana Shaikh|2026-11-13|absent
page width at 360 px: 360
$ git add -A && git commit -m "Step 1: students and Today screen (13 tests pass)"
$ git log --oneline
b06a76c Step 1: students and Today screen (13 tests pass)
05ef1da Spec: decisions and stack
62887ca Spec for Tuition Register v1
Four taps, one row: criterion 1 holds in the real data, not just in a test.
Step 2: payments and the Fees screen (real)
$ claude -p "Step 1 works: I tested it on a 360 px phone screen in Chromium and committed it (b06a76c). Now build step 2 only: payments and the Fees screen, as in SPEC.md (Paid / Partly paid (Rs X due) / Not paid for this month in India time; tap a student to record a payment: amount, date, cash or UPI). Write tests for acceptance criteria 2, 3 (the Fees half) and 4, and run them. Don't build the Student screen yet."
Edit src/db.js, src/app.js, src/dates.js, src/views.js, test/...
Bash npm test # tests 26 pass 26 fail 0
From its reply:
AC4: at 11:30 pm on 30 Nov in India the screen, the form date and the saved payment all say November. ... I checked the AC4 tests work by making the month use UTC on purpose: the 1 Dec test failed, and I then put the correct code back.
Which month a payment counts for: always the current month, set by the server. There's no month picker, per Decisions 4 and 6.
The 360 px check (AC5) is still to do. I haven't opened the new screens in a browser ...
We recorded Riya Rs 1500 cash and Aditya Rs 1000 UPI in Chromium:

"Not paid" first, then "Partly paid (Rs 500 due)", then "Paid": the spec's exact words. The page is 360 px wide (criterion 5 passes), but the header now wraps: "Students" fell onto a second line. Measuring passed; looking didn't. We committed step 2 (4449c1b).
The AI mistake: a November payment filed as December (real)
We tested like Sunita's real life, not like the spec: Sana's mother pays Rs 1500 cash, for November, on the evening of 30 November. Sunita types it in the next morning, 1 December, 9 am.
To test a future date, we started the app with its clock pinned (the AI made now injectable for tests), on a copy of the database:
// our check: Sunita enters, on 1 Dec at 9 am, the Rs 1500 Sana's mum paid on 30 Nov evening
const { createApp } = require('./src/app');
const app = createApp({ dbPath: '/home/claude/ep38runs/dec/register.db',
now: () => new Date('2026-12-01T09:00:00+05:30') });
const srv = app.listen(3100, async () => {
const body = new URLSearchParams({ amount: '1500', paid_on: '2026-11-30', mode: 'cash' });
const r = await fetch('http://localhost:3100/fees/3/pay', { method: 'POST', body, redirect: 'manual' });
console.log('POST /fees/3/pay ->', r.status);
const html = await (await fetch('http://localhost:3100/fees')).text();
console.log(html.match(/<h1>[^<]*/)[0].slice(4));
const m = html.match(/Sana Shaikh[\s\S]*?data-fee="\w+">([^<]*)/); console.log('Sana Shaikh:', m[1]);
srv.close(); app.locals.db.close();
});
Real output:
POST /fees/3/pay -> 303
Fees · December 2026
Sana Shaikh: Paid
$ sqlite3 register.db "select s.name, p.amount, p.paid_on, p.for_month from payments p join students s on s.id=p.student_id"
Sana Shaikh|1500|2026-11-30|2026-12
Paid on 30 November, filed under December. November's fee looks unpaid, and in December nobody will ask for December's fee: Rs 1500 quietly lost.
Why
app.post('/fees/:id/pay', (req, res) => {
...
r.addPayment({ ...value, student_id: student.id, for_month: month() });
...
});
month() is the month in India time right now, when she taps Save. The paid_on date she typed is never used for the month. The tests passed because they pinned the clock to 30 Nov 11:30 pm and checked for "November": they tested exactly what the AI assumed. Green tests can't catch an assumption they share with the code.
To be fair, our own Decision 4 said the Fees screen shows only this month, and the AI even wrote "always the current month". A spec can be wrong too; only real-life testing showed what that means at a month's edge.
"Fix it": the vague prompt (real)
$ claude -p "Payments are going into the wrong month. Fix it."
I fixed one real cause of payments landing in the wrong month. I couldn't check your actual records, though, so I can't be sure it's the one you saw. All 27 tests pass, including a new one for this case. Nothing is committed.
What was wrong: the app chose the month when Save was tapped, not when the payment form opened. If Sunita opened "Record a payment for November" at 11:58 pm on 30 Nov and saved at 12:01 am, it was silently filed under December. ...
This may not be what you're seeing. If she records a late payment, say a parent pays October's fee on 3 November, it goes into November. That's because the spec (decisions 4 and 6) says Fees only works on the current month. If that's the problem, it's a spec change ...
It fixed a different bug: real, but rare, and not Sana's case. A vague prompt makes the AI guess; this one guessed carefully, and said so.
Rolling back with Git (real)
We didn't ask for that change, so we don't keep it:
$ git status --short
M src/app.js
M src/views.js
M test/acceptance.test.js
$ git diff --stat
src/app.js | 13 +++++++++++--
src/views.js | 1 +
test/acceptance.test.js | 20 ++++++++++++++++++++
3 files changed, 32 insertions(+), 2 deletions(-)
$ git restore .
$ git status --short
$ git log --oneline -1
4449c1b Step 2: payments and Fees screen (26 tests pass)
Rolling back = returning to a known good version. git restore . puts every tracked file back to the last commit. (New, untracked files would also need git clean -fd; there were none.) It took one second because we committed first.
Fix the spec, then the code
The spec was wrong, so the fix starts there (committed as 1c4bfbf):
4. One payment = one month; she splits it herself. She chooses which month a payment is for:
last month, this month or next month (default: this month). (changed 13 Nov)
6. Fees opens on this month, with a link to last month (so late payments and old dues are visible). (changed 13 Nov)
A past date on Today shows the students who were current on that date.
## Acceptance criteria
7. A payment made on 30 Nov and typed in on 1 Dec, for November, counts for November, not December.
A real bug becomes a new acceptance criterion, so it can't come back without failing a test.
The evidence prompt (real)
$ claude -p "A real case, not a guess. Sana's mother paid Rs 1500 cash for NOVEMBER on 30 Nov evening. Sunita typed it in on 1 Dec at 9 am (paid on: 2026-11-30). The app saved for_month = 2026-12, so December shows Sana as Paid and November's fee looks unpaid. I checked it with createApp and now pinned to 2026-12-01T09:00+05:30:
Sana Shaikh|1500|2026-11-30|2026-12
I updated SPEC.md (commit 1c4bfbf): Decisions 4 and 6 changed, and acceptance criterion 7 is new. Make only that change: a 'For month' choice on the payment form (last month, this month, next month; default this month), and a link from Fees to last month. Add a test for criterion 7 and run all tests. Also, at 360 px the header now wraps: 'Students' falls onto a second line. Keep the three header links on one line. Nothing else."
Bash npm test # tests 29 pass 29 fail 0
From its reply:
I had to change two existing tests because the spec changed: One checked the old form heading "Record a payment for November 2026". It now checks that November is the default choice. One expected the payment page to be refused for a student who left in October. Now the page opens offering October only, and a November payment is still refused.
Sana's real record isn't fixed. The database still has her payment saved for 2026-12, and the app can't edit or delete payments. I didn't touch the data. ...
This could lead to the same mistake again. If Sunita opens last month's list and taps a student, the form still defaults to this month, as the spec says. So she could save a November payment as December again. ... I've left it for you to decide.
Header at 360 px: ... I checked this from the CSS only, not in a browser.
Always read "I changed existing tests": changing tests is how bugs hide. Here both changes follow the spec change. (Sana's wrong row was only in our test copy, not Sunita's real data.)
The key part of the AI's fix (src/app.js):
// A payment can be for last month, this month or next month (Decision 4).
// Only months the student was a student in are offered.
const monthChoices = () => [-1, 0, 1].map((n) => addMonths(month(), n));
const payMonths = (student) => monthChoices().filter((m) => r.isCurrentInMonth(student, m));
...
const forMonth = req.body.for_month === undefined ? month() : req.body.for_month;
if (!monthChoices().includes(forMonth)) {
errors.push('Choose last month, this month or next month.');
} else if (!payMonths(student).includes(forMonth)) {
errors.push(`${student.name} was not a student in ${prettyMonth(forMonth)}.`);
}
...
r.addPayment({ ...value, student_id: student.id, for_month: forMonth });
and its test for criterion 7 (excerpt from test/acceptance.test.js):
test('saved for November: November shows Paid, December still shows Not paid', async () => {
const res = await pay(t, id, { amount: '1500', paid_on: '2026-11-30', mode: 'cash', for_month: '2026-11' });
assert.equal(res.status, 303);
...
assert.equal(feeLabel(dec, 'Sana Shaikh'), 'Not paid');
...
assert.equal(feeLabel(nov, 'Sana Shaikh'), 'Paid');
});
Our checks again


Same 1 December check on a fresh copy, now sending for_month=2026-11:
POST /fees/3/pay -> 303
Fees · December 2026 Sana Shaikh: Not paid
Fees · November 2026 Sana Shaikh: Paid
Sana Shaikh|1500|2026-11-30|2026-11
header height at 360 px: 56
$ git log --oneline
22ba997 Payments: choose the month (criterion 7); Fees links to last month; header fits 360 px (29 tests pass)
1c4bfbf Spec: choose the month a payment is for; Fees can show last month; criterion 7
4449c1b Step 2: payments and Fees screen (26 tests pass)
b06a76c Step 1: students and Today screen (13 tests pass)
05ef1da Spec: decisions and stack
62887ca Spec for Tuition Register v1
Six checkpoints: git log reads like the project's diary.
Capstone checklist
- [ ] A real person, a weekly pain, a few evenings, checkable.
- [ ] One-page spec: user stories, non-goals, data, screens, acceptance criteria.
- [ ] Ask the AI for gaps and a plan before code; answer them in a Decisions section.
- [ ] Data model first: keys that make bugs impossible.
- [ ] One step per prompt; test it yourself; commit.
- [ ] Test like real life (a late payment typed in the next morning), not like the spec.
- [ ] Bad change?
git restore .Real bug? Fix the spec, add a criterion, send the evidence.
Common mistakes (real)
| Mistake | What we saw | Why | Fix |
|---|---|---|---|
| An app for everyone | no user, no end, no "done" | Too big | One real person, four questions |
| Payment month = today (the AI's) | Sana Shaikh\|1500\|2026-11-30\|2026-12 |
Assumed, untested | Choose the month + criterion 7 |
| Tests share the assumption | tests 26 pass 26 |
Same idea in code and tests | Real-life checks |
| "Fix it" (vague) | fixed a different bug | No evidence | git restore . + the exact case |
| Measured, not looked | "Students" on a second line | Width was fine | Look at the screen |
| First test script (the AI's) | Error: Cannot find module '.../test' |
node --test test/ loads a folder as a module |
node --test "test/**/*.test.js" |
Mini project: start your capstone
- Write three problem ideas. Score each with the four questions; pick the one with four yes.
- Talk to the person for ten minutes. Write the problem and user sections of
SPEC.mdin their words. - Write 3-5 user stories, non-goals, the data you store (and what you won't), the screens, and 5-7 acceptance criteria.
- Ask your AI tool for the gaps and a 3-step plan, with no files. Answer every gap in a Decisions section. Commit.
- Build step 1 only. Test every criterion it claims yourself, in a real browser at phone width. Commit.
- Invent one real-life test that the spec didn't think of (a late payment, a holiday, a student who changes batch) and run it.
Practice questions
- Your idea is "a food delivery app for my city". Apply the four questions.
Answer
Usually fails 1-4: no specific person, huge scope, not buildable in a few evenings, no clear "done". Narrow it to one real user: e.g. "my uncle's tiffin service: who wants lunch tomorrow, and who has paid this week".
- Turn "the app should be fast" into an acceptance criterion.
Answer
Something that passes or fails, e.g. "The Fees screen opens in under 1 second on her phone on home Wi-Fi with 20 students."
- Why does
PRIMARY KEY (student_id, date)make criterion 1 easier?
Answer
The database refuses a second row for the same student and date, so a second tap can only update the existing row.
- All 26 tests passed, yet a payment went to the wrong month. How?
Answer
The tests were written with the same assumption as the code (month = today), so they checked that assumption instead of real use (a payment typed in the next day).
- The AI changed three files you didn't ask it to. Which commands show what changed and undo it?
Answer
git status, git diff --stat (and git diff), then git restore . (plus git clean -fd for new untracked files) to go back to the last commit.
- When should a bug change the spec instead of just the code?
Answer
When the code did what the spec said and real life shows the spec was wrong (here: Decisions 4 and 6). Fix the spec, add an acceptance criterion, then ask for the code change.
Quiz
The AI's fix isn't what you asked for. Best next step?
A) Keep it: all tests pass · B) git restore . then a prompt with the exact case and evidence · C) Delete the project and start again · D) Ask "fix it properly this time"
Answer
B: go back to the last checkpoint, then give the AI the real case, the evidence and one change. A keeps a guess, C throws away good work, D is still vague.
Interview questions
- How do you scope a side project so you finish it? One real user, a weekly pain, a v1 of a few evenings, written non-goals and acceptance criteria.
- What's in a one-page spec / PRD? Problem, user, user stories, features, non-goals, data, screens, acceptance criteria, then decisions and stack.
- How do you work with an AI agent on a new codebase? Plan first (gaps, data model, steps), one step per prompt, tests plus my own checks, a commit after each working step.
- Tell me about a bug the AI introduced. A payment's month came from the save time, not the month it was for; tests shared the assumption; caught by a real-life test with a pinned clock; fixed in the spec (new criterion) and then the code.
- Why commit before asking an AI for a change? So you can see exactly what it changed (
git diff) and undo it instantly (git restore).
Glossary
| Term | Meaning (with an example from this episode) |
|---|---|
| Capstone | The final project that brings the whole course together (Sunita's register). |
| Version 1 (v1) | The first small version that does the core job (attendance + fees). |
| Spec (specification) | One page saying what you'll build before you build it (SPEC.md). |
| PRD | Product requirements document: another name for a spec. |
| User story | One need from the user's side: "As Sunita, I mark today's attendance...". |
| Feature | Something the app does (record a payment). |
| Non-goal | Something deliberately not built yet (no parent logins). |
| Acceptance criterion | A pass/fail check; together they define done (criterion 7). |
| Gap | A question the spec doesn't answer (does a fee rise change old months?). |
| Decisions section | Your written answers to the gaps, in the spec. |
| Stack | The set of tools the app is built with (Node, Express, SQLite). |
| Node.js | Runs JavaScript on a computer, outside the browser. |
| Express | A small library for building web servers in Node. |
| SQLite / better-sqlite3 | A database stored in one file / the Node package to use it. |
| Server-rendered page | HTML built on the server and sent to the browser. |
| Data model | Which tables and columns, and how they connect. |
| Table | Like a register page (attendance). |
| Row | One line in a table (Riya, 13 Nov, present). |
| Column | One heading (date). |
| Key / primary key | What makes a row unique; no two rows may share it (student_id, date). |
| Foreign key | A column pointing to a row in another table (REFERENCES students(id)). |
| SQL | The language used to create and query databases. |
| Screen | One page with one job (Today, Fees, Student). |
| Pixel (px) | One dot on the screen; her phone is 360 px wide. |
| Checkpoint | A Git commit of a version that works (b06a76c). |
| Commit | A saved snapshot of the project in Git. |
git log |
The list of commits: the project's diary. |
git status / git diff --stat |
Which files changed / how many lines in each. |
git restore . |
Put tracked files back to the last commit. |
| Rollback | Returning to a known good version. |
| Agent | An AI that edits files and runs commands in a loop (Claude Code). |
| Test / test runner | Code that checks code / the tool that runs tests (node --test). |
| Pinned clock | Starting the app with a fixed "now" to test a date (1 Dec, 9 am). |
| Evidence prompt | A prompt with the exact case and what you saw, not "fix it". |
| Time zone (Asia/Kolkata) | India time; "this month" is decided in it. |
| UPI | India's instant bank-to-bank payment system; here just a payment mode label. |
Summary
- Choose a problem with four questions: a real person, a weekly pain, a v1 in a few evenings, a checkable "done".
- Write a one-page spec with user stories, non-goals, data, screens and acceptance criteria; ask the AI for gaps and a plan before any code, and answer them yourself.
- Design the data model first:
PRIMARY KEY (student_id, date)made "one record per tap" automatic. - Build one step per prompt, test it yourself in a real browser, and commit a checkpoint.
- The AI's careful code and 26 green tests still filed a November payment under December, because code and tests shared the assumption "month = today". A real-life test found it.
- "Fix it" made the AI fix a different bug;
git restore .took us back. The real fix started in the spec (criterion 7), then an evidence prompt; 29 tests and our re-check pass.
Next episode: Capstone part 2: test, secure and launch.