OpenSpec 实战：从需求到代码的完整工作流

上一篇讲了概念，这篇我来用一个重构案例，展示 OpenSpec 实际用起来是什么样的

为什么选支付模块做例子

我选支付模块不是随便选的。支付代码有个特点：一开始都很简单，就是调用第三方 SDK 嘛。但随着业务发展，支持的支付方式越来越多，代码就开始乱了。

我见过太多这样的支付模块：

微信支付的逻辑写在 OrderService 里
支付宝的逻辑写在 PaymentController 里
要加个信用卡支付，得改十个文件
新人接手项目，看着代码一脸懵

这篇文章就展示怎么用 OpenSpec 重构这样一个模块。

场景设定

假设你接手了一个电商系统的支付模块。这个模块现在支持微信支付和支付宝，代码存在这些问题：

耦合度高：支付逻辑散落在 OrderService、PaymentController 等多个地方
扩展性差：加个新支付方式要改很多文件
测试困难：没有统一的测试策略，覆盖率不到 60%
文档缺失：新人看代码完全不知道为什么这么写

你的任务是用 Strategy Pattern 重构这个模块，让它更清晰、更易扩展。

步骤 1：初始化 OpenSpec（关键是 `openspec/config.yaml`）

初始化OpenSpec很简单，重点在于描述工程的openspec/config.yaml，当然你可以通过AI来帮你生成。

安装

css 复制代码

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

在项目中初始化

bash 复制代码

cd ecommerce-system
openspec init

这会创建 openspec/ 目录结构和你选择的ide的目录。这里一般会分为三部分，openspec/作为规格驱动开发的工作目录；.xxxx/各种Agentic Coding工具的配置目录，通常其中command + skills两个内容，主要是为了能让我们在跟AI沟通过程中无论使用自然语言还是手动唤起命令，都能使用openspec的能力。

dart 复制代码

.
├── .claude
│   ├── commands
│   │   └── opsx
│   └── skills
│       ├── openspec-apply-change
│       ├── openspec-archive-change
│       ├── openspec-bulk-archive-change
│       ├── openspec-continue-change
│       ├── openspec-explore
│       ├── openspec-ff-change
│       ├── openspec-new-change
│       ├── openspec-onboard
│       ├── openspec-sync-specs
│       └── openspec-verify-change
│ ......
├── .opencode
│   ├── command
│   └── skills
│       ├── openspec-apply-change
│       ├── openspec-archive-change
│       ├── openspec-bulk-archive-change
│       ├── openspec-continue-change
│       ├── openspec-explore
│       ├── openspec-ff-change
│       ├── openspec-new-change
│       ├── openspec-onboard
│       ├── openspec-sync-specs
│       └── openspec-verify-change
└── openspec
    ├── changes
    │   └── archive
    └── specs

配置项目上下文

配置`openspec/config.yaml`

这一步经常被忽视，但是真的很重要。刚初始化的项目会得到这样一个yaml的文件。

makefile 复制代码

schema: spec-driven

# Project context (optional)
# This is shown to AI when creating artifacts.
# Add your tech stack, conventions, style guides, domain knowledge, etc.
# Example:
#   context: |
#     Tech stack: TypeScript, React, Node.js
#     We use conventional commits
#     Domain: e-commerce platform

# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
#   rules:
#     proposal:
#       - Keep proposals under 500 words
#       - Always include a "Non-goals" section
#     tasks:
#       - Break tasks into chunks of max 2 hours

你需要在 openspec/config.yaml 里写清楚项目的背景和规范：

context：写清楚你当前项目的业务定义、开发编码规范、架构标准等等
rules：对各个工件单独增加要求
官方项目的demo：github.com/Fission-AI/...

这个时候我觉得你已经在吐槽，"这么多内容，得写到什么时候???"，"项目中这么多代码，不知道从哪写起啊！"......

别着急，我给大家提供几个写这个内容的思路。

