OpenSpec Practise

🌐 English Version

This project originated from in-depth discussions on AI programming within the “AI Force Injection” community. In response to the community’s vision of “leveraging OpenSpec for Spec-Driven Development,” this project demonstrates the practical application of the OpenSpec specification in AI-assisted programming through a complete hands-on example.

As a learning and practice repository for OpenSpec, this project provides systematic documentation analysis, detailed user manuals, and multi-language examples, aimed at helping developers deeply understand and efficiently apply the specification.

Star History:

Project Structure

This project consists of four core modules:

1. Documentation

Contains theoretical analysis and practical guides for OpenSpec, helping to understand the ideas and workflows behind the specification.

OpenSpec User Manual: The complete user manual for OpenSpec, covering installation, initialization, documentation standards, validation, best practices, and more.

“OpenSpec is a Spec-Driven Development (SDD) framework designed specifically for AI programming assistants. It ensures that humans and AI reach a shared understanding of requirements by defining specifications before writing code.” — OpenSpec User Manual

Companion slides: Legacy PPT · Current PPT
OpenSpec Practical Guide: A concrete implementation guide for putting OpenSpec into practice.

“OpenSpec is not just a documentation format — it is an engineering practice of Spec-Driven Development. It advocates ‘specification as the source of truth,’ ensuring that code and tests always remain consistent with the design.” — OpenSpec Practical Guide
OpenSpec Practical Guide: A Deep Retrospective on AI-Assisted Software Engineering End-to-End: An in-depth analysis of the role and value of OpenSpec in AI programming workflows.

“The traditional development model is Requirements -> Human -> Code, while the new paradigm is evolving into Intent -> Spec (OpenSpec) -> AI -> Code & Verification.” — OpenSpec AI Workflow Analysis

2. Example Code

A minimal multi-language implementation (MVP) based on an e-commerce scenario, demonstrating how the OpenSpec specification drives code delivery.

ecommerce-mini (Node.js)
- src/domain: Core business logic, a clean domain layer.
- src/http: API interface implementation.
- src/services: Business service layer.
- src/repo: In-memory data storage.
- src/persist: File-based persistent storage.
- __tests__: Accompanying test cases (unit tests, integration tests, performance tests).
ecommerce-mini-python (Python)
- src/domain: Domain models defined with Pydantic.
- src/services: Business service layer.
- src/api: API service implemented with FastAPI.
- src/repo: In-memory data storage.
- tests: Pytest test suite.

3. OpenSpec Specifications

Complete specification files demonstrating the SDD workflow, stored under examples/openspec/.

examples/openspec/config.yaml: Project context configuration (tech stack, conventions, etc.), automatically injected into each AI planning request.
examples/openspec/changes/v1-mvp/: Complete change specifications for the MVP version (archived).
- proposal.md: Change proposal (Why / What Changes / Capabilities).
- design.md: System architecture design (layered architecture and data flow).
- tasks.md: Implementation task checklist.
- specs/domain-model/spec.md: Core domain model specification.
- specs/catalog-management/spec.md: Product catalog management specification.
- specs/cart-management/spec.md: Shopping cart management specification.
- specs/order-management/spec.md: Order management specification.
- specs/payment/spec.md: Payment specification.
- specs/error-handling/spec.md: Error handling specification.
examples/openspec/specs/: Archived master specifications (merged from v1-mvp).

4. Test Data

Test data files used by the example projects.

examples/ecommerce-mini/data/: Test data for the Node.js version.
- products.json: Product data.
- carts.json: Cart data.
- orders.json: Order data.

Core Features

This project demonstrates the following core OpenSpec features:

Spec-Driven Development: Define specifications first, then write code, ensuring AI and humans reach a shared understanding of requirements.
Multi-language Implementation: Using the same specification to drive both Node.js and Python implementations.
Comprehensive Test Coverage: Unit tests, integration tests, and performance tests.
Production-Grade Extensions: Persistent storage, authentication, idempotency, and observability.
Deep AI Collaboration: Generate OPSX slash commands (/opsx:propose, /opsx:apply, etc.) via openspec init, supporting standardized collaborative workflows with 20+ AI programming assistants (such as Cursor, Claude Code, Junie, Lingma, etc.).

