AI-assisted spec writing: conversational specs, 5 techniques, and spec hallucination | SDD

AI is shifting from spec executor to spec co-author. A repeatable workflow, 5 AI-assisted spec writing techniques, and how to catch spec hallucination.

Everyone measures AI’s return in lines of code per minute — but the biggest leverage is elsewhere: in the specification you write before the first line of code exists. This matters to anyone handing work to an agent. A model will flawlessly implement a flawed requirement, and the tests — also generated from the same spec — will confirm that “everything works.” The cost of the mistake crystallizes at the spec level, not the code level.

In about ten minutes of reading, you’ll get a repeatable “draft → AI feedback → refined spec” workflow, five techniques with ready-made prompts, and a spec hallucination checklist. Not generalities about how “AI helps” — concrete material you can paste into your own editor tomorrow morning.

Quick Win — The Core Shift

Role Reversal, Not Faster Writing

The fastest return from a model on specifications doesn’t come from AI “writing the spec for you.” It comes from role reversal: you stop writing a document from scratch and start conducting a dialogue in which the model tirelessly asks clarifying questions, detects gaps, and forces decisions.

In practice, it looks like this: you throw in a loose sketch — a brain dump — the model returns a list of questions about edge cases and contradictions, you answer (often choosing from suggested options), and the model closes the loop by generating acceptance criteria in standardized syntax. The goal, which some practitioners consider realistically achievable: a spec that passes the first review — instead of several rounds of manual rewriting.

This isn’t magic; it’s a shift of work. Complexity doesn’t disappear — it moves from the code phase to the spec phase, where it’s cheaper to fix. There is one hard constraint you can’t break: intent, trade-offs, and the “why” belong to the human, while the model structures and fills in edge cases. Break that rule and you fall into a new class of error: hallucination at the specification level.

Let’s start with where this shift came from — and why previous attempts at “the spec as a source of truth” failed.

From Hand-Written Markdown to Specs Written in Dialogue

The idea of making the specification the central artifact of a project, rather than the code, has at least three waves of attempts behind it. Each failed not because of a lack of effectiveness, but because of the cost of entry — and that’s exactly the cost AI is now driving nearly to zero.

Three Waves, One Root Cause

The first wave was the formal methods of the 1980s and 1990s — notations like Z or TLA+, in which systems were described with mathematical rigor. They worked, but they required training that businesses weren’t willing to fund, and the client couldn’t read such a document.

The second wave — Model-Driven Architecture and UML generators — promised code straight from diagrams, but got stuck on the “round-trip problem”: manual changes to generated code drifted away from the model. The third wave, BDD and Gherkin, was supposed to bridge business and engineering, but maintaining the mappings between feature text and test code proved so tedious that .feature files became dead documentation.

The common denominator of these failures is clear: all of them required a notation specialist. Business people couldn’t read the spec, so the spec didn’t serve as a shared language — it was just another artifact to maintain.

What AI Changes

A model accepts ambiguous natural language and actively refines it, instead of rejecting it. Specs get written as plain Markdown or in a dialogue with an agent — no DSL, no UML, no notation course required. That’s the whole difference: the entry barrier that brought down its predecessors has just been removed.

From this shift follows an inversion that sounds provocative until you’ve worked with an agent for a week: code becomes an implementation detail of the specification, not the other way around. The spec declares intent; the agent executes it. In practice, the spec stops being a document that gathers dust and becomes the human-agent interface — the control surface through which you drive the model. A neat shorthand circulating in this space: the spec is the brain; the agent is the muscle.

Now that the entry barrier is gone, a practical question arises: which tool actually does this well?

Four waves of attempts to make specifications the source of truth — AI eliminates the barrier that broke the previous ones.

How Claude Code, Cursor, and JetBrains Junie Help Write Specs

The three most popular tools follow one pattern — plan and spec before code — but they differ on one decisive point: how firmly they enforce the human checkpoint. That matters more than which AI is “smarter.”

Claude Code and Cursor

Claude Code has Plan Mode — a mode in which the model plans and asks questions first, rather than writing code. It operates in a read-only state: it can read the repository but can’t edit files until you approve the plan. In this mode, the model asks clarifying questions, often proposing ready-made options to choose from, which shortens the iteration loop. The official rule is disarmingly simple: if a change can be described in one sentence, skip the plan. Worth knowing the boundary, though. Honestly — this is “prompt reinforcement,” not a hard technical lock; the plan’s quality depends directly on the project rules file (CLAUDE.md) that the agent reads at the start of every task like an onboarding manual.