已有的项目代码，首次init的项目

直接一句话，让AI帮你执行吧。比如

bash 复制代码

请按 OpenSpec 的 config 格式，初始化 openspec/config.yaml：项目是支付聚合系统，需包含技术栈、领域术语（渠道/商户/订单/回调/对账）、安全与合规约束。同时要根据 https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md 中对 proposal/design/tasks 功能的描述，填充必要规则。

新项目init，从0开发

这种情况下依然可以用上面那句话，但是这种情况更推荐你把当前要做的功能、服务职责、技术栈、架构要求等信息简历完善的文档放到项目内。

我知道从零开发一个项目很难有详细的文档，资料也可能比较模糊，但是一定有一个最原始的动机。所以一个比较舒服的方案是----"多跟AI唠唠"。

你可能觉得这个建议很废话，但是现在AI的编程和架构能力真的很强，很多时候它会比我想的更超前。

比如，架构方面的SOLID原则，你不需要展开说，只需要提及这个关键字即可。相信我，它比你想的还远。

当然了，唠不是无脑的唠，后面会介绍/opsx:explore，你会明白怎么唠的。

已有项目，且初始化过`project.md`

这个也在这里提一下，如果你的项目在OpenSpec的0.x版本就初始化过了，那完全可以通过openspec update升级，升级过程自己参考openspec的文档吧。这里主要强调一下千万别删除project.md。你可以让AI使用这个文件初始化config。具体做法参考前面吧。

最后因该能得到一份这样内容的文件：

markdown 复制代码

context: |
  电商系统支付模块
  - 技术栈：React + TypeScript + Node.js
  - 数据库：PostgreSQL
  - 当前支付方式：微信支付、支付宝
  - 计划新增：信用卡支付
  
  编码规范：
  - 遵循 Clean Architecture
  - 使用 Domain-Driven Design
  - 所有核心逻辑需要单元测试
  - API 需要集成测试

rules:
  proposal:
    - 敏感信息不得出现在日志中
    - 所有场景要求支持幂等操作
    - ...

  specs:
    - 接口与状态机须覆盖幂等、回调重试与对账口径
    - 支付金额必须使用整数（分）而不是浮点数
    - ...

  tasks:
    - 任务按渠道/商户侧拆分，单任务控制在 2 小时内可验证
    - ...

步骤 2：你的第一个 Change

现在开始真正构建 change 了。但在动手之前，先介绍一个"唠"方案的利器。

用 `/opsx:explore` 先聊清楚

很多开发者有个习惯：拿到需求就开始写代码。但在 AI 编码时代，这个习惯会让你踩坑。AI 也是一样的------给它一个模糊的需求，它就会给你一个模糊的实现。

/opsx:explore 的设计目的就是：让 AI 先思考，而不是直接修改代码。

它就像是一把铲子------帮你在一堆屎山代码中挖出一条路来。

什么时候用 explore？

在屎山代码中导航
- 接手陌生项目，需要快速理解代码结构
- 逻辑散落各处，找不到入口
- 需要理清调用链和依赖关系
- 这时候用 explore "挖一挖"，比直接看代码效率高很多
Change 开始前的需求讨论
- 需求不清晰，需要跟 AI 一起梳理
- 技术方案有多个选择，需要权衡
- 涉及现有代码，需要先理解再动手
执行中的细节探讨
- 遇到意外情况，需要调整方案
- 发现边界条件，需要补充设计
- 任务执行卡住，需要重新思考

怎么用？

bash 复制代码

/opsx:explore 当前支付模块的代码结构是怎样的？支付逻辑散落在哪些文件里？

AI 会分析代码，给你一个清晰的回答，但不会修改任何文件。

bash 复制代码

/opsx:explore 如果我要用 Strategy Pattern 重构支付模块，需要考虑哪些边界情况？

AI 会列出各种边界情况：支付超时、重复回调、部分退款、并发支付等。

