Episode 150 · What counts as a group?

Spec before code: decide what you want before the agent decides for you

Friday, 17:00. The group discount shipped yesterday. Maya expected about 40 bookings a day to get 10% off. In 24 hours, 1,900 did: roughly 23,000 € of discounts nobody decided to give.

Before the agent writes a line, write down what you actually want. Otherwise it decides for you.

30 min intermediateWriting a spec before the agent codesAcceptance criteria (Given / When / Then)Decisions the human owns, not the agentWhat the agent knows: only what is in its contextUser problem before technology

Problem
"Add a 10% discount for group bookings." The agent ships it in fifteen minutes. A day later, 1,900 bookings got the discount instead of about 40.
Why the simple system fails
A short request feels clear to the person who wrote it, because they fill the gaps from their own head. The agent fills the same gaps from what is plausible: "group" became "3 or more guests".
Engineering concept
Every request contains decisions. A spec makes the important ones explicit before any code exists: rules, acceptance criteria you can check, what is out of scope, and what is still unknown.
Technology
A half-page spec in the repo or the request: problem, users, rules, Given/When/Then acceptance criteria, non-goals, open questions, plus asking the agent to list its assumptions before coding.
Trade-offs
Specs cost time up front and can over-constrain; no spec costs rework and silent wrong decisions. Scale the spec to the risk: money, data, permissions and other teams deserve one.

The problem

2 min

Friday, 17:00. Maya's one-line request, "Add a 10% discount for group bookings", shipped yesterday.

Maya · Product manager
1,900 bookings got it in 24 hours. I expected about 40. That's roughly 23,000 €.
You · Engineer at StayHub
The code says a group is any booking with 3 or more guests.
Maya · Product manager
A group is tour operators! Five rooms or more. Isn't that obvious?
Lina · Senior engineer, your mentor
Obvious to you. Guess first.

The big idea

4 min

The decisions hiding in one sentence

The big idea

Every request hides decisions. Write the important ones down before code exists, or the agent makes them for you.

The agent didn't misunderstand Maya; it never had the information. Decisions about money, personal data, permissions and other teams are yours. Naming, file layout and code structure, the agent can decide.

How it works

5 min

Order "a big cake for a party" from a baker who never asks, and you get chocolate for 40, with nuts. Wrong for your lunch for 12 with a nut allergy. The fix isn't a better baker; it's the order form. A is that order form: half a page, written before the code.

The five parts of a spec

1
Problem
Who hurts and why: tour operators book 5+ rooms and email support for a discount, ~40 bookings a day. The problem tells you what "group" means.
2
Rules you own
Group = one booking, 5+ rooms, same hotel and dates. 10% off the room rate before taxes. No stacking with promos: the larger wins. Recomputed on partial cancellation.
3
Acceptance criteria
are checkable statements of done, often Given / When / Then with real numbers. Put one at each edge case, the boundary where the rule flips: "Given 4 rooms, then no discount."
4
Non-goals
say what this change won't touch: no admin screen, no tax or email changes. Without them, a helpful agent grows the scope.
5
Open questions
Write down what nobody has decided ("Do corporate rates count?") and tell the agent to stop and ask, not pick.
6
Assumptions before code
Ask the agent to read the spec and list its assumptions and questions, no code yet. Answer them in the spec, so the next session sees them too.

Watch a decision being made

4 min

Worked example

Lina writes the group discount v2 spec with Maya

Replace the one-line request with a spec the agent can build from and you can review against, in about twenty minutes.

1Start from the problem, then decide the rules
Tour operators, 5+ rooms. So: one booking, 5+ rooms, same hotel and dates; 10% of the room rate before taxes; no stacking; recomputed on partial cancellation.
Why: Each rule is a money decision, exactly the gaps the agent filled last time.
2Write criteria at the boundaries
Given 4 rooms → no discount. Given 5 rooms at 100 € × 2 nights → 100 € off. Given 5 rooms + 15% promo → promo only.
gherkin
```
Given a booking with 4 rooms
When the guest checks out
Then no group discount is applied
```
Why: Bugs live where the rule flips: 4 vs 5 rooms.
3Fence the scope
Non-goals: no admin screen, no tax or email changes. Open question: corporate rates?
Why: Every extra the agent adds is a new risk to review.
4Make the agent show its guesses
"Read docs/specs/group-discount.md. List every assumption and question. No code yet." It asks three: corporate rates (no), rounding (per booking, to the cent), a separate invoice line (ask finance).
Why: Before code, a wrong guess is one line in a list. After, it's spread across code and tests that agree with it.

