How to Write an AI Coding Spec: Acceptance Criteria, Constraints, and Tasks

TL;DR: An implementation-ready AI coding spec makes intent, acceptance scenarios, constraints, design choices, and tasks independently reviewable before code changes. This guide uses an OpenSpec “recipe search” change as a worked artifact example and focuses on what good proposal.md, specs/, design.md, and tasks.md content looks like.

Introduction

After understanding the theoretical foundation of Spec Coding, you might wonder: How does this actually work in a real IDE? What tools should I use to manage specification files?

The answer is OpenSpec — an open-source Spec Coding framework by Fission-AI (MIT license). It supports 20+ mainstream AI coding assistants and provides a complete artifact-driven development workflow.

What is OpenSpec?

OpenSpec is a lightweight spec layer that establishes an "agree before you build" contract between you and AI. Its core philosophy:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

Every change generates a set of standardized artifacts:

5-Minute Setup

Prerequisites: Node.js 20.19.0 or higher.

npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

openspec init creates an openspec/ directory and AI guidance files at your project root. Once initialized, you can start using slash commands in your AI coding assistant immediately.

Also works with pnpm, yarn, bun, and nix. See the installation docs.

The Practical Trio: OpenSpec + CLAUDE.md + .cursorrules

In the 2026 AI programming ecosystem, these three form the complete Spec Coding toolchain:

1. OpenSpec: The artifact-driven development framework that manages the entire lifecycle of changes via slash commands.
2. CLAUDE.md: A project memory specification popularized by Anthropic. It acts as a "Project Constitution," recording core architecture, tech stack choices, and established conventions.
3. .cursorrules: IDE-level instructions that enforce code style and constraints (e.g., "Use TypeScript strict mode," "No inline styles").

The division of labor is clear: OpenSpec manages the workflow, CLAUDE.md manages memory, .cursorrules manages style.

Complete Walkthrough: Building "Recipe Search" with OpenSpec

Let's walk through OpenSpec's complete three-step workflow.

Step 1: /opsx:propose — Propose the Change

Don't just tell the AI "Write a search feature." Use OpenSpec's propose command:

/opsx:propose add-recipe-search

The AI automatically creates an openspec/changes/add-recipe-search/ directory with four artifacts:

openspec/changes/add-recipe-search/
├── proposal.md    ← Why we're building this feature
├── specs/         ← Requirements and acceptance scenarios
│   └── search-recipe.md
├── design.md      ← Technical approach
└── tasks.md       ← Implementation checklist

The specs/search-recipe.md will contain structured acceptance criteria:

## Context
Users need to search existing recipes by keyword and filter them by "Cooking Time."

## Acceptance Criteria (Scenarios)
#### Scenario 1: Basic Keyword Search
- **WHEN** the user enters "Egg"
- **THEN** the system should return a list of all recipes with "Egg" in the title

#### Scenario 2: Empty State Handling
- **WHEN** the search results are empty
- **THEN** the system should display "No recipes found" and recommend 3 popular recipes

## Constraints
- Search API response time must be < 200ms
- Search results must support pagination

The tasks.md generates an implementation checklist:

## Implementation Tasks
- [ ] 1.1 Create Search API Endpoint (`/api/recipes/search`)
- [ ] 1.2 Implement full-text search logic (using existing Prisma queries)
- [ ] 2.1 Implement Search UI components (SearchBar + ResultList)
- [ ] 2.2 Add "Cooking Time" filter
- [ ] 3.1 Write API-layer unit tests
- [ ] 3.2 Write component-level E2E tests

Your job at this point is: review these artifacts and ensure the AI understood your intent. You can modify any artifact at any time — OpenSpec's philosophy is "fluid not rigid," with no rigid phase gates.

Step 2: /opsx:apply — Execute Tasks

Once artifacts are reviewed, run the implementation command:

/opsx:apply

The AI executes tasks from tasks.md one by one. Output looks like:

