# 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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/agentic-tool-catalogue/#spec-driven-workflow).
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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/agent-loops/),
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.[^ghostwriting]

[Plan mode](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/claude-code-cheatsheet/#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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/claude-code-cheatsheet/#the-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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/claude-code-cheatsheet/#claudemd) 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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/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.

[^ghostwriting]:
    The model can interpret the brief and spec, make the plan, build against it,
    and then assess its own result. That repeats one opinion across the process.
    Read the plan, inspect the work and check the claims yourself.

Source: <https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/spec-driven-development/>\
Licence: [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\
Cite as: Swift, B. (2026). _COMP4020/COMP8020 Agentic Coding Studio_ [Course materials]. ANU School of Computing. https://doi.org/10.5281/zenodo.21395760