Spec-Driven Development With AI Coding Agents

Why specs matter more in AI flows

• The agent has no shared culture, no whiteboard chats, no quick "wait, what about…" hallway question.
• It executes the spec literally, with confidence, even when the spec is wrong.
• Errors compound: a vague spec becomes vague code, becomes vague tests, becomes confidently wrong working software.
• A tight spec is the cheapest place to fix the bug.

What a good AI-era spec contains

1. Goal — one or two sentences. What outcome, for whom, why.
2. Scope — what is in, what is explicitly out.
3. Acceptance criteria — measurable, ideally testable. "When I POST X, I get Y. Test passes."
4. Constraints — code conventions, libraries to use / avoid, performance budgets, security requirements.
5. Pointers — files to read, similar features to mirror, docs to follow.
6. Non-goals — common scope creep ("don't refactor unrelated modules").

This is not new. It's just that humans tolerate ambiguity; agents don't.

The spec → agent → review pipeline

Human writes spec  →  Agent plans  →  Human approves plan  →  Agent implements
        ↑                                                            ↓
        └──────────────────  Human reviews diff  ←───────────────────┘

Every arrow is a checkpoint. Skip them and quality regresses fast.

Where teams get this wrong

• One-line briefs. "Add filtering to the user list." No fields, no UX, no acceptance.
• No non-goals. The agent "improves" five unrelated files because nothing told it not to.
• No tests in the spec. Agents lean on tests; without them, "done" is "the code looks like it works."
• Rewriting specs after the fact. Specs that drift mid-execution lose their value as a contract.

Spec patterns that compound

• CLAUDE.md / AGENTS.md at repo root — project-wide conventions. The agent reads it every session.
• Per-task spec files — .tasks/<id>.md checked into the branch with the work. Auditable, reviewable.
• Checklists — explicit step-by-step in the spec; agents tick them off.
• Examples block — "do it like this existing thing" beats "use this style" every time.

Where humans still own the keys

• Architecture and trade-offs. Spec writing happens after you've decided the shape.
• Ambiguity resolution. "We could do A or B" — agents need to be told which.
• Sign-off. A spec the team accepts, not a prompt one engineer hammered out.

A pragmatic workflow

1. Sketch the design in plain text first. Decide the shape.
2. Turn the design into a spec with the structure above.
3. Give the spec to the agent; ask for a plan; review the plan.
4. Approve the plan; agent implements; review the diff.
5. Iterate on the spec, not on prompts. Specs become the artefact.

What changes about engineering

The keyboard is no longer the primary interface. The spec is the new keyboard. Engineers who lean into clear technical writing, crisp acceptance criteria, and explicit non-goals will out-ship engineers who type fast and explain badly. The job didn't shrink — it moved upstream.

In one line

In AI-driven dev, the spec is your code. Treat it with the rigour you used to spend on the implementation.