引言
在 AI Coding 场景中，直接从需求描述进入代码实现，容易出现范围失控、设计偏移、上下文丢失和任务状态难以追踪等问题。OpenSpec 通过规格驱动开发（Spec-Driven Development）方式，将需求探索、方案设计、任务实施和最终归档拆分为独立阶段，使开发过程具备更清晰的边界和可追踪性。
在 OpenCode 中，OpenSpec 常见核心命令包括：
/opsx-explore
/opsx-propose
/opsx-apply
/opsx-update
/opsx-sync
/opsx-archive
日常开发最常用的主流程可以概括为：
Explore
↓
Propose
↓
Review
↓
Apply
↓
Archive
Update 与 Sync 主要用于开发过程中的方案调整和规格同步。
一、整体工作流
OpenSpec 的核心思路并不是增加更多流程，而是将“需求、设计、实现”拆开处理。
需求尚未明确
↓
Explore
↓
需求和方案逐步收敛
↓
Propose
↓
生成正式规格与任务
↓
Review
↓
确认范围、设计和任务
↓
Apply
↓
实现代码并更新任务进度
↓
Archive
↓
正式规格进入 openspec/specs/
这种方式适合中大型功能、长期维护项目、多人协作项目，以及需要 Agent 持续执行复杂开发任务的场景。
二、/opsx-explore：需求探索
Explore 用于需求尚未完全明确的阶段。
主要职责包括：
调查现有代码结构
分析需求目标
识别约束条件
比较技术方案
梳理边界场景
发现潜在风险
补充缺失信息
典型场景：
新增用户认证模块
认证方式、会话机制、安全策略、权限边界等内容尚未确定时，可以先执行：
/opsx-explore
Explore 阶段重点解决的问题通常包括：
认证方式
├── Session
├── JWT
└── OAuth
会话存储
├── PostgreSQL
├── Redis
└── 其他存储
安全策略
├── 密码规则
├── 登录失败限制
├── Session 过期
└── 多设备登录
Explore 的主要价值在于降低错误方案直接进入实现阶段的概率。
适用场景
需求边界不明确
技术方案存在多个选择
涉及重要架构决策
现有代码结构尚未调查
需要先分析潜在风险
对于修改文案、增加简单字段、修复明确错误等小型任务，通常不需要完整 Explore 流程。
三、/opsx-propose：生成正式变更方案
Propose 用于将已经相对明确的需求转化为正式 OpenSpec Change。
示例：
/opsx-propose add-authentication
生成结构通常类似：
openspec/
└── changes/
└── add-authentication/
├── proposal.md
├── specs/
├── design.md
└── tasks.md
proposal.md
用于记录变更背景、目标和范围。
重点内容包括：
为什么需要变更
需要解决什么问题
变更范围包含哪些内容
变更范围不包含哪些内容
specs/
用于记录行为级需求和验收场景。
示例：
### Requirement: Account Lockout
系统 SHALL 在连续五次认证失败后锁定账号。
#### Scenario: Fifth failed login
- GIVEN 已发生四次连续认证失败
- WHEN 第五次认证失败
- THEN 账号进入锁定状态
- AND 十分钟内拒绝新的认证请求
design.md
用于记录技术方案，例如：
模块划分
数据结构
接口设计
依赖关系
技术选型
兼容策略
风险与权衡
tasks.md
用于记录可执行任务和实施进度：
- [ ] 创建数据库结构
- [ ] 实现认证服务
- [ ] 实现登录接口
- [ ] 实现 Session 管理
- [ ] 增加集成测试
四、Review：正式实现前的审查
Propose 完成后，不建议立即进入 Apply。
正式实现前应重点检查以下内容：
proposal.md
├── 目标是否正确
├── 范围是否合理
└── 是否包含不必要功能
specs/
├── 行为是否明确
├── 边界场景是否完整
└── 验收条件是否可测试
design.md
├── 架构是否合理
├── 技术选型是否必要
└── 是否存在过度设计
tasks.md
├── 任务粒度是否合理
├── 是否存在遗漏
└── 是否包含测试与验证
规格驱动开发的重要价值之一，就是将需求错误和设计错误尽可能暴露在代码实现之前。
五、/opsx-apply：开始实施
Apply 用于按照已经确认的规格和任务真正修改代码。
示例：
/opsx-apply add-authentication
执行过程可以概括为：
读取 proposal
↓
读取 specs
↓
读取 design
↓
读取 tasks
↓
逐项实现
↓
执行验证
↓
更新 tasks 状态
任务进度通常直接记录在 tasks.md 中：
- [x] 创建数据库结构
- [x] 实现认证服务
- [x] 实现登录接口
- [ ] 实现 Session 管理
- [ ] 增加集成测试
这种方式使任务进度不依赖单次聊天上下文。
六、任务中断后的恢复
长时间任务可能因为上下文耗尽、终端关闭、网络异常、API 失败或主动暂停而中断。
恢复时通常无需重新执行 Explore 或 Propose。
重新进入项目后执行：
/opsx-apply <change-name>
例如：
/opsx-apply add-authentication
恢复执行前，建议先检查：
tasks.md
git diff
当前代码状态
测试结果
原因在于任务可能已经完成部分代码，但对应 checkbox 尚未更新。
推荐恢复流程：
读取未完成任务
↓
检查已有实现
↓
确认当前完成度
↓
补齐剩余部分
↓
运行测试或验证
↓
更新任务状态
七、/opsx-update：修改已有方案
Update 用于修改已经存在的规划文件。
典型场景：
原方案：
JWT Authentication
调整后：
Server-side Session
此时可以执行：
/opsx-update add-authentication
Update 会围绕已有的：
proposal.md
specs/
design.md
tasks.md
进行修改，并处理多个规划文件之间的关联影响。
例如：
design.md
JWT → Session
可能同时影响：
specs/
tasks.md
proposal.md
Update 的重点是“修改已经明确的方案”。
Update 与 Explore 的区别
Explore
= 修改方向尚未确定
= 重点在调查、比较、分析和澄清
Update
= 修改方向已经明确
= 重点在修订现有规划并保持一致
可以使用以下判断原则：
尚未确定应该如何修改
→ Explore
已经明确需要修改什么
→ Update
重大方向变化适合先 Explore，再 Update。
八、/opsx-sync：提前同步正式规格
正式规格通常位于：
openspec/specs/
正在进行的 Change 可能包含增量规格：
openspec/changes/add-authentication/specs/
执行：
/opsx-sync add-authentication
可以将当前 Change 的增量规格同步到正式规格，但不会归档当前 Change。
流程如下：
Change Delta Specs
↓
Sync
↓
openspec/specs/
↓
Change 继续保持 Active
Sync 常用于以下场景：
Change 开发周期较长
其他并行 Change 需要依赖当前规格
需要提前查看合并后的正式规格
普通开发流程通常不需要频繁手动执行 Sync。
九、/opsx-archive：完成归档
功能实现并完成验证后，可以执行：
/opsx-archive add-authentication
Archive 主要完成两项工作：
增量规格
↓
合并到正式 specs
Active Change
↓
移动到 archive
归档后的结构可能类似：
openspec/
├── specs/
│ └── authentication/
│ └── spec.md
│
└── changes/
└── archive/
└── add-authentication/
openspec/specs/ 应逐渐成为系统当前能力的正式描述，而不是一次性生成的未来蓝图。
十、日常推荐流程
大多数功能开发只需要记住以下主线：
Explore
↓
Propose
↓
Review
↓
Apply
↓
Archive
对应命令：
/opsx-explore
/opsx-propose
/opsx-apply
/opsx-archive
当方案需要调整时，可以插入 Update：
Explore
↓
Propose
↓
Review
↓
Update
↓
Apply
↓
Archive
当正式规格需要提前同步时，可以使用 Sync。
十一、全新项目的启动方式
全新项目不适合一次创建覆盖整个系统的巨大 Change。
推荐方式：
产品方向探索
↓
确定 MVP
↓
拆分多个 Change
↓
逐个实施和归档
例如 SaaS 项目可以拆分为：
01 bootstrap-project-foundation
02 add-authentication
03 add-organizations
04 add-project-management
05 add-task-management
06 add-comments
07 add-notifications
每个 Change 独立执行：
Explore
→ Propose
→ Review
→ Apply
→ Archive
第一个 Change：Foundation
第一个 Change 通常只处理基础设施：
项目目录结构
TypeScript 配置
数据库连接
ORM
Migration
Logging
Error Handling
Lint
Formatting
Test Infrastructure
CI
业务功能建议拆分到后续 Change。
不推荐：
create-entire-saas-platform
更推荐：
bootstrap-foundation
add-authentication
add-organizations
add-projects
add-task-management
一个 Change 最好对应一个能够独立描述、实现、测试和验收的能力增量。
十二、OpenSpec 与 OMO-Slim 的协作关系
OpenSpec 与 OMO-Slim 解决的是不同层级的问题。
推荐职责划分：
OpenSpec
负责 WHAT
├── 需求
├── Spec
├── Design
├── Tasks
└── 验收边界
OMO-Slim
负责 HOW
├── Agent 调度
├── 代码调查
├── 并行任务
├── 具体实现
└── Review
组合后的执行结构：
OpenSpec Change
↓
tasks.md
↓
OMO Orchestrator
│
├── Explorer
├── Librarian
├── Oracle
├── Fixer
└── Designer
↓
实现与验证
↓
OpenSpec Archive
执行 /opsx-apply 后，OMO-Slim Orchestrator 仍可继续运行。
更合理的关系是：
OpenSpec
定义顶层任务与边界
↓
OMO Orchestrator
根据任务选择执行 Agent
↓
专业 Agent 完成实现
十三、Deepwork 的使用位置
OMO-Slim 的 Deepwork 更适合以下任务：
大型重构
跨大量文件的功能开发
多阶段实施
高风险架构修改
长期复杂任务
在 OpenSpec 场景中，推荐关系如下：
OpenSpec
定义需求、规格和顶层 Tasks
↓
Apply
↓
OMO Deepwork
拆解复杂实施过程
↓
Subagents
↓
验证
不建议让 Deepwork 重新生成一套与 OpenSpec Tasks 冲突的顶层计划。
合理原则：
OpenSpec 决定做什么
OMO-Slim 决定如何完成
Deepwork 管理复杂实施过程
十四、模型资源分配建议
不同阶段对模型能力的要求不同。
| 阶段 | 模型能力建议 | 主要原因 |
|---|---|---|
| Explore | 高 | 需求分析、架构判断、方案比较 |
| Propose | 高 | 规格与设计质量直接影响后续实现 |
| Review | 高 | 需要发现遗漏、冲突与风险 |
| Apply | 中高 | 已有 Spec、Design、Tasks 作为约束 |
| Explorer Agent | 中低或快速模型 | 主要负责检索与定位 |
| Librarian Agent | 中低或快速模型 | 主要负责文档检索 |
| Oracle Agent | 高 | 复杂架构分析与审查 |
| Fixer Agent | 中高 | 主要负责具体编码实现 |
高能力模型更适合优先投入需求、设计与审查阶段。
错误需求进入实现阶段后，即使代码质量较高，也可能产生较大的返工成本。
十五、常见工作流示例
场景一：新增普通功能
/opsx-explore
↓
需求澄清
↓
/opsx-propose
↓
Review
↓
/opsx-apply
↓
测试
↓
/opsx-archive
场景二：方案已经明确
/opsx-propose
↓
Review
↓
/opsx-apply
↓
/opsx-archive
Explore 并非所有任务的强制步骤。
场景三：开发过程中发现设计需要修改
Apply
↓
暂停实现
↓
/opsx-update
↓
修订 Spec / Design / Tasks
↓
Review
↓
/opsx-apply
场景四：修改方向尚未确定
Apply
↓
发现原方案存在问题
↓
/opsx-explore
↓
比较新方案
↓
确定方向
↓
/opsx-update
↓
/opsx-apply
场景五：任务执行过程中断
任务中断
↓
重新进入项目
↓
读取 tasks.md
↓
检查 git diff
↓
/opsx-apply <change>
↓
继续未完成任务
十六、核心命令速查表
| 命令 | 作用 | 是否改业务代码 | 常见使用阶段 |
|---|---|---|---|
/opsx-explore |
探索需求、调查代码、比较方案 | 否 | 需求尚不明确 |
/opsx-propose |
创建 Change 并生成规划产物 | 否 | 方案基本明确 |
/opsx-apply |
按 Tasks 实现代码 | 是 | 实施阶段 |
/opsx-update |
修订已有规划产物 | 否 | 方案发生调整 |
/opsx-sync |
将增量规格同步到正式 Specs | 否 | 提前同步规格 |
/opsx-archive |
同步规格并归档 Change | 否 | 开发完成 |
最常见主线：
Explore → Propose → Review → Apply → Archive
十七、实践原则
1. 避免一次创建过大的 Change
一个 Change 最好对应一个独立、可测试、可验收的能力增量。
2. Apply 前审查 Design 与 Tasks
重点检查：
边界
依赖
数据模型
兼容性
错误处理
安全
测试
迁移方案
3. 中断恢复时先检查实际代码状态
tasks.md 是重要进度来源，但 checkbox 更新可能晚于代码实际修改。
恢复执行前应先确认：
Git Diff
已有实现
测试状态
未完成任务
4. 规格错误时暂停实现
发现需求或设计错误后，应先修正规格，再继续编码。
5. 正式 Specs 记录已实现事实
未来规划和尚未完成的功能更适合保留在 Active Change 中。
结语
OpenSpec 的核心价值并不在于增加命令数量，而在于建立清晰的规格驱动闭环：
需求探索
↓
方案固化
↓
人工审查
↓
任务实施
↓
验证
↓
归档
对应 OpenSpec：
Explore
↓
Propose
↓
Review
↓
Apply
↓
Archive
配合 OMO-Slim 后，可以形成更加清晰的分层结构：
OpenSpec
= 需求、规格、设计、任务边界
OMO-Slim
= 多 Agent 调度与实施
Deepwork
= 大型复杂任务的阶段化执行
这种模式特别适合中大型项目、长期维护项目，以及需要多个 Agent 协同完成复杂开发任务的工程场景。
参考资料
- OpenSpec Documentation: https://openspec.dev/
- OpenSpec GitHub: https://github.com/Fission-AI/OpenSpec
- OMO-Slim GitHub: https://github.com/krzjac/omo