Write specs that developers and AI agents understand
Write a spec a developer and a coding agent can execute without guessing, then check that what ships matches the intent.
Write a spec that a developer and an AI coding agent can execute without guessing, then check that what ships matches the intent. You learn to choose the right level of spec, to separate intent from solution, to write verifiable Given/When/Then criteria, to cover edge cases and non-functional requirements, to prepare an agent's context, to review its plan and to keep the spec alive. You leave with the spec of a feature from your own product and its versioned intent file.
What you will be able to do
- Choose the level of spec suited to the decision at hand (PRD, feature spec, ticket) and know what each must contain.
- State the intent of a feature (problem, target outcome, constraints, non-goals) separately from the solution, to leave the right room to the team and the agent.
- Write verifiable, declarative and unambiguous Given/When/Then acceptance criteria, including as tables of examples.
- Identify edge cases and non-functional requirements (performance, security, accessibility, personal data) and make them testable.
- Write a spec and an intent file that a coding agent can use (context, constraints, files involved, out of scope, verifiable definition of done).
- Review a coding agent's plan against the spec, spot gaps before it writes code, then check the evidence of what was delivered.
- Keep a spec alive (versions, decisions, updates when the code reveals a case) and spot the anti-patterns that make it useless.
Prerequisites
- Have already written a spec, a PRD, a user story or a ticket, even imperfect ones
- Work with a development team, or use a coding agent yourself (Claude Code, Codex, Cursor…), or be preparing to
- Recommended course beforehand, not required: “Design and Validate a Product Experience with AI” (its lesson “Hand off to the development team” gives the one-page spec that this course takes further).
- This course does not teach you to configure a coding agent: it teaches you to write what the agent and the team will read.
Syllabus
What will I write in this course, and in what order?
- Course introduction3 steps
Objective · By the end of this introduction, you will know what you are going to produce (the spec of a feature from your product and its intent file) and in what order the four modules get you there.
What is a spec for, at what level should you write it, and how do you say what you want without dictating how to do it?
Objective · By the end of this lesson, you will be able to say what a spec must enable (understand, decide, verify) and choose the right level (PRD, feature spec, ticket) according to the decision at hand and the reader, human or agent.
- Intent before solution7 steps
Objective · By the end of this lesson, you will be able to rewrite a request phrased as a solution into a complete intent (problem, target outcome, constraints, non-goals), and decide which parts of the solution to fix and which to leave open.
How do you write criteria you can verify, and not forget what happens when things do not go as planned?
Objective · By the end of this lesson, you will be able to write verifiable, declarative Given/When/Then scenarios (minimal context, a single event, observable outcomes), name them by what sets them apart and group variants into a table of examples.
Objective · By the end of this lesson, you will be able to find a feature's edge cases methodically with a grid of questions, and write its non-functional requirements (performance, reliability, security, accessibility, personal data) in a quantified, testable form.
What do you need to write so an AI coding agent builds the right thing, and how do you check before and after?
- What a coding agent needs7 steps
Objective · By the end of this lesson, you will be able to turn a spec into a self-contained brief for a coding agent: context, files and interfaces involved, constraints, out of scope and a definition of done with a verification step it can run.
Objective · By the end of this lesson, you will be able to write a feature's versioned intent file and split information between that file, the spec and the repository instructions file (CLAUDE.md or AGENTS.md).
Objective · By the end of this lesson, you will be able to review the plan a coding agent proposes before writing code, spot the gaps with the spec (missing criterion, out-of-scope change, unstated assumption) and then check the evidence of what was delivered.
How do you keep the spec accurate during and after the build, and deliver your own?
Objective · By the end of this lesson, you will be able to keep a spec up to date during and after the build (versions, decision log, updates when the code reveals a case), spot drift between spec and product, and recognise the anti-patterns that make a spec useless.
Objective · By the end of this workshop, you will have produced the spec of a feature from your product (intent, Given/When/Then criteria, edge cases, non-functional requirements, definition of done) and its versioned intent file, with the kit and the plan to use them with your team and your coding agents.