Cursor takes a different approach. It doesn’t have a dedicated Plan Mode (as of this writing — tools in this category evolve month by month), but it has rules in .cursor/rules and @file references — your "spec-in-repo" injected into the context on every query. It's a lightweight, ad-hoc approach: the spec is a hint next to the code, not an enforced checkpoint.

JetBrains Junie

JetBrains Junie sits at the opposite end. Plan Mode here is a checkpoint the developer activates before touching code — triggered with the /plan command, and /effort lets you dial up how deeply the model elaborates before it moves to implementation.

Across all the differences between tools, one shared pattern stands out — worth adopting regardless of the editor: the spec and plan are committed artifacts in the repo, not a one-off document. Kept alongside the code, versioned, they become the system’s memory — recording not just what was built, but why.

The tool is just the stage. Now for the concrete: five techniques that work regardless of the editor.

Three tools, one pattern (plan before code) — the difference lies in how firmly each enforces the human approval gate.

Five Techniques for AI-Assisted Spec Writing

A good prompt for writing a spec is the inverse of a prompt for writing code. A code prompt says “do X.” A spec prompt asks “what should I resolve before X exists at all?” The following five techniques deliver the biggest return because each attacks a different weakness of hand-written specs: underspecification, verbosity, blind spots, hidden decisions, and inconsistency.

1. Clarifying questions. Instead of asking for a finished document, make the model interrogate you first: “Before you write the spec: what questions do I need to resolve, what edge cases am I missing, what assumptions are hidden in my description?” This is the heart of the entire workflow — and the only technique with quantitative evidence from code generation research. The mechanism by which the model checks requirement consistency and asks about ambiguity raised GPT-4’s performance on a popular programming benchmark from 70.96% to 80.80% (ClarifyGPT, FSE 2024, MBPP-sanitized). It’s a code generation benchmark, not a spec review — but the direction is unambiguous: asking before acting genuinely improves quality.

2. Acceptance criteria in EARS. EARS — Easy Approach to Requirements Syntax — consists of five sentence patterns developed at Rolls-Royce for aviation requirements (Alistair Mavin, RE’09): ubiquitous (“system SHALL…”), event-driven (“WHEN X, system SHALL Y”), state-driven (“WHILE X, system SHALL Y”), optional feature (“WHERE X, system SHALL Y”), and unwanted behavior (“IF X THEN system SHALL Y”). It turns “the system should be fast” into a testable condition — each pattern covers a different situation: the happy path, a state (offline mode or an ongoing operation), and error handling. Some tools generate these criteria automatically for every user story.

3. Adversarial reviewer. Run the model as a hostile QA engineer: “Find 10 ways this system can fail.” The model hunts for logic gaps, unhandled states, and security holes — before a single line of code exists. It’s a cheap red-team simulation at the text level.

4. Variants with trade-offs. A hard rule applies here: the model does NOT decide for you. When a requirement is expensive or ambiguous, have it generate 2–3 architectural variants with a cost and risk breakdown — synchronous API vs. event queue, immediate cancellation vs. cancellation at period end. The human makes the call. This is the only one of the five techniques where the decision deliberately stays on your side.

5. Prompt skeleton and terminology consistency. Give the model a rigid section template — actors, preconditions, main scenario, alternative scenario — in which it may only fill in designated fields. Rigid structure blocks model verbosity and ensures one name per concept. It’s the simplest defense against “spec bloat,” which we will discuss in a moment.

The Principle That Ties All Five Together

In the spec, you separate “what and why” (human) from “how” (AI), and you don’t write into the spec what the model already knows. The model knows the stack and best practices from training — write only the domain-specific context it doesn’t have.

The techniques sound abstract until you see the same requirement before and after.

Five techniques, five different weaknesses of hand-written specs — only one gives the decision back to the human.

The Same Requirement Before and After

The difference between a loose sentence and an EARS requirement with acceptance criteria is the difference between “the agent will guess” and “the agent knows.” Here’s a concrete fragment — not a screenshot, but the actual text, because text is what lands in the model’s context.

