Spec-driven development

Read the problem and context in the brief, treat the spec as fixed, plan a response with the agent, then turn checkable clauses into tests

“Spec” is the industry’s word, used by spec-kit and its cousins. In this course it means a short fixed contract, rather than a comprehensive requirements document signed off before implementation.

Every course deliverable has a brief and a spec. The problem and context are in the brief, with room for your point of view. The fixed requirements are in the list headed “The spec” on the course page. Some lines can be checked by a script and some need a person. Interrogate both documents with the agent, decide on your response, record it in a plan and turn the mechanically checkable parts into tests before implementation.

Revise your plan when the running prototype disproves an assumption. The published spec remains fixed; do not weaken it through changes to the plan or tests.

Other teams and tools draw these boundaries differently. In this course, the course provides the brief and spec; you write the plan, tasks and implementation.

Why write anything down#

The alternative is prompt-and-hope. Type “build me an interactive explainer of tides” and the agent will build one. Every gap you left gets filled by the model’s priors rather than yours: what interactive means here, who’s reading it, whether it has to work on a phone. Those priors are the median of everything it read, which is why the result so often looks like a competent version of something you didn’t ask for.

The second cost is worse, and harder to see. The loop stops when the model decides the job is done, and that’s a claim, not a fact. If “done” was never written down, there’s only your own reading of the page to check the claim. That review often happens once the page renders and looks plausible. With a written spec, a test or your tutor can decide whether the work is finished against stated criteria.

Interrogate it with the agent#

People often respond to the word “spec” with a blank document and formal prose. A more useful first step is to give the brief and spec to the agent and ask it to argue with you. What’s ambiguous here, what did you assume, and what are three different readings of this line? Review the answers and settle those decisions before implementation, rather than halfway through it.¹

Plan mode is the informal end of the same habit, with the agent reading and proposing and making no edits until you accept. Use it for anything you’d struggle to review at a glance. Either way the principle holds: arguing about the plan is cheap, and arguing about the code is not.

For a larger brief, ask the agent to interview you before it plans. Answering questions about the audience, interaction, edge cases and exclusions identifies decisions before implementation. Read and edit the plan yourself, then begin in a clean session with the brief, spec and agreed plan as sources.

Explore, plan, implement, verify#

The brief, spec and plan sit inside the course’s standing working loop:

1. explore the existing artefact and repository
2. plan the bounded change and its evidence
3. implement against that plan
4. verify the diff, checks and running artefact

The phases need not occupy separate sessions or documents. Their purpose is to stop implementation beginning before the problem and the evidence are clear.

Instructions at four lifetimes#

Store instructions in four places according to who controls them and how long they apply:

• the brief and spec — the course’s instructions for this deliverable, fixed on the course site. The brief says what problem you are answering; the spec says what every answer must satisfy.
• CLAUDE.md — standing rules, read every turn and retained for the life of the repo. What’s true of this codebase whatever you’re doing today: how to run it, what not to touch, the conventions you want followed without asking. The cheatsheet has the mechanics.
• prompts and plans — your decisions for this session, usually relevant for an afternoon. A plan records your chosen response, implementation approach and evidence before the implementation begins.
• the task list — the current work, updated as tasks change. See task tracking for the available formats and tools.

Choose among these four locations together. Do not put today’s job in CLAUDE.md, where the agent will still read it three weeks later, or retype a standing convention in every session. Move repeated instructions towards longer-lived context, and move obsolete instructions towards shorter-lived context or remove them.

Make it checkable#

One line separates a spec from a wish: could someone who wasn’t there tell whether it’s been met?

“Make it look good” fails that test. “Every page has exactly one top-level heading” passes it, and so does “the visitor does something that changes what they see”. Every crit page has used this mix since week 1. Some lines a script can settle and some only a person can. The start skill pulls the week’s spec from the course API and helps you turn the mechanical ones into tests in spec/.

A spec made entirely of machine-checkable lines omits criteria such as “one strong idea with a point of view”. Automate the checks you can, leaving your attention and your tutor’s for the rest. Week 3 continues this practice in backpressure.

How much planning is enough#

Not every job needs a written plan. For a one-line fix, anything you can review in ten seconds or anything you would readily discard and redo, just ask. Write a plan when the work is large enough that a plausible result may pass a quick review. That describes most semester projects and few tasks from a session’s first ten minutes.

Overplanning creates the opposite problem. A plan detailed enough to remove all judgement from implementation shifts the job into prose, where feedback is weaker. Every line in the plan also consumes context on each turn.

The plan should change during the build. If the rendered result contradicts an assumption, revise the plan or implementation. Correct a test that misread the published spec; never weaken one merely to make the build pass. If the course spec itself looks wrong or contradictory, ask the teaching team rather than silently rewriting the contract.