bash 复制代码

/opsx:explore 微信支付和支付宝的回调处理有什么差异？现有代码是怎么处理的？

AI 会帮你分析现状，找出潜在问题。

我的使用习惯

我个人的一个习惯：任何复杂的 change，先用 explore 唠清楚。

这个过程就像跟一个资深同事做技术讨论：

你描述问题，它帮你分析
你提出想法，它帮你补充
你有疑虑，它帮你验证

等你们聊透了，再动手，效率会高很多。

两种创建模式

OpenSpec 的 change 创建有两种模式，对应不同的场景：

模式	命令组合	适用场景
快速模式	`/opsx:new` + `/opsx:ff`	简单需求、明确的小功能
迭代模式	`/opsx:new` + `/opsx:continue`	复杂设计、需要多轮讨论

快速模式：`/opsx:new` + `/opsx:ff`

适合场景：

需求明确，技术方案清晰
变更范围可控，预计 1-2 小时完成
不涉及架构调整

用法：

bash 复制代码

/opsx:new add-credit-card-payment
/opsx:ff

ff 是 "fast forward" 的意思，AI 会一次性生成所有工件：proposal、specs、design、tasks。你 review 一下就可以开始实施。

迭代模式：`/opsx:new` + `/opsx:continue`

适合场景：

需求复杂，需要多轮讨论
涉及架构调整，影响范围大
不确定因素多，需要边做边调整

用法：

arduino 复制代码

/opsx:new refactor-payment-module

这时 AI 会创建一个空的 change 目录。然后你开始跟 AI 讨论：

bash 复制代码

/opsx:explore 我想用 Strategy Pattern 重构支付模块，结合现有的代码，帮我评估一下实现。

AI 会分析你的方案，给出建议。讨论几轮后，你觉得方案成熟了：

arduino 复制代码

/opsx:continue refactor-payment-module

AI 会基于你们的讨论，生成 proposal.md。你 review 之后，继续：

arduino 复制代码

/opsx:continue refactor-payment-module

AI 会继续生成 design.md。以此类推，直到所有工件都完成。这其中每一个环节如果你发现任何问题都可以主动的进行/opsx:explore, 涉及到变更的话让AI帮你更新已经生成的工件，然后继续/opsx:continue

迭代模式的优势

很多人觉得现在的Agentic工具非常厉害，一个蜂群可以很完美的完成一大块工作。

动不动一个Agent Team就能重构编译器、自主完成一个项目。我也尝试过用Claude Code的Agent Team形式让他自主完成一个项目，它完成的很好。

不过AI现在有一个事还做都是做不到的--"结合现实的设计"--。我们经常遇到的情况就是"合理且是最佳选择"的情况下不得不向现实低头，选择折中的方案。但是自主开发的AI不会，它会优先安使用最佳选择，尤其是Team模式下。

扯远了，说了这么多其实是想说：

快速模式的问题：

AI 在信息不足的情况下生成工件，质量难以保证
你发现问题后需要反复修改，反而更慢
工件和实际需求脱节，实施时会踩坑

迭代模式的优势：

讨论过程中，AI 逐步理解你的需求
生成的工件更贴合实际情况
减少返工，整体效率更高

我的经验：宁可前面多花 30 分钟讨论，也不要后面花 3 小时返工。

关键：先解决 OpenQuestion，再创建 specs

这里有个重要的实践经验：

Proposal 中经常会有 OpenQuestion（开放问题） ，这些是你之前注意不到的点。比如：

markdown 复制代码

# Proposal: Refactor Payment Module

## Open Questions

1. 支付回调的幂等性用 Redis 还是数据库实现？
2. 如果用户中途切换支付方式，之前的支付记录怎么处理？
3. 对账时发现金额不一致，是人工介入还是自动处理？
4. 微信支付和支付宝的退款逻辑差异怎么统一？