DDD to OpenSpec Mapping

The strategic insights of Domain-Driven Design (DDD) combined with the structured specifications of OpenSpec build a highly reliable connection system from domain models to engineering code. The standard mapping paths for converting DDD deliverables into the OpenSpec workflow described below are distilled from the open-source skill repository project domain-driven-design-skills (see the ddd-openspec-mapping.md document for details).

1. Strategic Alignment and Directory Mapping

At the strategic level, by introducing DDD’s spatial partitioning methodology into OpenSpec’s directory structure, a natural correspondence between design and specification can be achieved.

The “Bounded Context” in DDD corresponds to the sub-domain directories under the specs/ directory in OpenSpec. This alignment ensures that every business boundary identified by DDD has a clear attribution in the engineering specifications. Meanwhile, declaring this mapping relationship in openspec/config.yaml provides the AI Agent with a global architectural context.

# openspec/config.yaml example: Domain and Bounded Context mapping configuration
context: |
  ## Project Domain Mapping
  This system follows DDD design, and core bounded contexts include:
  - User Management Context
  - Order Management Context
  - Payment Context

2. Tactical Implementation and Structure Mapping

Tactical design determines the quality of code implementation. OpenSpec provides a structured expression method to transform DDD building blocks into verifiable and executable task sequences.

The table below shows the specific mapping relationship between OpenSpec core components and DDD deliverables:

OpenSpec Specification Structure	Corresponding DDD Deliverable	Description and Explanation
Domain	Bounded Context	A domain directory corresponds to a bounded context.
Requirement	Domain Service / Command	Describes a core business function or operation.
Scenario	Aggregate Behavior	Uses Given/When/Then format to precisely describe aggregate behavior.
Design	Application Service	Coordinates multiple domain services, manages transactions and security.
Tasks	Tactical Design Backlog	Tasks for concrete implementations like entities, value objects, repository interfaces, etc.

3. Workflow-Driven Lifecycle

The OpenSpec workflow highly aligns with the iterative modeling of DDD, emphasizing a brownfield-first refactoring capability.

Propose: Use /opsx:propose to quickly initialize changes and consolidate domain modeling conclusions.
Apply: Utilize AI to implement code and perform automated verification based on the specifications (Requirements and Scenarios).
Archive: Merge incremental specifications into the master specification via openspec archive, ensuring a single source of truth for domain knowledge.

Quick Start

Node.js Example

Navigate to the examples/ecommerce-mini directory:

# Install dependencies (no external dependencies in this project, but good practice)
npm install

# Run tests (using Node.js built-in test runner)
npm test

# Start development server (in-memory storage, listening on port 3000 by default)
npm start

# Start production server (file persistence, authentication, listening on port 3002 by default)
npm run start:prod

Python Example

Navigate to the examples/ecommerce-mini-python directory:

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Start server (listening on port 8000 by default)
python -m uvicorn src.api.server:app --reload

Learning Path

Recommended learning order:

Getting Started: Read the OpenSpec User Manual to understand the basic concepts and usage of OpenSpec.
Practice: Read the OpenSpec Practical Guide to understand how to apply it in real projects.
Deep Dive: Read the OpenSpec Practical Guide: A Deep Retrospective on AI-Assisted Software Engineering End-to-End to learn best practices for AI collaboration.
Hands-On: Run examples/ecommerce-mini and examples/ecommerce-mini-python to experience spec-driven development firsthand.
Research: Browse the specification files under examples/openspec/changes/v1-mvp/ to learn how to write specifications.

Companion AI Skills

To more efficiently implement OpenSpec specifications in real-world development, this project recommends pairing with a dedicated AI assistant skill.

OpenSpec Assistant: An AI skill designed specifically for executing OpenSpec Spec-Driven Development (SDD). It covers the complete lifecycle of intent alignment, specification generation, code implementation, and automated verification. It also supports multi-role collaboration among architects (writing and reviewing specs), developers (writing code), and QA engineers (writing tests), and natively supports the /opsx command system used in this project.