ruan-cat 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）」验证方向后，再推进「主体任务」
- 执行中动态补全：
/opsx:apply、/opsx:verify或人工复核发现任务遗漏时，先回写当前 change 的tasks.md，再继续实现或验收
格式速记：
- [ ] [修改] `packages/foo/src/bar.ts` - 增加 processItem() 方法，实现单条数据处理
执行中动态补全
当 /opsx:apply、/opsx:verify 或人工复核发现当前 change 存在任务遗漏时，必须先把遗漏项写回 openspec/changes/<change>/tasks.md，再继续实现或验收。tasks.md 是唯一可执行任务源，不得只把遗漏写在聊天 checklist、进度报告或子代理反馈里。
补全任务必须保持 OpenSpec checkbox 格式：
- [ ] [操作类型] 路径 - 具体动作与验收标准
发现缺口但未写回 tasks.md 时，不得声明相关实现、验收或 change 已完成。任务补全后必须运行：
openspec validate <change-name> --strict
更新与迭代决策
相同意图？ → YES: 更新现有变更 / NO: 启动新变更
>50% 重叠？ → YES: 更新现有变更 / NO: 启动新变更
原始能完成？→ NO: 更新现有变更 / YES: 启动新变更
验证
/opsx:verify 检查三个维度：
- Completeness - 所有任务完成，需求已实现
- Correctness - 匹配规范意图，处理边界情况
- Coherence - 设计决策反映在代码中
执行长任务的注意事项
- 文件级粒度执行 - 每次只修改一个文件，立即标记完成
- 先试点再推进 - 先完成「试点批次」，验证通过后继续「主体任务」
- 及时更新任务文件 - 完成任务后立即更新
tasks.md的复选框；发现遗漏任务时先补写tasks.md并 strict validate - 并行子代理 - 启动多个子代理分模块完成任务
- 中文回复 - 始终用中文回复用户
- 重读任务要求 - 上下文合并后重新阅读规范
- 连续执行 - 一次性完成
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、故障排除 |