这些问题在快速模式下可能被忽略，导致 specs 和 design 基于"假设"生成，后续实施时才发现问题。

我推荐的工作流：

bash 复制代码

/opsx:explore ──► /opsx:new ──► /opsx:continue (生成 proposal)
                                              │
                                              ▼
                                    发现 OpenQuestion?
                                              │
                                    ┌─────────┴─────────┐
                                    │                   │
                                   YES                  NO
                                    │                   │
                                    ▼                   ▼
                            /opsx:explore         /opsx:continue
                            继续讨论                    │
                            直到问题清晰                ▼
                                    │            生成 specs
                                    └──────────────►│
                                                    ▼
                                              /opsx:continue
                                              生成 design
                                                    │
                                                    ▼
                                              /opsx:continue
                                              生成 tasks

核心原则：OpenQuestion 有了答案之后，再创建 specs。

这样做的好处：

specs 是基于"确定"的信息生成的，不是基于"假设"
design 不会因为前期考虑不周而返工
tasks 的粒度和顺序更合理

官方工作流文档：github.com/Fission-AI/...

主规范（specs/）的来源

主规范描述的是"当前状态"，是所有 change 的基准。不要手动创建 specs，而是通过以下方式：

方式一：`/opsx:onboard` 从现有代码提取

如果你的项目已有代码，可以用 /opsx:onboard 让 AI 分析代码并生成 specs：

bash 复制代码

/opsx:onboard

AI 会分析你的代码结构、业务逻辑，自动生成对应的规范文件，指导你一步步的使用OpenSpec。

方式二：从 change 的 delta specs 合并

如果你是全新项目，没有现有代码，可以：

创建第一个 change
用 /opsx:continue 生成 specs（此时是 delta specs）
实施并 archive 时，delta specs 会合并到主规范

这是更常见的方式------主规范是在 archive 时自动生成的 ，不需要提前手写。但是这里有个要注意的点，有的时候AI不会自动的同步，而是询问是否需要进行sync，这时需要我们手动执行/opsx:sync。

关键点：

specs 描述的是"当前状态"（what the system does now）
change 中的 specs 描述的是"变更"（what will change）
archive 时，delta specs 合并到主规范，形成新的"当前状态"

所以在这个支付模块的例子中，我们不需要提前写主规范。直接开始 change 即可。

步骤 3：创建重构变更（迭代模式示例）

这次我们用迭代模式来演示，因为支付模块重构是一个典型的复杂场景。

官方推荐的迭代模式流程：

bash 复制代码

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

第一步：用 explore 讨论方案

在创建 change 之前，先用 explore 把方案聊透。这是官方推荐的做法------先探索，再动手。

bash 复制代码

/opsx:explore 我打算用 Strategy Pattern 重构支付模块，把微信支付和支付宝的逻辑抽成独立的策略类。你觉得这个方案有什么潜在问题？

AI 可能会指出：

markdown 复制代码

Strategy Pattern 是个好的起点，但有几个问题需要考虑：

1. **策略选择时机**：是在创建订单时确定，还是支付时再选择？
   - 如果是后者，需要考虑用户中途切换支付方式的场景

2. **回调处理差异**：
   - 微信支付回调需要验签，支付宝也需要，但方式不同
   - 需要一个统一的回调处理框架

3. **幂等性**：
   - 重复回调如何处理？
   - 现有代码有幂等保护吗？

4. **状态同步**：
   - 支付状态和订单状态的同步逻辑在哪里？
   - 需要考虑分布式场景吗？

建议先用 explore 看一下现有代码的回调处理逻辑。

继续讨论：

bash 复制代码

/opsx:explore 现有代码的回调处理逻辑是怎样的？

markdown 复制代码

我分析了现有代码，发现：

**微信支付回调**：`PaymentController.handleWechatCallback()`
- 验签逻辑在方法内部
- 直接更新订单状态
- 没有幂等保护

