How OpenSpec Enables Spec‑Driven Backend Development with Claude AI

OpenSpec Overview

OpenSpec’s core idea is Spec‑Driven Development (SDD): before writing any code, developers and an LLM reach a clear, traceable agreement on “what to build”, preventing the model from drifting.

Key Principles

Align before coding : use a structured document chain (Proposal → Spec → Design → Tasks) to keep requirements, design and implementation aligned.

Change‑as‑Code : treat every software change as an independent, versioned, verifiable code unit with full context.

Fluid, not rigid : no hard stage gates; support back‑tracking, iteration and parallel work, fitting agile and exploratory tasks.

Delta Specs : record only added, modified or removed items, reducing context load and improving LLM precision.

Brownfield‑first : designed for existing projects, lightweight, non‑intrusive, compatible with mainstream AI coding assistants such as Copilot, Cursor, Claude.

Project Initialization

Run the following command in the project root: openspec init The command creates the following directory layout:

your-project/
├── openspec/
│   ├── AGENTS.md        # instructions for interacting with Claude Code
│   ├── project.md       # project metadata such as tech stack
│   ├── specs/           # stores specification files
│   └── changes/         # stores change proposals
└── .claude/             # Claude Code configuration directory

Core Workflow Commands

Start Claude Code : claude code in the project root to enter interactive mode.

Propose : /openspec:proposal "Add user‑role filter to API" creates a proposal folder under openspec/changes/ with a proposal.md containing the full set of constraints.

Implement : after reviewing the proposal, run /openspec:apply <proposal name> to let the LLM generate code according to the spec.

Archive : /openspec:archive <proposal name> moves the finalized spec files to openspec/specs/, completing a development loop.

Specification Files

The proposal generates four key markdown files:

proposal.md : AI expands the short request into a full requirement document (background, goal, acceptance criteria).

design.md : AI produces a concrete technical solution based on the declared tech stack (e.g., NestJS, TypeORM, PostgreSQL), including database checks, API changes, and code‑structure modifications.

tasks.md : AI breaks the design into executable steps that the /openspec:apply command will follow.

specs/ : contains the final specification files (OpenAPI definitions, type definitions, etc.) if the change is complex; otherwise it may stay empty.

Example Proposal

/openspec:proposal "Add user‑role filter to GET /users"
    Requirements:
    1. New query parameter 'role' with enum values admin, editor, viewer.
    2. Only admin users may use the filter; others ignore it.
    3. Invalid role values return 400.
    4. Use existing 'user_role' table, no changes to response shape.

The AI writes a detailed proposal.md and design.md, then creates concrete tasks such as:

Create a migration adding the role column (enum) to the users table.

Update UsersController and UserService.findAll to add a where role = … clause.

Add unit tests covering the illegal‑role scenario.

Iterative Refinement

Developers can generate a draft, review the generated proposal.md and design.md, then correct mistakes via a follow‑up prompt, e.g., “The permission logic is wrong; only super‑admin should see disabled users.” The AI rewrites the files, after which /openspec:apply executes the final implementation.

Additional CLI Utilities

openspec list

: list all change proposals. openspec show <name>: view details of a specific proposal. openspec validate: validate the syntax of specifications. openspec update AGENTS.md: refresh the Claude instruction set.

Locale Configuration

To switch the OpenSpec CLI prompts to Chinese, run: openspec config set locale zh-CN This only affects the interactive messages, not the content of the spec files.