In real life

3 min

Two well-known ways to write before building

Working backwards (Amazon's PR/FAQ, described publicly)

Write the press release first
Then a detailed FAQ
Can't explain it? Don't build it

Thorough answers before any code.

Shaped pitch (Basecamp's Shape Up book)

Problem and appetite (a time budget)
Rough solution, explicit no-gos
Builders decide the details

Clear edges; details left to the team.

What goes wrong

3 min

Vague criteria ("works for groups", "handles edge cases")

Nobody can check them, so they're always "met".

Instead

Given / When / Then with real numbers, including the boundary.

Criteria for one currency or country only

The code covers only the cases the spec names.

Instead

Say whose currency (the hotel's), with one case per currency you serve.

Letting the agent write the only tests

Tests from the same assumption confirm it.

Instead

Your criteria become tests; the agent can add more.

Trade-offs

3 min

How much to write	Fits when	You pay
One-line request	Visible, reversible tweaks you'll check right away	Every gap filled silently
Half-page spec	Money, personal data, permissions, other teams	15–30 minutes up front
Full design document	Cross-system changes, migrations, hard to reverse	Days of work; can go stale

Tuesday, 9:30. After two expensive weeks.

Maya · Product manager
From now on, every change gets a full spec. Even labels.
Karim · CTO
Then we bought a tool that types in minutes and wait days for documents. Prompt, look, fix.
Maya · Product manager
"Look, fix" cost us 23,000 €.

Your job as tech lead

4 min

Claude Code can write the code for this. You still own the decisions, and you have to know what good looks like to accept or reject its work.

Decisions you own

The business rules: who qualifies (5+ rooms, not 3+ guests), the amount, before or after tax, stacking with promos.
Whose currency and which countries the rule covers, with one criterion per currency you serve.
The non-goals, and which open questions block the build and who answers them (Maya, finance, legal).

Tell Claude Code

Read docs/specs/group-discount.md and the pricing code in packages/pricing. Don't write code yet. List every assumption you'd need and every question the spec doesn't answer, especially rounding, currencies, promo codes and cancellations. After I answer, implement it so each acceptance criterion becomes a test with the same numbers. Don't change tax logic or confirmation emails. Run pnpm test and paste the output.

Check before you accept

Every assumption in its list is either in the spec or answered by you.
One test per criterion, same numbers: 4 rooms → none; 5 rooms × 100 € × 2 nights → 100 € off.
Nothing changed in tax logic, emails or admin screens.

Red flags

It starts coding a money rule without asking a single question.
Its tests use different cases from your criteria ("3 guests get 10%").
It hard-codes a currency or threshold the spec didn't state.

Check yourself

2 min

Q1/3Reasoning

Maya asked for "a 10% discount for group bookings". The shipped code treats any booking with 3+ guests as a group. Who made that decision?

How confident are you?

Next: the spec is perfect, and the agent wants to change 23 files to implement it. Will you read its plan first?

Finished?

Mark it complete to update your skill map.

Next: Plan before code: review the approach, not 1,400 lines

Go deeper (optional)You don't need this to understand the lesson. Open it when a project needs the details: Technical deep dive, Analogy, Why it matters, Check your understanding, Practice ladder, Explain it yourself.

Technical deep dive

A half-page spec

Worked example

Write the group discount v2 spec with Maya

Replace the one-line request with a spec the agent can build from and you can review against, then let the agent surface what you missed.

1Start from the problem
Tour operators book 5+ rooms and email support for a discount (~40 bookings/day). Goal: automatic, visible at checkout.
Why: The problem tells you what "group" means. Without it, the definition is a guess about words.
2Decide the rules you own
Group = one booking, 5+ rooms, same hotel, same dates. 10% off the room rate before taxes. No stacking with promo codes: the larger discount wins. Recomputed on partial cancellation.
Why: Each rule is a business decision about money. These are exactly the gaps the agent filled last time.
3Write criteria at the boundaries
Given 4 rooms → no discount. Given 5 rooms at 100 € × 2 nights → 100 € off. Given 5 rooms + 15% promo → promo only. Given 5 rooms, 1 cancelled → discount removed.
gherkin
```
Given a booking with 4 rooms
When the guest checks out
Then no group discount is applied
```
Why: Bugs live at boundaries. 4 vs 5 rooms is where the rule flips, so that's where a criterion must sit.
4Fence the scope
Non-goals: no admin screen for the percentage, no change to tax logic or confirmation emails. Open question: corporate rates?
Why: Without non-goals, a helpful agent adds settings pages and email tweaks, each a new risk to review.
5Make the agent show its guesses
"Read docs/specs/group-discount.md and the checkout pricing code. List every assumption and question. No code yet." It asks: corporate rates? Rounding? A separate invoice line? Maya answers; the spec is updated.
Why: The cheapest moment to correct a guess is before it becomes code and tests that agree with it.

Vague	Checkable
"Works for groups"	"Given 5 rooms, then 10% off the room rate"
"Handles edge cases"	"Given exactly 4 rooms, then no discount"
"Doesn't break promos"	"Given a 15% promo, then only the promo applies"

If you can't imagine the test, it isn't a criterion yet.

Analogy

Ordering a cakeAsking an agent

Ordering a cake"A big cake for a party"Asking an agentA one-line request
Ordering a cakeBaker picks the usual cakeAsking an agentAgent picks plausible defaults
Ordering a cakeOrder form: people, allergiesAsking an agentSpec: rules and criteria
Ordering a cake"No fruit on top"Asking an agentNon-goals
Ordering a cake"Can you do gluten-free?"Asking an agentOpen questions

Where the analogy breaks: you see a cake the moment it arrives. A wrong rule hides inside the code until a real guest hits it.

Why it matters

Agents turn words into code very fast. So the words become the weak spot.

A guessed rule doesn't look like a bug. The agent writes tests that match its own guess, and they all pass. Everything is green.

Then real guests arrive. A family of three gets a "group" discount. A fee is charged in the wrong currency. Code can be rewritten in minutes, but wrong charges on real cards can't.

A spec also makes checking easy. You go down the list of criteria, one by one. Done means done.

Check your understanding

Q1/3Design

Which are good acceptance criteria for the group discount? (Select all that apply.)

Select all that apply.

How confident are you?

Practice ladder

Step 1 · Trace

Find the silent decisions

Scenario Warm-up

Maya's next request: "Let hotels offer a free airport shuttle to guests who book 3+ nights."

List at least five decisions the agent would have to make silently, and for each, the plausible guess it might pick.

Step 2 · Complete

Finish the criteria

Design Practice

Lina started the acceptance criteria for the corrected date-change fee. Fill in the three missing ones.

Rule: the fee is set by the hotel, in the hotel's currency

Given a Lisbon hotel with a 20 EUR date-change fee
When a guest moves the stay to new dates
Then they are charged 20 EUR

Given a Chicago hotel with a 25 USD date-change fee
When a guest moves the stay to new dates
Then ___                                        (1)

Given a hotel with no date-change fee set
When a guest moves the stay to new dates
Then ___                                        (2)

Given a guest who paid a date-change fee
When ___                                        (3)
Then the fee is refunded

Step 3 · Solve

Spec: share dietary notes with hotel kitchens

Design Practice

Maya wants guests' dietary notes ("nut allergy", "vegan") from the booking form to appear on the hotel kitchen's breakfast list. Write a half-page spec for Claude Code: problem, rules, 4+ criteria, non-goals, open questions.

Step 4 · Decide

Which requests get a spec?

Decision Stretch

This week's requests for Claude Code:

Rename "Housekeeping" to "Rooms" in the ops tool's menu.
Let support agents issue goodwill vouchers up to 50 € without a manager.
Add a CSV export of the night's arrivals for hotel managers.

For each, decide one-line request or spec, then write your overall rule as "We chose X over Y because…, accepting the risk of…".

Explain it yourself

Karim says: "The agent writes code in minutes. Writing specs just slows us down. Prompt, look, fix." Explain when he's right and when he's wrong.

0 words