**支付宝回调**：`PaymentController.handleAlipayCallback()`
- 验签逻辑也在方法内部
- 同样直接更新订单状态
- 也没有幂等保护

**问题**：
1. 验签逻辑重复，且不符合 DRY 原则
2. 状态更新逻辑散落在两处
3. 缺少统一的回调处理框架
4. 幂等性缺失，可能导致重复入账

**建议**：
- 创建统一的 `PaymentCallbackHandler`
- 每个策略类负责自己的验签逻辑
- 引入幂等性保护（可用 Redis 或数据库唯一约束）

继续深入：

bash 复制代码

/opsx:explore 如果我要支持幂等，用 Redis 还是数据库方案？

markdown 复制代码

两种方案对比：

**Redis 方案**：
- 优点：性能高，天然支持 TTL
- 缺点：需要引入 Redis 依赖，增加运维复杂度
- 适用：高并发场景

**数据库方案**：
- 优点：不需要额外依赖，简单可靠
- 缺点：需要定期清理过期记录
- 适用：中等并发场景

**建议**：看你的项目情况。
- 如果已经有 Redis，直接用 Redis
- 如果没有，数据库方案够用

另外，支付回调的幂等性还有个关键点：**业务幂等** vs **技术幂等**
- 技术幂等：同一个请求不重复处理
- 业务幂等：同一笔支付不管收到多少次回调，结果一致

你的场景需要哪种？

这样的讨论可以持续几轮，直到你对方案有充分的信心。

第二步：创建 change

聊透之后，创建 change：

arduino 复制代码

/opsx:new refactor-payment-module

AI 会创建 openspec/changes/refactor-payment-module/ 目录，准备接收工件。

第三步：生成 proposal

开始生成工件：

bash 复制代码

/opsx:continue

聊透之后，开始生成工件。

bash 复制代码

/opsx:continue

AI 会基于刚才的讨论，生成 proposal.md：

markdown 复制代码

# Proposal: Refactor Payment Module

## Why
当前支付模块存在以下问题：
1. 高耦合：支付逻辑散落在 OrderService、PaymentController 等多处
2. 低内聚：每种支付方式的逻辑混杂在一起
3. 难扩展：添加信用卡支付需要改动 10+ 个文件
4. 难测试：单元测试覆盖率仅 58%
5. 缺少幂等保护：回调可能重复入账

## What
采用 Strategy Pattern + Clean Architecture 重构支付模块：

1. 抽取支付策略接口（PaymentStrategy）
2. 为每种支付方式实现独立策略（WeChatPayStrategy, AlipayStrategy）
3. 创建支付上下文（PaymentContext）统一管理
4. 统一回调处理框架（PaymentCallbackHandler）
5. 引入幂等性保护（基于数据库唯一约束）
6. 分层架构：Domain → Application → Infrastructure

## Capabilities
重构后的系统能够：
- 轻松添加新的支付方式（只需新增一个 Strategy 类）
- 每种支付方式独立测试（单元测试覆盖率 > 90%）
- 支付逻辑集中管理（单一职责）
- 支持支付方式的热插拔（依赖注入）
- 回调幂等处理（防止重复入账）

## Impact
- 无破坏性变更（对外接口保持不变）
- OrderService 移除支付逻辑（职责分离）
- PaymentController 简化为路由转发
- 新增 payment/ 目录（模块化）
- 数据库新增 payment_records 表（幂等保护）

第四步：继续生成 design 和 tasks

Review proposal 之后，继续：

bash 复制代码

/opsx:continue

AI 会生成 design.md（架构设计、组件设计、依赖注入配置、文件结构、测试策略等）。

再继续：

bash 复制代码

/opsx:continue

AI 会生成 tasks.md（分阶段的任务清单）。

由于这些内容较长，这里不完整展示，结构和之前快速模式的例子类似。不同的是，迭代模式生成的工件会包含更多讨论中发现的细节，比如幂等性处理、回调统一框架等。

