Skip to content
Back to AI Coding

Spec-Driven AI Development

Write acceptance criteria before prompting AI; treat the spec as a contract.

WorkflowIntermediate

Why

GitHub's 2024 enterprise survey of 2,000 developers found 97% have used AI coding tools at work, and Stack Overflow's 2024 survey found 76% of developers use or plan AI tools (up from 70%). A precise spec is the cheapest way to improve AI output. 'Add a login page' yields 10 different implementations; 'POST /login with zod-validated {email,password}, 401 on failure, set JWT cookie, 200 with user' yields one.

When

Write a spec for any feature with >1 acceptance criterion. Skip for trivial edits a one-liner covers.

How

1. Write Given/When/Then acceptance criteria. 2. Add constraints (zod validation, no new deps, follow X pattern). 3. Feed spec + file refs to the AI. 4. Gate: tsc + tests must pass; reject and re-prompt on red. 5. Commit only on green with a conventional message.

Example

Spec: "POST /api/books: validate {title:string, author:string} with zod; reject empty title (400); persist to Books; return 201 + row; log failures." Prompt: "@file src/api/router.ts implement the spec above; follow health.ts pattern"

Common Problems

  • ⚠Error: Cannot find module 'xxx' → run `npm install xxx` (or `pnpm add xxx`); verify it is in package.json dependencies.
  • ⚠Error: "Command not found: claude" or "cursor" → ensure the binary is on PATH: `which claude` / `which cursor`; reinstall globally if missing.
  • ⚠TypeError: Cannot read properties of undefined (reading 'x') → add a null guard or optional chaining `obj?.x`; trace the undefined source via the stack.

Best Practices

  • ✓Write specs as testable acceptance criteria, not prose.
  • ✓Keep the AI loop tight: spec → generate → gate → commit.
  • ✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Spec-Driven AI Development?

Write acceptance criteria before prompting AI; treat the spec as a contract. It helps developers quickly grasp the core value and use cases of Spec-Driven AI Development.

How do I get started with Spec-Driven AI Development?

To get started with Spec-Driven AI Development, focus on these points first: Write Given/When/Then acceptance criteria.

What are common mistakes with Spec-Driven AI Development?

Common mistakes when using Spec-Driven AI Development include: Error: Cannot find module 'xxx' → run `npm install xxx` (or `pnpm add xxx`); verify it is in package.json dependencies.; Error: "Command not found: claude" or "cursor" → ensure the binary is on PATH: `which claude` / `which cursor`; reinstall globally if missing.; TypeError: Cannot read properties of undefined (reading 'x') → add a null guard or optional chaining `obj?.x`; trace the undefined source via the stack..

What are the best practices for Spec-Driven AI Development?

Best practices for Spec-Driven AI Development include: Write specs as testable acceptance criteria, not prose.; Keep the AI loop tight: spec → generate → gate → commit.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Spec-Driven AI Development?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.