Write the spec the model can hit
Lesson 2 of 5 — vague in, vague out. Specificity is the whole skill.
How to convert a design into a spec a model hits on the first try, and why naming the acceptance check up front changes what you get back.
Prerequisites
Lesson 1 — you have an architecture sketch to specify.
Step 116 min
Turn the design into a spec
GoalA prompt that names every constraint a senior would — so the output is reviewable, not magic.
The model is not a mind-reader; it is a constraint-satisfier. It fills the gaps you leave with the statistically average choice — which is rarely the choice your system needs. A spec is just the act of leaving fewer gaps.
Add autosave to the editor.Implement the "save draft" route from this design:- POST /api/posts/:id/draft, auth required, owner-only (403 otherwise).- Body: { body: string }. Reject > 100KB with 413.- Upsert one row in post_draft keyed by postId; last-write-wins; set savedAt = now.- Return { ok: true, savedAt }. On DB error return 500 { ok:false }, do not leak the error.- No new dependencies. Match the existing route style in /api/posts/:id/route.ts.Write the route, then a test covering: happy path, non-owner, oversize body.Spec-driven prompting
Writing the contract — inputs, outputs, edge cases, constraints — so the model has a target precise enough to hit.
Want the full picture? Open the reference →
- Pin the interface — exact route, signature, types. No paraphrasing.
- Name the edges — the 413, the 403, the empty input. Models skip these unless told.
- Constrain the blast radius — "no new dependencies", "match existing style", "touch only these files".
- Demand the test — it both improves and verifies the output.
Quiz
Why ask the model for the test cases up front instead of after?
Rewrite your lesson-1 feature as a senior prompt: pin the interface, name three edge cases, constrain the blast radius, and demand a test.
Concepts covered · 2
More like this
Review what comes back like a senior
Models produce confident, plausible, well-formatted code — which is exactly what makes their mistakes dangerous. This lesson is the review rubric: the specific failure classes to hunt for, because "it looks right" is not review.
Orchestrate agents without the codebase rotting
Putting it together: context, guardrails, and a verification loop that lets you run coding agents across a real codebase without it drifting into an incoherent pile. This is the senior loop at full speed.
Structure & style the app
Lay down the HTML skeleton and a calm dark style for a todo app. No JavaScript yet — just the shape, so the behaviour you add next has somewhere to live.
Liked this one?
Pass it on
Discussion
Be the first to ask
Your questions stay private with the team. We can pin answers to share with everyone.
Sign in to ask a question privately on this tutorial.
Sign inNo pinned answers yet for this tutorial.