步骤 4：Review 工件

在让 AI 实施之前，先 review 这些工件。这一步很重要。

检查 proposal.md

Why 部分是否准确反映了问题？
What 部分的技术方案是否合理？
Impact 评估是否完整？

检查 design.md

架构设计是否符合项目规范？
文件结构是否合理？
测试策略是否充分？

检查 tasks.md

任务粒度是否合适？（每个任务 2-5 分钟）
是否有遗漏的任务？
时间估算是否合理？

如果发现问题，直接编辑文件修改。然后让 AI 更新其他工件。

步骤 5：实施任务

开始实施

bash 复制代码

/opsx:apply

AI 会开始执行 tasks.md 中的任务。

实施过程

vbnet 复制代码

AI: Working through tasks...
     
     ✓ 1.1 Created domain/payment/ directory
     ✓ 1.2 Defined PaymentStrategy interface
     ✓ 1.3 Defined Payment entity
     
     Current task: 2.2 实现 WeChatPayAdapter
     
     [AI writes code...]
     
     ✓ 2.2.1 Implemented pay() method
     ✓ 2.2.2 Implemented refund() method
     
     Moving to next phase...

中途用 explore 讨论细节

如果在实施过程中遇到问题，可以用 explore 讨论：

bash 复制代码

/opsx:explore WeChatPayAdapter 的 pay() 方法需要处理支付超时的场景吗？微信支付 SDK 会怎么处理？

AI 会帮你分析，但不会修改代码。讨论清楚后，继续实施。

中途调整

如果发现需要调整设计，可以：

复制代码

暂停，我需要调整一下 design.md

修改完之后：

bash 复制代码

/opsx:apply

继续实施。

步骤 6：验证实现

运行验证

bash 复制代码

/opsx:verify

AI 会检查：

Completeness：所有任务是否完成？
Correctness：代码是否符合规范？
Coherence：实现是否与 design 一致？

验证报告

yaml 复制代码

Verification Report:
     
✅ Completeness: All tasks completed
✅ Correctness: All tests passing
✅ Coherence: Implementation matches design
     
⚠️ Warnings:
- PaymentController.ts 缺少错误处理中间件
- 建议添加请求验证

Proceed to archive? (y/n)

如果有警告，修复之后再归档。

步骤 7：归档变更

执行归档

bash 复制代码

/opsx:archive

归档过程

vbnet 复制代码

AI: Archiving refactor-payment-module...
     
     ✓ Merged Delta Specs into openspec/specs/payment/spec.md
     ✓ Moved to openspec/changes/archive/2025-02-28-refactor-payment-module/
     Done! Ready for the next feature.

归档会做两件事：

把 Delta Specs 合并到主规范
把变更移到 archive/ 目录

验证扩展性：添加信用卡支付（快速模式示例）

重构的价值在于让后续开发更容易。现在架构清晰了，添加新支付方式可以用快速模式。

创建新变更

csharp 复制代码

/opsx:new add-credit-card-payment

生成所有工件

bash 复制代码

/opsx:ff

这次 AI 生成的 proposal 会很简洁：

markdown 复制代码

# Proposal: Add Credit Card Payment

## Why
用户反馈希望支持信用卡支付。

## What
基于现有的 PaymentStrategy 接口，实现 CreditCardAdapter。

## Capabilities
- 支持 Visa、MasterCard、American Express
- 支持 3D Secure 验证
- 支持退款

## Impact
- 新增 1 个文件：CreditCardAdapter.ts
- 更新 DI 配置
- 无破坏性变更

design.md 也会很简洁：

php 复制代码

# Design: Credit Card Payment

## Technical Approach
实现 PaymentStrategy 接口，复用现有架构。

