Episode 161 · A goal, a deadline, no architecture

From business goal to architecture decision

Monday, 9:05. Karim makes you tech lead of StayHub's biggest project yet: hotel chains. Atlantica's 420 hotels sign if a 20-hotel pilot is live in 12 weeks. By 9:30, Claude Code has written a 14-page architecture. It looks great. Is it the right one?

A big project starts as one sentence from the business. You turn it into numbers, compare a few real options, measure the scary unknown, and write down the decision.

30 min advancedTurning a business goal into measurable targets and constraintsComparing architecture options against the driversThe agent researches and prototypes; the lead decidesTime-boxed spike on the riskiest assumptionArchitecture decision recordsProblem → requirements → constraints → options → trade-offs → decision

Problem
StayHub must win hotel chains: Atlantica's 420 hotels sign only if their central reservation system can drive StayHub prices, with a 20-hotel pilot in 12 weeks. You are the tech lead, and there is no architecture yet.
Why the simple system fails
Asking Claude Code "design the architecture" returns a polished, confident design in minutes. It answers a question nobody wrote down, picks technologies by habit, and hides the one assumption that decides everything: can StayHub absorb 600,000 price changes in minutes?
Engineering concept
Goal → measurable targets and constraints (the decision drivers) → two or three real options → a spike on the riskiest assumption → a decision written as an ADR, with the trade-off accepted and what would make you revisit it. The agent researches, drafts and prototypes; the lead decides.
Technology
Decision drivers, quality targets, options tables, time-boxed spikes in a throwaway branch, ADRs in the repository, Claude Code in plan mode for read-only research.
Trade-offs
Deciding fast keeps the team busy but can lock in a wrong one-way door; spiking and writing an ADR costs days but buys evidence. Spend the time where the decision is expensive to reverse, and decide quickly where it isn't.

The problem

2 min

Monday, 9:05. StayHub has ~10,000 partner hotels and has never won a hotel chain.

Karim · CTO
You're tech lead for StayHub for Chains. Atlantica, 420 hotels, signs if a 20-hotel pilot is live in 12 weeks.
Maya · Product manager
Their own reservation system sets every price. They won't type prices into our dashboard.
You · Engineer at StayHub
Claude Code already drafted an architecture: Kafka, a new database for rates, GraphQL, a nightly CSV import. Fourteen pages.

The big idea

4 min

Fourteen pages in twenty minutes

The big idea

Goal as numbers, drivers, two or three options, a spike for the unknown, an ADR. The agent researches and measures; you decide.

Without written drivers, the agent fills the gaps with its habits and produces something plausible nobody can evaluate. With them, every option can be checked line by line.

How it works

5 min

An architect asks how many people, what budget, what the rules allow, then sketches two or three houses, and pays for a soil test before choosing. Soft ground changes everything.

From a sentence to a decision

1
You: goal as numbers
20 hotels in 12 weeks, 420 in 20; a price change visible in search within 5 minutes (p95); guest search may not slow by more than 20%.
2
You rank the drivers
A is a target or constraint that shapes the choice. A chain-wide change is 420 × 365 × 4 ≈ 613,000 updates; the rates API is safe at ~300 writes/s (34 min). Claude finds the limits in code; you rank them.
3
Agent lists options; you cut
An option is one real way to meet the drivers, with cost and risk. One option is not a decision. Remove options with a driver, not with taste.
4
Agent runs the spike
A is a short, time-boxed experiment that measures one unknown. You set the question and time box; its code is thrown away.
5
You sign the ADR
An records context, options, choice, the trade-off accepted and when to revisit. The agent drafts; you check every number.

Watch a decision being made

4 min

Worked example

Lina thinks out loud: from "win chains" to ADR-047

Decide how chains send rates and availability, in the first week.

1Find the limits in the real system
Claude Code, plan mode, read-only: the rates API is synchronous, one hotel per call, ~300 writes/s. A 613,000-update burst takes ~34 minutes today.
Why: Research is where the agent shines: fast, checkable, deciding nothing.
2Cut options with drivers
A (bulk CSV): fails freshness, out. B (we pull): ~5,100 requests at Atlantica's 10/s = 8.5 min, fails. C (chains push, queue, batch apply): fits, if the database absorbs bursts.
Why: Removing options with a driver makes the choice defensible.
3Spike the deciding unknown
Two days, branch spike/ari-batch, staging copy only, "don't recommend". Batches of 500: ~4,000 rows/s, a burst in ~2.5 min; search p95 120 → 135 ms. Branch deleted.
Why: An hour of opinion became a number.
4Write and sign ADR-047
Option C inside today's platform. Trade-off: a public API to version for years. Revisit if a chain can't push or bursts exceed ~1.5M. Signed with Karim and Maya.
Why: A one-way door; the reasons must outlive this team.

