openspec 的 使用

OpenSpec (opsx-*) 核心命令速查表

OpenSpec 是一个基于规格（Spec）和文档驱动的 AI 辅助开发工作流工具。以下命令通常在你的 AI 编程助手（如 Cursor、Claude 等）的对话或终端中触发，用于管理软件研发的完整生命周期。

💡 提示：带有 (Experimental) 标记的命令为实验性功能，流程可能仍在优化中。

---

🚀 阶段一：启动与探索 (Onboarding & Explore)

命令	英文原意	中文解释与使用场景
opsx-onboard	Guided onboarding - walk through a complete OpenSpec workflow cycle with narration	引导式入门。如果你是第一次使用，该命令会带你完整走一遍工作流，并配有解说。
opsx-explore	Enter explore mode - think through ideas, investigate problems, clarify requirements	进入探索模式。用于前期的头脑风暴、思考架构、排查问题或澄清模糊的需求。此时 AI 专注梳理思路，不写代码。

---

📝 阶段二：提案与规划 (Proposal & Planning)

命令	英文原意	中文解释与使用场景
opsx-new	Start a new change using the experimental artifact workflow (OPSX)	开启新变更。使用 OPSX 实验性工作流创建一个新的开发任务。
opsx-propose	Propose a new change - create it and generate all artifacts in one step	提出变更提案。一步到位地创建变更，并生成所需的所有规划文档（如需求、设计文档）。
opsx-ff	Create a change and generate all artifacts needed for implementation in one go	快速生成方案 (Fast Forward)。一键创建变更并直接生成实施所需的全套文档。适合需求非常明确的场景。

---

💻 阶段三：实施与调整 (Implementation & Update)

命令	英文原意	中文解释与使用场景
opsx-apply	Implement tasks from an OpenSpec change (Experimental)	实施任务。根据已确认的变更计划，开始让 AI 落地生成代码。
opsx-continue	Continue working on a change - create the next artifact (Experimental)	继续工作。接着之前的进度，创建下一个环节的工件或继续写代码。
opsx-update	Update a change - revise existing planning artifacts and keep them coherent (Experimental)	更新变更。开发中需求变更时使用，用于修订现有的规划文档，确保文档和代码不脱节。

---

✅ 阶段四：验收与归档 (Verification & Archiving)

命令	英文原意	中文解释与使用场景
opsx-verify	Verify implementation matches change artifacts before archiving	验证实施。在收尾前，校验代码实现是否完全符合当初设定的规范要求（类似 Code Review）。
opsx-sync	Sync delta specs from a change to main specs	同步规范。将本次变更产生的差异文档（delta specs），合并到项目的主干规范文档中。
opsx-archive	Archive a completed change in the experimental workflow	归档变更。将已经完成的单个变更任务进行归档，标志着该任务正式完结。
opsx-bulk-archive	Archive multiple completed changes at once	批量归档。一次性归档多个已完成的变更任务。

---

🛠️ 典型工作流示例

1. 接到新需求：opsx-explore (先讨论) -> opsx-new (确认要做)
2. 出设计方案：opsx-propose (生成需求/设计文档)
3. 开始写代码：opsx-apply (AI 开始写代码)
4. 开发中调整：opsx-update (修改需求) -> opsx-continue (接着写)
5. 提测验收：opsx-verify (检查代码)
6. 合并主干并归档：opsx-sync (同步文档) -> opsx-archive (任务闭环)