From markdown prompts to executable specifications:
how ATDD keeps coding agents honest, from requirement to production.
A coding agent writes a feature in minutes. But who decides what "correct" means, and who proves the agent delivered it?
"Loyalty members get 15% on large orders." Is 1000.00 large? Does it stack with 10%? The agent picks an answer silently.
The same model writes the code and the tests. If it misunderstood the rule, its tests share the misunderstanding.
Under pressure to pass, agents edit assertions, skip tests or hardcode the example values. The build is green, the feature is not.
Requirements in Jira or markdown are not checked against the running system. After three sprints nobody trusts them.
Reviewing 2,000 generated lines line by line doesn't scale. Reviewers need evidence, not more code to read.
Passing locally says nothing about staging or production. "Done" has to be proven in every environment.
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.
Write a spec, let the agent build from it. The spec is often discarded after the task.
The spec is kept and evolved with the feature, and each change starts from a spec change.
The spec is executable. It fails until the behaviour exists, it gates every PR and it runs against production.
"Loyalty members get a bigger discount on large orders."
WHEN a loyalty member places an order above 1000.00 EUR, THE SYSTEM SHALL apply a 15% discount.
| loyalty | 1000.00 | 900.00 | | loyalty | 1000.01 | 850.01 | | loyalty | 1234.56 | 1049.38 |
| Markdown-driven SDD GitHub Spec Kit · Kiro specs | Executable specs (ATDD) this repo | |
|---|---|---|
| artifact | spec.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 it | The agent, as context and instructions | The agent and the test runner. Every example is run. |
| "done" means | Tasks 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 merge | Can drift from the code unless someone keeps it updated | Living documentation. The same spec runs on preview, staging and @smoke in production. |
| strength | Great for planning, decomposition and design discussion | Great for verifiable behaviour: boundaries, rounding, error cases |
needs-clarification).kind=specThen assertion. No undefined steps, no crashes.main stays green.src/ changed, the pending ID removed (never added)$ 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.
In CI, tool calls the agent isn't allowed to make are denied quietly. Check permission_denials_count.
--allowedTools completeRe-running a workflow uses the original commit's YAML. Your fix isn't in that run.
The conformance reviewer refused PRs opened by the Claude bot. Agent-to-agent hand-offs need explicit trust.
allowed_bots: 'claude'The deploy reported healthy while the old revision still answered. In-memory state was lost on the traffic switch.
discountNeverExceedsTenPercent encoded the old 10% rule. When the rule changes, the tests pinning it must change too.
Agents love example values. Holdout scenarios with values the agent never sees, plus an independent reviewer, catch "if total == 1000.01".