On this page
How to Write a Spec an AI Coding Agent Can Actually Follow
Write specs that produce reliable AI-generated code: explicit goals, edge cases, non-goals, and acceptance criteria. A practical, template-driven guide.
Quick answer
- A good spec tells the agent the goal, the constraints, the edge cases, and how you’ll verify success.
- Be explicit about what not to do — that’s where agents guess and drift.
- The spec is the contract; the agent’s job is to satisfy it, and yours is to test it.
What makes a spec work
An agent succeeds when it has no ambiguity to resolve on its own. The spec must state the outcome, the scope, the constraints it must respect, the cases it must handle, and the criteria that define done. The more you leave implicit, the more the agent invents — and the harder it is to tell whether the result is right.
The template
Write these six sections, sized to the change:
- Goal — one sentence: what should exist when this is done.
- Context — what the codebase already does, and where this fits.
- Behavior — the exact inputs, outputs, and steps for the happy path.
- Edge cases — empty input, failure, concurrency, missing data.
- Constraints & non-goals — what it must not do, change, or touch.
- Acceptance criteria — a checklist you can verify.
A worked example
Instead of “add user login”:
Goal: users can create an account and log in with email and password. Context: existing Express app; users table already exists. Behavior: POST /register creates a user; POST /login returns a session token; both return JSON errors on failure. Edge cases: duplicate email, short password, malformed JSON, missing fields. Constraints: use bcrypt for password hashing (never plaintext); don’t change the users schema; don’t add email sending. Acceptance criteria: registering then logging in returns a token; duplicate email returns 409; password is stored as a bcrypt hash.
How to verify it worked: the agent’s output satisfies every acceptance criterion, and a quick read shows it respected the constraints — no plaintext password, no schema change.
Why constraints matter most
The non-goals are the highest-value section, because that’s where agents guess. “Don’t change the schema” prevents a silent migration; “never log passwords” prevents a security regression. Explicit constraints are how you keep the agent inside the lines you’d draw yourself.
Where this bites vibecoders
The single biggest improvement to any vibe-coding session is writing the spec before the first prompt. It converts “the assistant did something unexpected” into a checkable mismatch — either the spec was unclear or the implementation missed it, and both are fixable. Ambiguity is the tax you pay in debugging later; the spec pays it up front.
Where AI coding assistants get this wrong
- Implementing the happy path and ignoring every edge case you didn’t name.
- “Improving” things outside the spec because they looked incomplete.
- Silently changing schema, deps, or conventions to make its approach work.
- Declaring done without evidence against the acceptance criteria.
Checklist
- Write the goal in one sentence before prompting.
- Enumerate edge cases, not just the happy path.
- State constraints and non-goals explicitly.
- Define acceptance criteria you can test.
- Verify the output against the spec, not just “it runs.”
FAQ
How long should a spec be?
As long as the change needs and no longer. A bug fix might be two lines; a feature might be a page. The test is whether a fresh agent could implement it without asking you to resolve ambiguity.
Should the spec live in the repo?
Yes. Committing the spec next to the code gives you a record of intent, a review artifact, and a reference for future changes. It’s the difference between a conversation and a document.
Can I write the spec with the AI’s help?
Yes — drafting the spec is itself a good use of the assistant, as long as you review and own it. The spec is your judgment encoded; don’t outsource the judgment.
Related topics
- What Is Spec-Driven Development?
- What Is Context Engineering?
- How to Review AI-Generated Code Like a Senior Engineer