## Implementation
```typescript
export class CreditCardAdapter implements PaymentStrategy {
  constructor(private readonly stripeClient: Stripe) {}
  
  async pay(order: Order, amount: number): Promise<PaymentResult> {
    // Stripe SDK 调用
  }
}

实施和归档

bash 复制代码

/opsx:apply
/opsx:archive

整个过程可能只需要 30 分钟。而重构前，可能要花半天。

这就是 OpenSpec 的威力：前期投入换来后期的效率飞跃。

OpenSpec 实际带来的价值

用了几个月下来，我觉得 OpenSpec 最有价值的是这三点：可追溯、可控、有积累。

可追溯

所有历史开发任务都能在 OpenSpec 中找到。你的开发动作、技术决策、设计思考，全部有记录。三个月后回来看，你还能想清楚"当时为什么这么改"。

可控

每个开发动作都在 Task 中有迹可循。各个阶段会检查 Task 执行情况，一步一步按计划推进。这让开发流程和交付物都更可控------不会出现 AI 改着改着就跑偏的情况。

有积累

这个是我觉得最有用的。

无论是 AI 还是人，刚接触项目的时候都很痛苦。试想一个场景：你面前是 20 万行以上的代码，AI 说"我觉得应该这样改"，你敢让它动吗？你确定它理解你的需求了吗？

OpenSpec 会仔细维护你的每一次研发，汇总成 Spec 知识库。这个知识库是你后续开发最稳定的基石------AI 读一遍 Spec，比你解释半小时都管用。所以无论多么小的功能，只要会对后续开发产生促进、影响的功能，都值得你用openspec积累到你的工程知识库zhong。

我踩过的坑

1. 不要 new + ff + apply 一条龙

刚开始用 OpenSpec 的时候，我喜欢 new + ff + apply 一把梭。结果发现陷入了无尽的"验证 → 给 AI 反馈 → 再验证"循环。

问题出在哪？

ff 生成的工件不一定靠谱。你直接 apply，AI 就开始写代码了。写着写着发现问题，你给它反馈，它改，你再验证，又发现问题......循环往复。

怎么解决？

最简单的办法：让 AI 自己循环。在 Cursor 里写 Rule，在 Claude Code 里写 CLAUDE.md，要求 AI 每完成一个任务先自测，再标记完成。

更好的办法：引入 TDD。后面文章会专门讲。

2. 把精力放在该放的地方

用了一段时间后，我发现 OpenSpec 的四个工件有不同的"受众"：

复制代码

人 ── proposal ── design ── specs ── task ── AI

Proposal 给人看：定义"为什么要做这件事"，是你和 AI 沟通的起点
Design 给人看：技术决策、架构设计，类似详细设计文档。我一般会在这里多花点时间
Specs 给 AI 看：格式固定、要求明确（比如必须用 SHALL 表达要求），人读起来有门槛，但 AI 读起来很顺畅
Task 给 AI 执行：不用怕写得太机械，重点是清晰、粒度合适

我的建议：先搞定 design，再让 AI 生成 specs。把人的精力放在人擅长的事上，让 AI 配合你。

总结

通过这个案例，我展示了 OpenSpec 的完整工作流：

初始化项目：配置 config.yaml，定义项目上下文
定义现状：创建 specs/ 描述当前状态
探索方案 ：用 /opsx:explore 讨论，聊透再动手
规划变更：选择快速模式或迭代模式，生成工件
实施验证：执行任务，中途可继续用 explore 讨论
归档记录：合并 specs，保留历史

OpenSpec 带来的价值：

减少沟通成本：工件先行，偏差早发现
降低返工率：明确规范，结果可预测
提升扩展性：架构清晰，新增容易
保留历史：归档完整，可追溯

如果你也在用 AI 编码助手，不妨试试 OpenSpec。

下一篇，我会对比 OpenSpec 和另一个流行的 AI 编码框架 Superpowers，看看它们的异同和适用场景。你会发现他们不是竞争、替代的关系，而是合作关系。

OpenSpec 实战：从需求到代码的完整工作流