Session 03

Writing a·good spec

Program
Agentic engineering
With
Arndt Voges
From
Arndt Voges Consulting
Where
Remote

The task you hand the agent, then a live interview

Writing a good specLive interviewClose

5 min welcome, 70 min writing a good spec, with a live interview, the rest together

0:00
Welcome·a reminder that I am available for questions
0:05
Writing a good spec·what a spec is, and what comes before it
0:45
Break
0:50
One game, two specs·with a live interview
1:20
Homework, close
1:30
End

I am available for feedback and meetings.
Between sessions too. Just ask.

How to reach me

  1. Emailarndt@arndtvoges.com
  2. Book a callmeet.arndtvoges.com/arndt
  3. Webarndtvoges.com

Questions, feedback, a call with your team: any time, between sessions too.

Where we are

  1. 01Core concepts
  2. 02Preparing the codebase for agents
  3. 03TodayWriting a good spec
  4. 04Feedback loops
  5. 05Workflow integration and code review
  6. 06Claude Code in depth
  7. 07Orchestration and subagents
  8. 08Claude Code alternatives
Last session: the codebase. Today: the task you hand it.

Your CLAUDE.md says how you work.
The spec says what to build this time.

At the end of this session, you will go from engineer to conductor.

Your job is to delegate code generation and spend more time thinking. You will spend a lot more time putting your requirements into words than you have before.

What we cover today

Acceptance criteriaNon-goalsInterview
SpikeSpecspecs/
DiscoveryConstraintsRefinement
Definition of doneWhere do product owners fit in?

Part one

What aspec is

The task, the limits, and how to tell it is done.

A ticket is written for people who share your context.
The agent does not.

Until now

Ticket
You code

From now on

Ticket
Spec
Agentic execution

Spec: three parts

The task

What, and why

The change, the reason, where it lands.

The limits

What stays fixed

Interfaces, data model, what not to touch.

Done means

How to tell it is done

Criteria that something can check. The part most tickets leave out.

Precise where it matters, open where it does not

Fix it in the spec
  • Interfaces and signatures
  • Data model changes
  • Error handling
  • Scope
Leave it to the agent
  • Internal structure
  • Naming of helpers
  • Order of the work
  • Anything you would not review
  • Anything you are excited to be surprised by

Acceptance criteria are statements something can check

Cannot be checked

"The checkout works well on mobile."

Can be checked

"At 375 px width the pay button is visible without scrolling. checkout.mobile.spec passes."

If no test or command can check it, the agent cannot either, and you check it by hand.

Say what not to touch.
Scope drift happens because nothing said stop.

"Not in scope: the voucher logic, the order API, anything under src/legacy/."

Point, do not describe.

Build it like pages/account/orders.vue: same data loading, same error states. Beats a paragraph describing them.

What is new goes into the spec as data, not as a description

Design

URLs of the Figma frames, one per state. The agent reads them through the Figma MCP server. Not a screenshot.

Data structure

The new or extended fields as a type or schema, with one example record. Not a sentence.

Business logic

A table: input, expected result, one row per case. Not a paragraph.

Part two

Beforethe spec

When you do not know enough to write it yet.

From ticket to spec

Ticket written for people Spike or discovery changes nothing Interview it asks, you answer specs/ task · limits · done Fresh session builds from the spec only when you do not know enough yet PRODUCT OWNER business rules in the concept, acceptance criteria in refinement Most of the work happens before the agent writes a line of code.
Spike

A throwaway run that reads the code and reports options.
Its output feeds the spec. It is not code to merge.

prompt
Spike, change nothing:
how could we add a wishlist
to the account area? Read the code,
then list two or three options
with trade-offs and open questions.
A spike run: eight read-only agents survey the code in parallel, then one writes the survey
Discovery

The agent maps where a change will land:
callers, tests, configuration.

prompt
Before we change the checkout total: find every caller of calculateTotal,
the tests that cover it and the configuration it reads. Add the map to the spec.
The map goes into the spec, so the run that builds it does not have to rediscover it.