In real life

3 min

Grow one system, or split into many?

Shopify: modular monolith

One large codebase kept
Strong boundaries inside it
Publicly described by its engineers

Fewer moving parts to run.

Amazon: team-owned services

Small teams own services
Talk only through APIs
Widely described publicly

Teams move independently, at operating cost.

What goes wrong

3 min

Adopting the agent's first architecture

It was designed for a goal it guessed.

Instead

Goal and drivers first, then options against them.

Shipping the spike's code

No tests, shortcuts, staging assumptions.

Instead

Delete the branch; rebuild properly from a spec.

A new technology nobody on call can run

The first incident lasts hours.

Instead

Make "operable by today's team" a driver.

Trade-offs

3 min

Approach	Fits when	You pay
Decide now from the proposal	Two-way doors you can change in a day	Unknowns become bets
Drivers, options, spike, ADR	Public APIs, data models, new infrastructure	Days before building the core
Build two options	Rarely: no spike can answer it	Double cost; the loser lingers

Monday of week 1, 17:00. The options table is done.

Karim · CTO
Option C is obviously right. Skip the spike. Eight engineers are waiting.
Lina · Senior engineer, your mentor
Only if the database takes 613,000 updates in five minutes. Nobody knows that.
Karim · CTO
And if it's fine, we lost two days.

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 goal as numbers and the deadline: 20-hotel pilot in 12 weeks, changes visible in search within 5 minutes.
Which drivers rank first, and which unknown deserves a spike (question, time box, data allowed).
The decision, the trade-off accepted and the "revisit if", signed with Karim and Maya.

Tell Claude Code

Read docs/projects/chains/goal.md. Plan mode, don't edit. Research only: find every place that writes to the rates table, how the partner rates API handles writes today, and any measured limits in our dashboards or load tests. List two or three ways chains could send rates, and for each say which drivers it meets or fails, with file paths or numbers. Don't recommend an option or new technologies.

Check before you accept

Every claim about a limit points to code, a dashboard or a load test you can open.
The spike has one question, a time box, staging data, and its branch is deleted after.
You verified every number in the ADR draft.

Red flags

New technologies no driver asked for.
"Option C is clearly best" with no measurement behind it.
Spike code tidied up and proposed as the first production version.

Check yourself

2 min

Q1/3Scenario

Karim makes you tech lead of StayHub for Chains. Claude Code is open. What do you do first?

How confident are you?

Next: ADR-047 is signed. Karim wants a plan by Friday, and Claude Code has just produced 112 tasks in four minutes.

Finished?

Mark it complete to update your skill map.

Next: Breaking down a big project

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

Technical deep dive

The spike that decided it

Worked example

From "win chains" to ADR-047

Turn Karim's goal into an architecture decision for how chains send rates and availability, using Claude Code for research and the spike, in the first week.

1Write the goal as numbers
20 Atlantica hotels in 12 weeks, 420 in 20. A CRS change visible in search within 5 min (p95). Guest search p95 may not degrade by more than 20%.
Why: Every option will be checked against these lines. If a target is vague, the decision will be too.
2Find the drivers in the real system
Ask Claude Code, in plan mode, to find every place that writes rates and the limits of the rates API. It reports: synchronous, one hotel per call, safe at ~300 writes/s. You compute the burst: 420 × 365 × 4 ≈ 613,000 updates, ~34 min today.
Why: Read-only research is where the agent shines: fast, checkable, and it decides nothing.
3Keep two or three real options
A (bulk CSV) fails freshness and source of truth: out. B (we pull): a full sweep is ~5,100 requests and Atlantica allows 10/s, so 8.5 min: fails freshness. C (chains push, queue, batch apply): fits, if the database absorbs bursts.
Why: Removing options with a driver, not with taste, is what makes the choice defensible.
4Spike the deciding unknown
Two days, branch spike/ari-batch, staging copy only. Batches of 500 rows: ~4,000 rows/s, 613,000 updates in ~2.5 min; search p95 120 → 135 ms. Branch deleted.
Why: An hour of opinion became a number. The code was written to answer a question, not to ship.
5Write and sign the ADR
ADR-047: option C inside today's platform. Accepted trade-off: a public API contract to version and support for years. Revisit if a chain can't push, or bursts exceed ~1.5M updates. Reviewed by Karim and Maya.
Why: The decision is a one-way door; the reasons must outlive this month and this team.

