meetup · AI-native delivery

Spec-Driven Development
in the AI era

From markdown prompts to executable specifications:
how ATDD keeps coding agents honest, from requirement to production.

ATDDGherkin + CucumberClaude Code agentsGitHub Actions → Azure
S c a l e r
the problem

AI made code cheap. Verification is the new bottleneck.

A coding agent writes a feature in minutes. But who decides what "correct" means, and who proves the agent delivered it?

01 / ambiguity

Prose is open to interpretation

"Loyalty members get 15% on large orders." Is 1000.00 large? Does it stack with 10%? The agent picks an answer silently.

02 / self-grading

The agent marks its own homework

The same model writes the code and the tests. If it misunderstood the rule, its tests share the misunderstanding.

03 / gaming

Green at any cost

Under pressure to pass, agents edit assertions, skip tests or hardcode the example values. The build is green, the feature is not.

04 / drift

Docs and code drift apart

Requirements in Jira or markdown are not checked against the running system. After three sprints nobody trusts them.

05 / review overload

Humans drown in diffs

Reviewing 2,000 generated lines line by line doesn't scale. Reviewers need evidence, not more code to read.

06 / "done"

"Works on my machine"

Passing locally says nothing about staging or production. "Done" has to be proven in every environment.

how the SDLC changed

Traditional SDLC vs spec-driven delivery

click a stage for details
spec-driven development

The spec is the source of truth. Code is a derived artifact.

When an agent writes the code, the scarce human work moves upstream to deciding behaviour and downstream to proving it.

A spec-driven workflow writes the intent down first, in a structured form, before any code. The agent plans and implements against it, and the spec outlives each change.

intent before codereviewable artifactversioned with the codeagent-readable

Spec-first

Write a spec, let the agent build from it. The spec is often discarded after the task.

Spec-anchored

The spec is kept and evolved with the feature, and each change starts from a spec change.

Spec-as-gate (this talk)

The spec is executable. It fails until the behaviour exists, it gates every PR and it runs against production.

the same requirement, three ways
prose · Jira ticket

"Loyalty members get a bigger discount on large orders."

? how large · stacking · rounding
markdown spec · EARS style

WHEN a loyalty member places an order above 1000.00 EUR, THE SYSTEM SHALL apply a 15% discount.

? is 1000.00 included · half-up or down
executable spec · Gherkin

| loyalty | 1000.00 | 900.00 | | loyalty | 1000.01 | 850.01 | | loyalty | 1234.56 | 1049.38 |

✓ runs · ✗ fails until built
markdown specs vs executable specs

GitHub Spec Kit, Kiro… and ATDD: what's different?

Markdown-driven SDD
GitHub Spec Kit · Kiro specs
Executable specs (ATDD)
this repo
artifactspec.md → plan.md → tasks.md (Kiro: requirements.md in EARS, design.md, tasks.md) .feature rules + example tables, plus an OpenAPI contract and SLO thresholds
who reads itThe agent, as context and instructionsThe agent and the test runner. Every example is run.
"done" meansTasks are ticked off. Tests are usually written by the same agent.The scenarios turn from red → green. They were written and reviewed before the code.
can the agent change it?Yes. It's a file in its context.No. The hook and the CI path guard make the spec read-only for the implementer.
after mergeCan drift from the code unless someone keeps it updatedLiving documentation. The same spec runs on preview, staging and @smoke in production.
strengthGreat for planning, decomposition and design discussionGreat for verifiable behaviour: boundaries, rounding, error cases
not either/orMarkdown specs tell the agent what to do. Executable specs tell you whether it did it.
acceptance test-driven development

ATDD: agree on examples first, then build until they pass

ATDD
click the steps
the layers of an executable spec

Four layers: business language at the top, I/O at the bottom

how the project is structured

Every folder has an owner, and agents have lanes

ATDD_ROLE =
who is involved

Humans decide, agents do the work, evidence proves it

👤 Humans

Product owner
Writes the requirement issue, answers open questions, approves the rules and examples in the spec PR.
owns: specs/features
Architect
Owns the API contract and the quality thresholds (p95 latency, error rate).
owns: openapi.yaml · slo.json
QA / test engineer
Owns the step → DSL → driver layers and the governance rules that keep the spec honest.
owns: acceptance/java
Developer
Reviews design and readability (behaviour is already proven), then merges the implementation PR.
owns: src/main · src/test
Platform team
Owns the pipeline, hooks, agent definitions and CLAUDE.md, i.e. the rules of the game.
owns: .github · .claude · ci
Release approver
Approves the production deployment once staging, the spec and the k6 SLO check are green.
gate: production environment