Implementing tasks...
✓ 1.1 Create Search API Endpoint
✓ 1.2 Implement full-text search logic
✓ 2.1 Implement Search UI components
✓ 2.2 Add Cooking Time filter
✓ 3.1 Write API-layer unit tests
✓ 3.2 Write E2E tests
All tasks complete!

Key advantage: The AI reads only one task and its relevant spec context at a time. This "small-step" approach narrows the model's focus and reduces (though never eliminates) the chance of hallucination compared to throwing a vague requirement at it all at once. It does not replace review — you still read the diff and run the tests for each task before trusting the checkmark.

Step 3: /opsx:archive — Archive the Change

After all tasks pass tests:

/opsx:archive

OpenSpec archives the change to openspec/changes/archive/ with a timestamp:

openspec/changes/archive/2026-04-01-add-recipe-search/

This gives you a complete change history. Even three months later, you can quickly understand "why we did this" by reading the proposal.md.

Extended Workflow

The default profile ships a few more core commands beyond the three above: /opsx:explore (think through an idea before proposing) and /opsx:sync (synchronize artifact state). If you want the expanded profile, select it with openspec config profile and apply it with openspec update:

Command sets evolve. Run openspec update inside each project to regenerate AI guidance and ensure the latest slash commands are active, and check the OpenSpec commands doc for the current list.

OpenSpec vs. Alternatives

These three take different shapes rather than sitting on a single quality ladder. The snapshot below reflects mid-2026; all three move fast, so re-check the current docs before standardizing on one.

Note: Kiro is AWS's spec-driven IDE. It is not locked to a single model — through Amazon Bedrock it offers a choice of models (Claude, plus others). Treat "tool support" as a shape difference, not a ranking.

How to Write High-Quality Specs (The Golden Rules)

A good specification should have three key elements:

1. Use WHEN/THEN Syntax: This Behavior-Driven Development (BDD) syntax is extremely AI-friendly because it clarifies inputs and expected outputs.
2. Define Boundary Conditions: Tell the AI what to do if a user enters invalid characters, the network drops, or the data is empty.
3. Define the "Non-Goals": Explicitly forbid behaviors in the spec (e.g., "Do not modify the database schema," "Do not use third-party libraries").

Common Pitfalls: Avoiding Spec Coding Mistakes

• Over-specifying: OpenSpec's philosophy is "fluid not rigid." If you dictate every line of code, you lose the AI's flexibility. Specs should focus on "outcomes," not "low-level instructions."
• Ignoring the Single Source of Truth (SSOT): If you change requirements in chat but don't update the files in specs/, the AI will quickly become confused. Remember: If requirements change, update the Spec first.
• Lack of Task Verification: For every completed task, require the AI to run corresponding tests rather than just trusting its "I'm done" message.
• Skipping Archive: /opsx:archive is not optional. Archiving means knowledge persistence — three months later, you or your teammates can quickly understand the change history through archived artifacts.

Model Recommendations and Context Hygiene

Do not pin a model from an article. Check the current OpenSpec README for supported hosts, then evaluate available models on the actual work: scenario completeness, constraint adherence, unsupported assumptions, diff quality, test validity, latency, and cost. Planning and implementation can favor different models; a provider label does not predict either result.

Context hygiene: Before starting /opsx:apply, clear the AI's context window so it focuses on the current change's artifacts rather than stale conversation history.

Summary

A well-written specification gives people and agents a concrete artifact to challenge before implementation. OpenSpec can manage that artifact lifecycle, but production readiness still depends on architecture, review, tests, security controls, deployment evidence, and operations. The practical skill is writing acceptance criteria and constraints that can actually fail, then preserving the evidence.

Ready to go further? Learn how to build an automated runtime environment for your AI Agent with Harness Engineering.

Related Reading:

• Spec Coding Concept Complete Guide
• Vibe Coding Practical Guide: From Cursor to Claude Code
• Context Engineering: How to Provide the Perfect Context for AI