Skip to content
Winter Sale from $619, until 31st December 2026 Book now
Agentic coding workshops iOS + Android

Spec-Driven Development Workshop: Writing Specs That Coding Agents Can Execute

Spec-driven development means writing down what to build – requirements, design and a task list – before an agent writes code, and keeping that spec as the reference while it works. A workshop on it teaches a team to write specs that are short enough to maintain, precise enough to test and split into tasks an agent can finish and a human can review.

6 min read

Key takeaways

  • Agents fill every gap in a prompt with a guess; a spec closes the gaps that matter before code exists.
  • A useful spec has three layers – requirements with testable acceptance criteria, a short design and a list of small tasks.
  • Kiro and GitHub Spec Kit structure the process, but plain Markdown files and a planning mode work too; the habit matters more than the tool.
  • For mobile apps, store requirements such as account deletion, login options and in-app purchases belong in the spec, not in a fix after rejection.

Why agents need specs more than people do

A developer who gets a vague ticket asks questions, looks at similar features and remembers what the product owner said last week. A coding agent does some of that – it reads code – but where information is missing, it picks the most plausible option and keeps going. The result looks finished and is often subtly wrong: the wrong edge case handled, a field validated differently than elsewhere, an empty state nobody asked for.

Specs move those decisions to the start, where they are cheap. They also make review faster: the reviewer checks the code against the spec instead of reconstructing the intent from the diff. And they survive the session – the next agent run, or the next developer, starts from the same document.

The three layers of a useful spec

1. Requirements

User-facing behaviour with acceptance criteria that can be tested. A structured sentence pattern helps. Kiro, for example, uses the EARS notation, which reads like this:

WHEN the user confirms "Delete account" in the settings screen
THE SYSTEM SHALL delete the account and its personal data on the server
AND sign the user out on all devices.

IF the deletion request fails
THE SYSTEM SHALL show an error and keep the user signed in.

Each criterion becomes a test, either automated or in the release checklist.

2. Design

A page, not a book: which components change, the data model, API contracts, error handling, and the decisions an agent must not make on its own – which library, which pattern, which existing module to extend.

3. Tasks

Small, ordered steps, each ending in a state that builds and passes tests. A good task fits in one agent session and one reviewable pull request. "Add the deletion endpoint with tests" is a task; "implement account deletion" is not.

Talk to an AI Code Engineer about your agentic coding workshop.

In a free call we look at your team, your codebase and your goals and suggest a workshop format that fits – remote or on-site, in English or German.

Tools: Kiro, Spec Kit or plain Markdown

OptionHow it worksFits teams that…
KiroAWS's agentic IDE generates requirements, design and task files per feature and works through the taskswant the process built into the editor
GitHub Spec KitOpen-source toolkit with templates and agent commands for specifying, planning and breaking down work; supports several coding agentswant a structured process with the agent they already use
Plain MarkdownSpec files in the repository, a planning mode in Claude Code, Codex or Cursor, and a rule in the context file to follow themwant minimal tooling and full control

The workshop uses whichever your team prefers. The skills transfer: a well-written requirement is the same in all three. Teams that build apps with Kiro will find the store side in Kiro app to the App Store and Kiro app to Google Play.

Workshop agenda

  1. The A/B exercise. Two groups build the same small feature – one from a one-line prompt, one from a short spec. Comparing the results opens the day better than any argument.
  2. Writing requirements. Turning a real backlog item into testable acceptance criteria, including the unhappy paths agents tend to skip.
  3. Design notes. What to decide up front, what to leave open, and how to point the agent at existing patterns in the codebase.
  4. Task breakdown. Splitting work into steps that end green, and letting the agent propose a breakdown that the team then corrects.
  5. Execution. Running the tasks with an agent, checking each against the spec, updating the spec when reality differs.
  6. Keeping specs alive. Where spec files live, when they are updated, when they are archived.

Product managers benefit as much as developers; the article on agentic coding for product managers looks at their side of the process.

Specs for mobile apps: put the store rules in

Many App Store and Google Play rejections of agent-built apps trace back to requirements nobody wrote down. They are easy to add as non-functional requirements in every relevant spec:

  • accounts that users can create can also be deleted inside the app – and, on Google Play, through a web link,
  • third-party login comes with an equivalent privacy-friendly option such as Sign in with Apple on iOS,
  • digital goods and subscriptions use In-App Purchase on iOS and Google Play Billing on Android,
  • every new SDK or permission comes with an update of the privacy manifest, the App Privacy answers and the Data safety form,
  • Android builds target the API level Google Play currently requires.

With these in the spec, the agent builds them in from the start and the reviewer can check them like any other criterion. Our guide from AI prototype to production app lists further hardening steps that belong in specs.

Where spec-driven development goes wrong

  • Specs nobody reads. An agent can generate a long spec in seconds. If no human reviews it critically, it only adds false confidence.
  • Specs that rot. A spec that no longer matches the code misleads the next agent session. Update or archive it with the change.
  • Waterfall by accident. Specs for a whole quarter up front defeat the purpose. Write them per feature, just before the work starts.
  • Over-specified design. Prescribing every function name leaves the agent no room and the spec no chance of staying current. Specify decisions, not keystrokes.

We run this workshop remotely or on-site, in English or German, on a real feature from your backlog. It combines well with an internal hackathon, where every team starts from a spec. Book a free call to pick the feature together.

Frequently asked questions

Isn't spec-driven development just waterfall again?

Not when specs are written per feature, kept short and updated as the code changes. The aim is to make the decisions an agent would otherwise guess, a few hours or days before the work – not to plan months ahead.

Do we need Kiro or Spec Kit for spec-driven development?

No. They give the process structure, but spec files in Markdown, a planning mode in your coding agent and a rule in the context file to follow the spec work as well. The workshop teaches the writing; the tool is a choice.

How long should a spec be?

As short as possible while still answering the questions an agent would otherwise guess. For a typical feature, a page of requirements and a page of design notes plus a task list is plenty.

Who writes the spec – product or engineering?

Both. Product owns the requirements and acceptance criteria, engineering owns the design and task breakdown, and an agent can draft each part for the humans to correct.

Free, 15 minutes, no obligation

Plan your agentic coding workshop with us.

Our AI Code Engineers run hands-on workshops on Claude Code, OpenAI Codex, Cursor and AI app builders – and ship apps to the App Store and Google Play every week. Tell us about your team.

AI tools, store policies and requirements change quickly – always check the current documentation of the tools and stores you use. This article is independent advice and not affiliated with or endorsed by Apple, Google, Anthropic, OpenAI or any other company or product mentioned; all trademarks belong to their owners.

Workshop for your team?

Talk to an AI Code Engineer – free, 15 minutes, in English or German.

Book a call for free

Chat and hotline are open 24/7. Answers from our senior AI Code Engineers (real humans) usually take closer to 72 hours than 1 hour.