BEFORE looks like most backlog tickets:

User can cancel subscription.

One sentence, zero edge cases, open to interpretation. An agent receiving this description must guess at least three things.

This is where the clarifying dialogue comes in. The model doesn’t write immediately — it asks: what happens with a payment in progress, what about refunds for unused time, what about reactivation after cancellation? For an expensive decision (technique 4) it surfaces a variant: immediate cancellation vs. cancellation at the end of the paid period — and leaves the choice to you.

AFTER that conversation, the same requirement looks different:

WHEN the user confirms cancellation, THE system SHALL
  preserve access until the end of the paid billing period.
IF a pending payment is unresolved, THEN THE system SHALL
  hold the cancellation until the payment clears and notify the user.
WHILE the subscription is in state "cancelled, active until date X",
  THE system SHALL allow reactivation without a new payment.

Acceptance criteria:
- after cancellation, access expires exactly on the period end date, not before
- a cancellation attempt with a payment in progress returns a message, not a 500 error

Same requirement, two different worlds. On the left: a guessing game for the agent. On the right: a contract that’s hard to implement incorrectly. The value of conversational SDD is visible only in a fragment like this — it’s proof, not a promise.

Since AI closes requirements so neatly, where’s the catch? There is one.

Same requirement: on the left a guessing game for the agent, on the right a contract that can’t be implemented wrong.

Spec Hallucination and How to Catch It

“The biggest problem with specifications in my experience is actually underspecification — it’s easy to miss requirements that you don’t know you don’t know.” — Den Delimarsky, Creator of GitHub Spec Kit

The most dangerous hallucination isn’t in the code — it’s in the specification. Spec hallucination is a new class of error: during the draft-closing phase (auto-refinement), the model appends a requirement that is grammatically and logically consistent, but that nobody requested. Once written into the document, it becomes the “source of truth” from which everything else is generated.

Why is this more dangerous than a bug in code? A code bug gets caught by the compiler, linter, or tests. A hallucination in the spec is semantically valid — the agent implements it flawlessly, and the tests (also generated from the same spec) confirm the code works 100% as specified. The mistake reaches production as a “correctly implemented error.”

Four Forms Worth Recognizing

Imagine the most dangerous variant in the financial sector: while closing a transaction module, the model appends a requirement that in the event of an authorization service failure, transactions below a certain threshold should be approved locally without balance verification. The team — trusting the well-formatted document — approves the spec, the code passes the tests, and it ships to production as a correctly implemented vulnerability. No test catches it, because the tests were built from the same source.

In practice, spec hallucination takes four forms worth knowing (based on a taxonomy from research into model-generated specification failures):

• pattern hallucination — you say “task management app,” the model appends everything it’s seen in training: boards, drag-and-drop, recurring tasks, tags;
• scope-creep hallucination — it assumes authentication, a database, full REST, even though you only asked to explore an idea;
• reference hallucination — it cites a nonexistent document section or an API the spec never mentioned;
• calculation hallucination — it supplies a number (“required throughput is 12,500”) when the source says something different.

Heavier artillery is coming for these four classes: formal verification, where an SMT solver engine mathematically checks whether a set of requirements is internally consistent. AWS Kiro Requirements Analysis is heading exactly in that direction. It’s a topic for a separate conversation — for now, it’s enough to know the direction exists.

The Agreement Trap and the Condition Map

Here we reach the most interesting apparent paradox. A model is an excellent reviewer — tirelessly asking questions, experiencing no fatigue, and never skipping the obvious. Research on model sycophancy simultaneously shows that models systematically agree: in one 2025 study (ELEPHANT, Cheng et al., arXiv:2505.13995) models failed to challenge unjustified user assumptions in 86% of cases, and users actually preferred the agreeable versions. Separate studies show the effect grows in long, personalized sessions.

This isn’t a contradiction — it reflects two different working conditions. AI is a tireless reviewer in a single shot — and a systematic yes-sayer in a long session. Fresh eyes on someone else’s text catch gaps; the same conversation drawn out for an hour drifts toward agreeing with you. Hence the rule: for spec reviews, use a fresh session and explicitly tell the model to attack assumptions, not confirm them.

A Checklist for Implementation

How do you catch spec hallucinations before they enter implementation? The checklist is short and repeatable:

