引言：从理论到实战

在前三篇文章中，我们深入探讨了规格驱动开发（SDD）的理念，并详细剖析了 OpenSpec 的设计哲学与核心结构。然而，再精妙的理论，也需要通过实践来验证其价值。

本文将不再停留于概念层面，而是带你进行一次 完整的、端到端的 OpenSpec 实战演练。我们将以一个真实的开源项目——一个简单的 RESTful API 服务为蓝本，为其添加一个全新的功能：“用户个人资料管理”。通过这个过程，你将亲身体验 OpenSpec 如何将模糊的需求转化为清晰的工程指令，并引导 AI 助手高效、准确地完成任务。

图1：OpenSpec 实战工作流全景。从 openspec init 初始化项目上下文，到最终 archive 归档变更，形成一个完整的、可追溯的闭环。

---

一、准备工作：设定舞台

1. 安装 OpenSpec CLI

确保你的环境中已安装 Node.js (>=20.19.0)，然后全局安装 OpenSpec。

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

 2. 选择目标项目

我们选用一个名为 simple-notes-api 的开源项目作为我们的“试验田”。这是一个基于 Node.js 和 Express 构建的极简笔记应用后端，代码结构清晰，非常适合演示。

# 克隆项目
git clone https://github.com/chenmohi/simple_note_api.git

# 或者，如果配置了 SSH 密钥

git clone git@github.com:chenmohi/simple_notes_api.git


cd simple-notes-api

3. 初始化 OpenSpec

在项目根目录下运行初始化命令。OpenSpec 会自动检测你使用的 AI 工具（如 Cursor），并创建必要的目录和配置文件。

openspec init

4. OpenSpec Action

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

5. OpenSpec Dashboard

6. OpenSpec Command

命令	它的作用
/opsx:propose	一步完成变更创建和规划工件生成（默认快速路径）
/opsx:explore	仔细思考想法，调查问题，明确需求。
/opsx:new	启动新的变更框架（扩展工作流程）
/opsx:continue	创建下一个工件（扩展工作流程）
/opsx:ff	快速规划成果（扩展工作流程）
/opsx:apply	执行任务，并根据需要更新工件
/opsx:verify	根据工件验证实现（扩展工作流程）
/opsx:sync	将增量规范同步到主规范（默认工作流程，可选）
/opsx:archive	完成后归档。
/opsx:bulk-archive	归档多个已完成的更改（扩展工作流程）
/opsx:onboard	引导式演练，完整演示端到端变更流程（扩展工作流程）

具体使用可以参考：https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md

二、第一步：填充项目上下文 (config.yaml)

为了让 AI 助手能准确理解我们的项目，我们需要先完善 openspec/project.md 文件。这是整个 SDD 流程的基石。

我们可以向 AI 提出请求：

“请阅读 openspec/config.yaml 并帮助我填写有关我的项目、技术栈和编码约定的详细信息。”

AI 会分析现有代码，并生成类似以下内容：

<!-- openspec/config.yaml -->
schema: spec-driven

# Project context
context: |
  ## 项目概述
  - 项目名称: IVahit
  - 描述: 简单的笔记记录 API (Just a note taker API)
  - 类型: RESTful Web API
  - 许可证: GPL-3.0-or-later

  ## 技术栈
  - **语言**: Python >= 3.9, < 4.0
  - **Web 框架**: FastAPI >= 0.116
  - **ORM**: SQLAlchemy >= 2
  - **数据验证**: Pydantic >= 2
  - **数据库**: PostgreSQL (通过 psycopg2 >= 2.9)
  - **测试**: pytest

  ## 项目结构
  ```
  IVahit/           # 主包
    ├── api/        # API 路由定义
    ├── crud/       # 数据库增删改查操作
    ├── model/      # 数据模型和 Pydantic schemas
    ├── engines.py  # 数据库引擎配置
    ├── mylog.py    # 日志模块
    └── scripts.py  # CLI 脚本命令
  test/             # 测试文件
  ```

  ## 编码约定
  - **代码格式化**: 使用 black (自动格式化)
  - **导入排序**: 使用 isort (自动排序 imports)
  - **代码检查**: ruff (linting)
  - **拼写检查**: codespell
  - **未使用代码检测**: vulture
  - **配置验证**: validate-pyproject
  - **测试框架**: pytest

  ## 可用 CLI 命令
  - `IVahit_create_database`: 创建数据库
  - `IVahit_clear_database`: 清理数据库
  - `IVahit_manual_test_crud`: 手动测试 CRUD 操作

# Per-artifact rules
rules:
  proposal:
    - Keep proposals under 500 words
    - Always include a "Non-goals" section
  tasks:
    - Break tasks into chunks of max 2 hours