🤖 Claude agents (.claude/agents)

spec-author
Turns the issue into Gherkin rules + examples through example mapping. Asks questions instead of guessing (needs-clarification).
acceptance-engineer
Adds step glue, DSL verbs and driver methods, then proves the new scenarios are red for the right reason.
implementer
Writes production code and unit/property tests until the spec is green. It cannot touch the spec.
spec-conformance-reviewer
Independent, read-only. Did the code implement the rule, or just the example numbers?
Humans decide·agents do the work·evidence proves it: red check, green spec, mutation score, @smoke in prod
requirement → production · REQ-ORD-016 tiered loyalty discount

One requirement, end to end

Product owner
Claude agents
CI pipeline
Developer
Release · prod

    
two kinds of pull request, never mixed

First prove it's red, then prove it's green

① Spec PR · ATDD_ROLE=spec

specs/ · acceptance/ · delivery/ (+ REQ id added to pending list)
  • Path guard: only spec paths changed, kind=spec
  • Contract lint: openapi.yaml is valid
  • New scenarios are red, failing on a Then assertion. No undefined steps, no crashes.
  • Everything else still green. The pending REQ is excluded, so main stays green.
  • PO approves the Rule lines and boundary rows

② Implementation PR · ATDD_ROLE=implement

src/main · src/test (+ REQ id removed from pending list)
  • Path guard: only src/ changed, the pending ID removed (never added)
  • Unit + jqwik property + ArchUnit tests pass; the domain stays framework-free
  • The whole spec is green, plus holdout scenarios the agent never saw
  • Mutation testing (PIT) ≥ 80%: planted bugs get caught
  • Preview deploy: the same spec runs over the network, plus contract fuzzing (Schemathesis)
$ ONLY='@REQ-ORD-016' scripts/acceptance.sh && python3 ci/red_check.py target/cucumber/report.json
Checked 6 scenario(s): 4 good red, 2 already passing, 0 problem(s).
  ✓ red   … payable amount of the order expected 850.01 but was 900.01
  • green … 1000.00 → 900.00  (already satisfied; confirm it pins an intended boundary)
✓ Red for the right reason.
keeping agents honest

Try to cheat the spec. Something will catch you.

← pick something an over-eager agent might try
lessons from real runs

Things that actually happened

agent "succeeds" in ~20 s, no PR

Silent permission denials

In CI, tool calls the agent isn't allowed to make are denied quietly. Check permission_denials_count.

→ keep --allowedTools complete
changed agents.yml, same behaviour

"Re-run" replays old config

Re-running a workflow uses the original commit's YAML. Your fix isn't in that run.

→ start a fresh run (re-add the label)
reviewer: "non-human actor"

Bots reviewing bots

The conformance reviewer refused PRs opened by the Claude bot. Agent-to-agent hand-offs need explicit trust.

→ allowed_bots: 'claude'
k6: many 404s, normal latency

"Healthy" was the old revision

The deploy reported healthy while the old revision still answered. In-memory state was lost on the traffic switch.

→ wait until /actuator/info reports the new SHA
property test failed after a rule change

Tests pin old rules (good!)

discountNeverExceedsTenPercent encoded the old 10% rule. When the rule changes, the tests pinning it must change too.

→ a feature, not a bug
hardcode-shaped risk

Example ≠ rule

Agents love example values. Holdout scenarios with values the agent never sees, plus an independent reviewer, catch "if total == 1000.01".

→ implement the Rule: line, not the table
takeaways

Let agents write the code.
Keep humans in charge of "correct".

Specs as examples, not prose. Boundaries and rounding are where AI guesses.
Make the spec executable, red before code and green after.
Separate the roles: who writes the spec is not who satisfies it.
Defence in depth: hook, path guard, holdout, mutation and an independent reviewer.
One spec, every environment: laptop, preview, staging and production.
Markdown SDD and ATDD combine well: plan in prose, gate on examples.
Thank you! Q&A