OpenSpec 规范驱动开发助手
OpenSpec 是规范驱动的 AI 编程框架。核心理念：在编写代码前，与 AI 就需求达成一致。
-
流动而非僵化 - 随时处理任何工件，无阶段门控
-
迭代而非瀑布 - 边构建边完善理解
-
简单而非复杂 - 最小化设置和仪式
-
棕地优先 - Delta 方式修改现有系统
斜杠命令
命令 功能
/opsx:explore
探索想法、调查问题、明确需求
/opsx:new
启动新变更
/opsx:continue
创建下一个就绪工件
/opsx:ff
快进 - 一次创建所有规划工件
/opsx:apply
实施任务，按需更新工件
/opsx:verify
验证实现的完整性、正确性、一致性
/opsx:sync
同步 delta specs 到主规范（可选）
/opsx:archive
归档完成的变更
/opsx:bulk-archive
批量归档多个变更
/opsx:onboard
交互式教程
工作流模式
快速功能流（需求明确时）：
/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive
探索式流程（需求不明确时）：
/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply
增量式流程（需要更多控制时）：
/opsx:new → /opsx:continue (重复) → /opsx:apply → /opsx:archive
工件系统（默认 Schema: spec-driven）
工件依赖链：
proposal → specs → design → tasks → implement
工件类型：
-
proposal.md - 变更提案（Why/What/Impact）
-
specs/ - Delta 规范（ADDED/MODIFIED/REMOVED）→ 详见 references/delta-specs-format.md
-
design.md - 技术设计
-
tasks.md - 任务清单（带复选框）→ 编写规范详见 references/tasks-writing-guide.md
工件状态：BLOCKED （缺少依赖）→ READY （依赖完成）→ DONE （文件存在）
目录结构
openspec/ ├── config.yaml # 项目配置（可选） ├── specs/ # 当前系统行为（事实来源） ├── changes/ # 活跃变更 │ └── add-feature/ │ ├── .openspec.yaml │ ├── proposal.md │ ├── specs/ │ ├── design.md │ └── tasks.md ├── archive/ # 已归档变更 └── schemas/ # 自定义工作流（可选）
tasks.md 核心要求
详细规范请读 references/tasks-writing-guide.md
两条最重要的原则：
-
文件级粒度：每个任务条目必须包含 [操作类型] 文件路径 - 具体改动描述 ，禁止写无法定位文件的模糊任务
-
试点分层：任务总数 ≥ 5 时，必须先划分「试点批次（Pilot Batch）」验证方向后，再推进「主体任务」
格式速记：
- [修改]
packages/foo/src/bar.ts- 增加 processItem() 方法，实现单条数据处理
更新与迭代决策
相同意图？ → YES: 更新现有变更 / NO: 启动新变更
50% 重叠？ → YES: 更新现有变更 / NO: 启动新变更 原始能完成？→ NO: 更新现有变更 / YES: 启动新变更
验证
/opsx:verify 检查三个维度：
-
Completeness - 所有任务完成，需求已实现
-
Correctness - 匹配规范意图，处理边界情况
-
Coherence - 设计决策反映在代码中
执行长任务的注意事项
-
文件级粒度执行 - 每次只修改一个文件，立即标记完成
-
先试点再推进 - 先完成「试点批次」，验证通过后继续「主体任务」
-
及时更新任务文件 - 完成任务后立即更新 tasks.md 的复选框
-
并行子代理 - 启动多个子代理分模块完成任务
-
中文回复 - 始终用中文回复用户
-
重读任务要求 - 上下文合并后重新阅读规范
-
连续执行 - 一次性完成 tasks.md 全部任务
-
禁止批处理脚本 - 使用具体的文件编辑，不用脚本批量修改
-
主从代理调度：主代理阅读全部任务、分配子代理、监听反馈；子代理严格按要求完成任务
常用 CLI 命令
openspec init # 初始化项目 openspec list # 列出活跃变更 openspec status --change <name> # 查看工件状态 openspec validate <name> --strict # 严格格式校验 openspec archive <name> --yes # 归档变更
配置、自定义 Schema、故障排除详见 references/configuration.md
参考文件
文件 内容
references/tasks-writing-guide.md
tasks.md 编写规范（文件级粒度 + 试点分层详解）
references/delta-specs-format.md
Delta Specs 完整格式规范
references/configuration.md
config.yaml 配置、自定义 Schema、故障排除
外部参考资源