Option	Freshness (5 min)	Bursts (613k)	Team / ops	Verdict
A. Bulk CSV upload	Fails (manual, hours)	n/a	Easy	Out
B. We pull from CRS	Fails (8.5 min sweep)	Limited by their 10 req/s	A connector per CRS vendor	Out for now
C. Chains push, queue, batch	~2.5 min (spike)	Absorbed by queue	Existing queue + DB	Chosen

Visual diagram

Chain's reservation system

ARI push API

Update queue

Batch applier

Rates database

Guest search

Claude Code (spike)

Click a component

The option chosen for StayHub for Chains: a push API that accepts updates fast and applies them in batches. Follow the walkthrough.

Analogy

Building a houseStarting a big project

Building a house"A family house"Starting a big project"Win hotel chains"
Building a houseFamily size, budget, rulesStarting a big projectGoal numbers and limits
Building a houseTwo or three sketchesStarting a big projectTwo or three options
Building a houseSoil test before choosingStarting a big projectSpike before deciding
Building a houseSigned plans for the builderStarting a big projectADR for the team

Where it breaks: a house plan rarely changes once built. Software can, so the ADR also says what would make you change your mind.

Why it matters

Early project decisions are the expensive ones.

They're hard to undo. How chains send prices becomes a contract with 420 hotels' systems. Changing it later means they all change too.

Everything is built on top. Months of work by people and agents sit on this choice. A wrong start multiplies.

Agents make plausible designs cheap. A beautiful 14-page architecture takes minutes. Only written goals and limits tell you if it fits your problem.

Check your understanding

Q1/3Reasoning

Which of these are decision drivers for the chains project? (Select all that apply.)

Select all that apply.

How confident are you?

Practice ladder

Step 1 · Trace

Check the 14 pages against the drivers

Debugging Warm-up

Here's the summary of Claude Code's day-one architecture for chains:

Chains upload a CSV of rates every night; a job imports it.
A new Kafka cluster carries all rate changes.
A new document database stores chain rates; a sync job copies them into the existing rates database every 10 minutes.
A GraphQL gateway in front of everything.

The drivers: 5-minute freshness (p95); the chain's CRS is the source of truth; ~613,000-update bursts; 8 engineers; nothing the on-call team can't run; search p95 may not degrade more than 20%.

Trace each point against the drivers: which driver does it break or ignore, and why?

Step 2 · Complete

Complete ADR-047

Design Practice

Fill the blanks in Lina's ADR.

Context: goal ___ hotels in ___ weeks; freshness ___ (p95); bursts of ~___ updates (420 × 365 × ___); rates API safe at ~___ writes/s.
Options: A ___; B ___ (fails because ___); C ___.
Evidence: spike, ___ days, batches of ___ rows: ~___ rows/s, burst applied in ~___ min, search p95 ___ → ___ ms.
Decision: ___.
Consequences / accepted trade-off: ___.
Revisit if: ___.

Step 3 · Solve

Frame the invoicing decision

Design Stretch

Next decision for StayHub for Chains: Atlantica wants one monthly invoice for all 420 hotels (commission owed to StayHub), in their accounting format, instead of 420 separate invoices. Today StayHub's invoicing code generates one PDF per hotel per month. Atlantica's finance team imports invoices into their ERP (enterprise resource planning) system, which accepts a standard e-invoice file.

Without help: write the goal as numbers, four drivers, two or three options, and the one spike question you'd give Claude Code (with its time box and the line that stops it recommending).

Step 4 · Decide

The spike says no

Decision Stretch

Alternative ending. The spike reports: best batch size 500, ~1,500 rows/s: a chain-wide burst takes ~6.8 minutes. Single-hotel changes (a few thousand updates) still apply in seconds. Atlantica's revenue team says chain-wide price changes happen about twice a month; single-hotel changes happen hundreds of times a day.

Options: (1) keep option C and agree a different target with Maya and Atlantica: single-hotel changes within 5 min, chain-wide changes within 10 min; (2) keep C and partition the rates table to reach 5 min for everything (+4 weeks, touches the guest search path); (3) switch to B (pull).

Write your decision: "We chose X over Y because…, accepting the risk of…".

Explain it yourself

Explain to Maya why you didn't just accept the architecture Claude Code proposed in twenty minutes on day one.

0 words