这份 config.yaml 文件将成为后续所有 AI 交互的“项目宪法”。

---

三、第二步：创建变更提案 (proposal.md)

如果使用codebuddy，在对话框中输入

# 在codebuddy对话框中
/opsx:propose user-profile-management

会自动生成proposal.md，design.md，tasks.md，并且在changes/user-profile-management/specs目录下生成详细规格文件

我们可以在对话中探索需求，确定功能

# 在codebuddy对话框中
/opsx:explore user-profile-management


# 生成提案
/opsx:new

# 在后续的对话中，不断continue，依次生成proposal、specs、design等
/opsx:continue

# 在对话的过程中，可以对技术方案做出调整

---

四、第三步：协同生成规范、设计与任务

有了清晰的提案，我们就可以让 AI 助手基于它来生成后续的工件。

1. 生成规范 (specs/)

向 AI 提出请求：

“请基于 openspec/changes/user-profile-management/proposal.md 生成详细的、可测试的功能规范，存放在 specs/ 目录下。”

AI 会生成类似 spec.md 的文件，采用 WHEN ... THEN ... 的格式来描述行为：

<!-- openspec/.../specs/profile/spec.md -->
## GET /api/profile
- WHEN 用户已认证
  - THEN 应返回状态码 200
  - THEN 响应体应包含用户的 `nickname` 和 `avatar_url`
- WHEN 用户未认证
  - THEN 应返回状态码 401

## PUT /api/profile
- WHEN 用户发送有效的 `nickname` 和 `avatar_url`
  - THEN 应更新数据库中的记录
  - THEN 应返回更新后的个人资料

2. 生成技术设计 (design.md)

接着，请求 AI 生成技术方案：

“请基于上述规范，为个人资料管理功能设计技术方案，包括数据库变更、API 路由和控制器逻辑。”

AI 会输出 design.md，详细说明如何实现。

3. 拆解任务清单 (tasks.md)

最后，让 AI 将设计方案拆解为具体的、可执行的任务：

“请将 design.md 中的方案拆解成一份详细的、带 checkbox 的任务清单。”

AI 会生成 tasks.md，例如：

• 在 /migrations 中创建 profiles 表的迁移脚本。
• 在 /models 中创建 Profile 模型。
• 在 /routes 中添加 /profile 路由。
• 在 /controllers 中实现 getProfile 和 updateProfile 控制器。
• 为新 API 编写 Jest 测试。

图2：变更提案目录 (changes/) 的内部结构。proposal.md、design.md、tasks.md 和 specs/ 共同构成了一个完整、自包含的工程单元。

---

五、第四步：执行、验证与归档

1. 执行任务

现在，你可以逐项完成 tasks.md 中的任务。你可以手动编码，也可以让 AI 助手根据具体任务描述来生成代码。由于上下文（project.md）和规范（specs/）都已明确，AI 生成的代码将高度精准。

2. 验证变更

在所有任务完成后，使用 OpenSpec CLI 进行验证：

# 验证特定变更的规范格式是否正确
/opcx:verify user-profile-management

或者使用 OpenSpec CLI 进行验证：

# 列出所有变更
openspec list

# 验证特定变更的规范格式是否正确
openspec validate user-profile-management

3. 归档沉淀

当功能开发、测试完毕并准备合并时，执行归档命令：

/opsx:archive

# 或者

openspec archive user-profile-management

此命令会将 changes/user-profile-management/specs/ 下的所有规范文件，移动到主 openspec/specs/ 目录下（例如 openspec/specs/profile-v1.md），正式成为项目知识库的一部分。同时，changes/ 目录下的该提案文件夹会被清理。

至此，一次完整的 OpenSpec 实践圆满结束。我们不仅交付了一个新功能，还为项目沉淀了一份宝贵的、机器可读的规范资产。

---

六、结语：SDD 的真正力量

通过这次实战，我们可以看到，OpenSpec 的真正力量并非在于它能自动生成多少代码，而在于它 强制建立了一种严谨的思考习惯。它要求我们在动手之前，先想清楚“为什么”和“做什么”，并将这些思考固化下来。

这种“先思考，后编码”的模式，极大地降低了沟通成本，提升了代码质量，并为项目的长期可维护性打下了坚实的基础。无论你是独立开发者，还是大型团队的一员，OpenSpec 都能为你的人机协作之旅带来前所未有的清晰度和掌控感。

预告：在下一篇《SDD 的未来：从代码生成到系统演进》中，我们将展望 SDD 范式的未来发展方向，探讨它如何从辅助编码，进化为驱动整个软件系统自主演进的核心引擎。敬请期待！