Three ways to a complete spec

You write it

You think through the corner cases yourself. When you know the domain best and a wrong guess is expensive.

It interviews you

It asks, you answer, it writes the spec. When the knowledge is in your head, not on paper.

It decides

In plan mode it explores, makes every call and writes them into a plan. You review and approve before any code changes. When the risk is low.

You can combine these
Each is a legitimate choice. Each solves a different need.

Let the model interview you

prompt, adapted from Anthropic's best practices
I want to build [short description]. Interview me in detail.

- Ask about technical implementation, UI and UX,
  edge cases, concerns and tradeoffs.
- Ask what must not change, and how we will know it is done.
- Decide the obvious questions yourself.

Keep going until we have covered everything,
then write a complete spec to specs/01_INITIAL_SPEC.md:
the task, the limits, and acceptance criteria as tests.
Then start a fresh session and build from the spec. Answering ten questions is cheaper than reviewing a wrong diff.

Where product owners fit

Concept

Business rules go into the spec before any code exists.

Refinement

They write or check the acceptance criteria.

Review

Against the criteria, not the diff.

Spec size follows risk,
not ticket size.

"Port this entire stack from PHP to Java." One line in the ticket, massive scope. It needs the full spec.

Part three

One game,two specs

One line, then a spec written live.

Spec A

Build a Snake game. Don't ask any questions. Just do it.

Spec A: no questions, every decision its own

Spec A run: 367 lines written to index.html Spec A summary: classic rules, speed ramps, best score saved, 13 checks
Walls that kill, speed that ramps up, a best score saved in the browser. Nobody asked for any of it. (But it's cool!)

Live: the interview, for the same game

prompt
I want to build a Snake game for the browser.
It works great on mobile phones and desktop.
Professional, tasteful animations.
Limits: one HTML file, no dependencies. No sound, no high scores.
Done: game logic separate from drawing, every rule covered by a test.

Interview me in detail. Ask about technical implementation,
UI and UX, edge cases, concerns and tradeoffs.
Decide the obvious questions yourself.
Keep going until we have covered everything,
then write a complete spec to specs/01_INITIAL_SPEC.md:
the task, the limits, and acceptance criteria as tests.
I answer diligently and work through the questions with the agent. It works with my initial specification.

Claude time!

Spec B: six rounds of questions, then a 691-line spec

Spec B interview: it asks which extra effects, after checking back on the brief Spec B: six rounds answered, it writes specs/01_INITIAL_SPEC.md, 691 lines
It checked back before adding more effects: "the brief originally said professional, tasteful."

Demo time.
The big reveal.

What did A decide on its own? What did the interview get into B?

Today, in thirty seconds

What a spec is

  • From engineer to conductor
  • Task, limits, done
  • Done means something can check it
  • Say what not to touch
  • Point, do not describe
  • What is new goes in as data

Before the spec

  • Spike: options, no code
  • Discovery: where it lands
  • Three ways, and combine them
  • Let it interview you
  • Plan mode: approve before code
  • Spec size follows risk

One game, two specs

  • One line: its decisions
  • A few lines and an interview: ours
  • Build from the spec in a fresh session
Example homework, to be tailored to your team

Homework: a team exercise

Ticket

One real ticket, run twice: as written, then from a spec. Refine the spec, not the chat.

With the author

One spec written with whoever wrote the ticket, before any code.

Two skills

Create a /discovery and a /spike skill that customize a shared and agreed-upon approach to your team's codebase(s). Commit them to main, or add them to the plugin.

Share

Be ready to show in 5 minutes: ticket and final spec side by side, what changed between the two runs, and the questions the ticket did not answer.

Done means /discovery and /spike are in main, or in the plugin, and used on two tickets. As a team, before the next session.

Next session:
feedback loops.

Arndt Voges Consulting · arndt@arndtvoges.com · arndtvoges.com

<stop>