• cross-check against scope/brief — compare every requirement against the original brief; look for what you didn’t request;
• reference verification — check API names, library names, and cited sections against official documentation;
• contradiction detection — ask the model (in a fresh session) to find inconsistencies between modules;
• human-in-the-loop intent checkpoint — a mandatory gate where a human approves the spec before the agent begins implementation; this is the last barrier that catches spec hallucinations.

There’s another side to the debate. Some experienced practitioners are genuinely skeptical of verbose specifications — and rightly so. Auto-refinement without rigid guardrails leads to “spec bloat.”

Birgitta Böckeler of Thoughtworks describes the effect directly: spec-kit generates many markdown files that are — her words — “very verbose and tedious to review,” and she’d rather read the code than those files. Some Thoughtworks practitioners go further: SDD drives the need for excessive specification and ends up with a file count that the team simply cannot maintain. Auto-refinement without guardrails balloons the spec to a size the team just doesn’t read.

Completeness is not quality. That’s why the prompt skeleton and a hard length limit are just as important as closing the gaps in the first place.

Since the risks are real, the question becomes: does this work at an enterprise scale? Let’s look at the numbers.

A code bug is stopped by tests; a spec bug is confirmed by tests — because they were built from the same source.

Spec as Agent Interface — Enterprise Case

At an enterprise scale, the spec stops being a document and becomes the control interface for a fleet of agents. Enterprises aren’t buying “AI that writes code” — they’re buying a repeatable intent interface in which a product owner without coding experience generates production-ready prototypes, and developers focus on architecture.

The best-documented public example is the AWS agentic stack deployment at Delta Airlines, shown at re:Invent 2025. The numbers are striking: 1,948% growth in Amazon Q Developer adoption over six months and 94% satisfaction among developer teams — a project subsequently migrated to Kiro, a newer IDE natively built around a spec-driven workflow. Backlog grooming turned into design sessions, and product owners without coding backgrounds generated production-ready prototypes.

The enterprise mechanism rests on a three-phase workflow: the model expands a single prompt into three files — requirements (in EARS), design, and tasks with a dependency graph — where each task has traceability back to a requirement. Independent tasks run in parallel, cutting implementation time on large projects by roughly 75%.

An honest caveat is needed here, because it’s easy to get carried away by metrics. The 1,948% and 94% are process metrics — adoption and satisfaction — not code quality or production defect counts. They say people liked the tool and adopted it, not that the code is better. Worth hearing the other side too: some respected BDD practitioners warn that “one shot from spec to product” approaches are doomed to fail, like CASE tools in their day — great for selling to executives, disappointing in practice. What works is a tight, iterative loop in which AI handles the structural part of the work and the human retains ownership of domain knowledge and architectural judgment.

This leads to the role the spec is starting to play: a living document committed to the repo, the system’s memory that grows with the code. Keeping that memory alive after generation is a separate topic.

Summary and Takeaways

If this article leaves one thought, let it be this: stop measuring AI’s return in lines of code. The leverage is in the specification — in what you resolve before the agent moves. Specifications co-created with AI today, and eventually largely generated and maintained by agents, shift the engineer’s role from “writes code” to system judge.

What to take to work tomorrow:

• Repeatable workflow: sketch → AI asks and detects gaps → you answer → AI turns it into acceptance criteria → you approve. Goal: a spec that passes the first review, without several rounds of rewriting.
• Five techniques: clarifying questions, acceptance criteria in EARS, adversarial reviewer, variants with trade-offs, prompt skeleton with consistent terminology.
• New class of error: spec hallucination — caught by an intent checkpoint, not by tests. In long sessions, watch for agreement drift; return with a fresh session for review.
• The boundary (human-in-the-loop): intent, trade-offs, and “why” belong to the human. AI structures and fills in edge cases. That boundary doesn’t get handed to the model.

Deploy one thing tomorrow: a prompt skeleton for reviewing your own spec, plus the four-point hallucination checklist. That’s enough to feel the difference.

I appreciate you reading this far — it was dense material, and I value your time. If this changed how you think about AI’s role in writing specifications, share it with someone who still measures productivity in lines of code — and let me know in the comments what edge case AI caught in your spec before you did. If you want to go deeper into keeping such a spec alive after generation, I’ve written about living documentation separately.