OpenSpec-practise

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:

Star History Chart

Project Structure

This project consists of five core modules:

1. AI Tool Configuration

AI collaboration commands and skills generated via openspec init --tools claude, located in .claude/.

2. Documentation

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

3. Example Code

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

4. OpenSpec Specifications

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

5. Test Data

Test data files used by the example projects.

Core Features

This project is based on OpenSpec v1.9.0 and demonstrates the following core features:

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

OpenSpec v1.5.0’s workflow highly aligns with DDD’s iterative modeling, with special emphasis on explore-first and brownfield-first refactoring capabilities.

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:

  1. Getting Started: Read the OpenSpec User Manual to understand the basic concepts and usage of OpenSpec.
  2. Practice: Read the OpenSpec Practical Guide to understand how to apply it in real projects.
  3. 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.
  4. Hands-On: Run examples/ecommerce-mini and examples/ecommerce-mini-python to experience spec-driven development firsthand. Both implementations are products of the same set of OpenSpec specifications.
  5. Practice v1.5.0 Workflow: Browse openspec/changes/archive/2026-07-08-add-product-get-by-id/, a “query product by ID” feature added using the complete v1.5.0 workflow (Explore → Propose → Apply → Sync → Archive). Compare the proposal/design/specs/tasks in this change with the final code changes (server.js, server.py) to understand the complete SDD chain from specification to implementation.
  6. Practice v1.7.0 Workflow: Read the v1.7.0 Workflow Practice, a “product search and price sort” feature added using the complete workflow (Explore → Propose → Update → Apply → Sync → Archive), demonstrating how /opsx:update revises planning artifacts mid-implementation while keeping them coherent. Artifacts in openspec/changes/archive/2026-07-28-add-product-search/.
  7. Research: Browse the specification files under openspec/changes/archive/2025-01-27-v1-mvp/ to learn how a complete system’s specifications are built from scratch.

Companion AI Skills

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

This site is open source. Improve this page.