Breaking down a big project
Thursday, 9:00. ADR-047 is signed. Karim wants a plan by Friday. Claude Code produced 112 tasks in four minutes, neatly ordered: database, API, worker, dashboard, and Atlantica integration in week 12 of 12. It looks complete. Where's the risk?
A decision isn't a plan. Make something thin work end to end first, grow it in slices, start the slow outside things early, and give dates as ranges.
- Problem
ADR-047 is signed: chains push rates to a new API, queued and applied in batches. Twenty Atlantica hotels must be live in 12 weeks, 420 in 20, built by 8 engineers directing Claude Code. Karim wants a plan by Friday.
- Why the simple system fails
Claude Code produces 112 tasks in four minutes, ordered by layer: all tables, then all endpoints, then the worker, then the dashboard, then integration with Atlantica in week 12. Nothing works end to end until the last weeks, so every integration surprise arrives when there's no time left.
- Engineering concept
Plan by outcomes: milestones a customer could verify, a walking skeleton through every layer in week 3, then vertical slices. Map the dependencies (especially external ones) to find the critical path. Cut slices into agent-sized tasks, each with a spec and acceptance criteria. Estimate with ranges, keep a cut list, and re-plan every week.
- Technology
Milestone definitions, a walking skeleton, vertical slices, dependency maps and the critical path, task cards with Given/When/Then criteria, three-point estimates, a weekly re-plan and a written cut list.
- Trade-offs
Slicing vertically delays the "complete" layers and can mean reworking early code; layering looks efficient but hides risk until the end. A single committed date reassures stakeholders but lies about uncertainty; ranges are honest but need explaining.
The problem
2 min- Karim · CTOI need a plan by Friday. 20 hotels in 12 weeks, all 420 in 20. Eight engineers.
- You · Engineer at StayHubClaude Code wrote one: 112 tasks. Tables weeks 1–3, endpoints 4–7, worker 8–9, dashboard 10–11, Atlantica integration week 12.
- Lina · Senior engineer, your mentorWhen does anything first work for Atlantica?
The big idea
4 minPlan around outcomes and risk, not layers: something working end to end in week 3, then slices, with ranges and a cut list.
A restaurant can build the kitchen, then the dining room, then open. Or serve one table three dishes in week 3, end to end, and learn the oven is too small while there's time.
How it works
5 min- 1Milestones as outcomes
Each one a demo anyone can check. M0, week 3: a rate changed in Atlantica's sandbox appears in staging search within 5 minutes. M1, week 12: 20 hotels live. M2, week 20: all 420.
- 2Walking skeleton first
A is the thinnest version that works through every layer: push API → queue → applier → search, one hotel.
- 3Then vertical slices
A cuts through every layer to deliver one usable thing: rates, availability, restrictions, bookings back, hardening.
- 4External waits on day one
The is the longest chain that must happen in sequence. Sandbox credentials take 3 weeks, requested day one; a mock CRS meanwhile. No agent shortens a partner's calendar.
- 5Agent-sized tasks
One spec section with Given/When/Then criteria, one code area, a diff reviewable in ~30 minutes (< ~400 lines), a verify command, an out-of-scope line.
- 6Ranges and a cut list
A gives best, likely and worst: 7 / 10.5 / 16 weeks. Agree the cut list now (restrictions first) and re-plan every Friday.
Watch a decision being made
4 minLina asks; you build a plan Karim can trust
Turn ADR-047 into milestones, slices, dependencies, task cards and an honest estimate by Friday.
- 1Map dependencies, external first
Sandbox access requested day 1; Claude builds a mock CRS from sample payloads. The 420-row mapping file and the booking spec asked in week 1 (Maya chases). Security review slot booked for week 10.
Why: External waits sit on the critical path.
- 2Cut six slices
S1 skeleton, S2 rates, S3 availability, S4 restrictions, S5 bookings back, S6 hardening: each usable and demoable alone.
Why: Slices surface risk early and make cutting scope clean.
- 3Let the agent draft task cards; you check them
Card ARI-07: availability updates,
src/chains/arionly, < ~400 lines, 4 criteria,pnpm test:chains, rates out of scope.Why: Review is the scarcest resource. A task you can't review in 30 minutes is two tasks.
- 4Range, cut list, re-plan rule
Total 7 / 10.5 / 16 weeks against a week-12 pilot. Cuts agreed now: restrictions first, extra currencies second. Every Friday: update the range, pull from the cut list if worst passes week 12, tell Karim and Maya the same day.
Why: Agreeing cuts before a slip turns a crisis into a planned decision.
In real life
3 minGmail: years of beta
- Invite-only launch in 2004
- Grew with real users
- "Beta" label for years
Real use reveals the real risks.
iPhone: revealed complete
- Built in secret
- Shown finished in 2007
- Had to make sense as a whole
Fits when the whole is the product.
What goes wrong
3 minThey stay at 80% for a month.
Outcomes a customer could verify in a demo.
Huge diffs get skimmed.
One spec, one area, a ~30-minute review.
Slips are found late, and the skipped check causes the incident.
Ranges, a Friday re-plan, cuts from the agreed list.
Trade-offs
3 min| Planning style | Fits when | You pay |
|---|---|---|
| Layer by layer | Almost never for partner integrations | Integration risk last; nothing to demo |
| Skeleton + slices | New products, integrations, fixed dates | Early code reworked |
| Single committed date | Small, well-known work | Hidden uncertainty; slips found late |
- Karim · CTORanges sound like excuses. One date for all 420. I'm telling the board.
- Maya · Product managerAnd Atlantica wants the consolidated statement at the pilot, or they may walk.
- Karim · CTOSo the pilot is bigger and you want one date?
Your job as tech lead
4 minClaude 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.
- The milestones as verifiable outcomes, and the order of slices: which risk is faced first.
- Which external dependencies start on day one and who chases each.
- The estimate range, the cut list and its order, agreed with Karim and Maya before anything slips.
Read docs/projects/chains/plan.md and ari-api.md. For slice S3 (availability) only, draft task cards in docs/projects/chains/tasks/S3.md. Each card: one spec section, 3 to 5 Given/When/Then criteria, exactly one code area (src/chains/ari or src/chains/applier), a diff under ~400 lines, a verify command, an out-of-scope line. List dependencies between cards. Don't write code. Flag any criterion you guessed.
- Every card has criteria, one area, a verify command and an out-of-scope line.
- The cards add up to the slice's outcome and nothing more.
- You decided every guessed criterion instead of letting it stand.
- A plan ordered by layer, with partner integration at the end.
- Tasks like "build the API" with no criteria.
- One precise date for months of work, no range, no cut list.
Check yourself
2 minNext: three squads, about twenty-five Claude Code sessions a day, and Monday's pull requests all reinvent the same helpers. Time to write the codebase's rules.
Mark it complete to update your skill map.
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
From ADR-047 to a plan Karim can trust
Turn the signed architecture into milestones, slices, dependencies, agent-sized tasks and an honest estimate, by Friday.
- 1Write milestones as outcomes
M0 week 3 (one sandbox hotel, a rate visible in search in < 5 min), M1 week 12 (20 hotels live), M2 week 20 (420 hotels + consolidated statement).
Why: Each milestone is a demo anyone can check. "API 80% done" can stay at 80% for a month.
- 2Map dependencies, external first
Sandbox access (3-week lead time) requested day 1; Claude Code builds a mock CRS from Atlantica's sample payloads meanwhile. Mapping file and booking spec asked in week 1. Security review slot booked for week 10.
Why: External waits sit on the critical path, and no agent makes them shorter.
- 3Cut vertical slices
S1 skeleton, S2 rates, S3 availability, S4 restrictions, S5 bookings back, S6 hardening. Each one usable and demoable on its own.
Why: Slices surface risk early and make cutting scope a clean decision instead of a half-finished layer.
- 4Split slices into agent-sized tasks
Claude Code drafts the task list per slice; you check each card has criteria, one area, a size of < ~400 lines and a verify command. ARI-07 is the template.
Why: Review is the scarcest resource. A task you can't review in 30 minutes is two tasks.
- 5Estimate with ranges and a cut list
Per slice best / likely / worst; total 7 / 10.5 / 16 weeks against a week-12 pilot. Cut list agreed with Karim and Maya now: restrictions first, extra currencies second.
Why: Likely isn't safe. Agreeing the cuts before anything slips turns a crisis into a planned decision.
- 6Set the re-plan rule
Every Friday: compare done slices with the plan, update the range, pull from the cut list if the worst case passes week 12, tell Karim and Maya the same day.
Why: A plan updated weekly survives contact; one defended until week 11 doesn't.
| Agent-sized when… | ARI-07 has it? |
|---|---|
| One spec section, Given/When/Then criteria | Yes: 4 criteria |
| One area of the code | Yes: src/chains/ari only |
| Diff reviewable in ~30 minutes | Yes: < ~400 lines |
| A command that proves it | Yes: pnpm test:chains + contract test |
| Says what's out of scope | Yes: rates, src/rates |
Analogy
- Opening a restaurantSoft opening, one tablePlanning a big projectWalking skeleton
- Opening a restaurantAdd one dish at a timePlanning a big projectAdd one slice at a time
- Opening a restaurantOven takes six weeksPlanning a big projectPartner access takes three
- Opening a restaurantClear recipe per dishPlanning a big projectSpec per agent task
- Opening a restaurantDrop a dish if latePlanning a big projectCut list, agreed early
Where it breaks: a restaurant's soft opening serves real guests. A walking skeleton usually runs only in a test setup, so you still need a pilot with real hotels.
Why it matters
Surprises come from connecting things. If you connect to the partner's system in week 11 of 12, any surprise becomes a missed date.
Outside teams don't go faster because agents do. Atlantica takes three weeks to give test access. Ask on day one.
Big tasks can't be reviewed. A 3,000-line change gets skimmed, and bugs slip through. Small tasks keep every change checkable.
One date hides doubt. A range, updated weekly, lets Karim and Maya act early instead of hearing bad news at the end.
Check your understanding
Select all that apply.
Practice ladder
Find the critical path
Estimation Warm-upTrace the plan to the pilot. Weeks are counted from the start of the project.
- Sandbox access arrives at the end of week 3.
- S1 skeleton: 2 weeks of work against a mock, then 0.5 week to verify against the sandbox (can't verify before access arrives).
- S2 rates and S3 availability: 1.5 weeks each, both after S1, done by different squads in parallel.
- S5 bookings back: 3 weeks, after S1 and after Atlantica's booking-notification spec arrives (end of week 5).
- S6 hardening: 1.5 weeks, after S2, S3 and S5.
(1) When is each slice done? (2) Which chain sets the date? (3) What happens if the booking spec arrives at the end of week 7 instead?
Complete the task card
Design PracticeComplete this card so it is agent-sized.
## ARI-12: Apply rate updates in batches Slice: ___ · Area: ___ (only) · Size: ___ Spec: docs/projects/chains/ari-api.md#rates Acceptance criteria: - Given 1,200 queued rate updates for 3 hotels, when the applier runs, then ___ - Given two updates for the same hotel, room and date, then ___ - Given a burst of 613,000 updates on the staging copy, then ___ and search p95 ___ - Given an update for a hotel not mapped to StayHub, then ___ Verify: ___ Out of scope: ___
Break down the consolidated statement
Design StretchM2 includes the consolidated monthly statement: one document per month listing commission owed by each of Atlantica's 420 hotels, grouped by legal entity and country, importable into Atlantica's accounting system.
Without help, write: (1) the milestone as an outcome, (2) a walking skeleton and 3 vertical slices, (3) the external dependencies and when you'd request them, (4) one agent-sized task card, (5) a three-point estimate.
Friday of week 7
Decision StretchWeek 7 re-plan. S1, S2, S3 are done. S5 (bookings back) hit a surprise: Atlantica's system rejects bookings without a guest loyalty id field their docs never mentioned. Remaining work, in weeks (best / likely / worst): S4 restrictions 1 / 1 / 2, S5 2 / 3 / 5, S6 1 / 1.5 / 2.
Likely finish: week 12.5. Worst: week 16. Options: (1) cut S4 restrictions (Atlantica manages 20 hotels' minimum stays by hand for the first month), keep week 12; (2) borrow 2 engineers from the Search team for 4 weeks; (3) move the pilot to week 14.
Write your decision: "We chose X over Y because…, accepting the risk of…", including who you tell and when.
Explain it yourself
Explain to Karim why you rejected Claude Code's 112-task plan even though every task in it was needed.