OpenSpec 安装与使用指南

OpenSpec 安装与使用指南文档定位OpenSpec 的安装、初始化、需求调整、技术方案调整、任务调整、实现推进和测试 bug 修复流程说明。1. OpenSpec 是什么OpenSpec 是一套面向 AI 编程代理的规格驱动开发工具。它把需求拆成结构化文件让 AI 和开发者围绕同一组文档推进先创建 change。写清楚proposal.md为什么做、做什么、不做什么。写清楚spec.md系统应该怎样表现如何验收。写清楚design.md技术方案、数据结构、兼容和风险。写清楚tasks.md测试、实现和验证步骤。实现时按tasks.md推进。完成前运行 OpenSpec 校验和项目测试。完成后同步规格或归档。与 Superpowers / Spec Kit 的关系OpenSpec 管变更档案proposal/spec/design/tasksSuperpowers 管 AI 执行纪律Spec Kit 管规格驱动项目模板。三者搭配方式见superpowers-guide.md§3。2. 安装与初始化2.1 安装全局安装 OpenSpec CLInpminstall-gfission-ai/openspeclatest openspec--version本次项目验证过的版本1.5.0如需关闭遥测exportOPENSPEC_TELEMETRY02.2 初始化项目在项目根目录执行openspec init.--toolscodex openspec doctor--jsonopenspec context--json初始化后通常会生成.codex/skills/openspec-*Codex 使用的 OpenSpec 工作流技能。openspec/config.yaml项目上下文、约束、验证命令和目录规则。openspec/changes/每个需求变更的工作目录。初始化后建议执行openspec validate--all--jsongitstatus--short--branch3. 目录结构一个标准 change 的目录结构openspec/changes/change-name/ ├── .openspec.yaml ├── proposal.md ├── design.md ├── tasks.md └── specs/ └── capability-name/ └── spec.md文件作用proposal.md变更提案说明背景、范围、非目标和影响design.md技术设计说明方案、数据、兼容、迁移和风险tasks.md任务清单说明测试、实现、验证和收尾specs/capability-name/spec.md能力域规格说明说明系统应该怎样表现spec.md不和design.md、tasks.md放同级是因为一个 change 可能影响多个能力域。OpenSpec 用specs/capability-name/spec.md区分能力域方便后续同步主规格。4. 常用命令openspec--version# 版本openspec init.--toolscodex# 初始化项目openspec doctor--json# 环境检查openspec context--json# 查看项目上下文openspec new changechange-name# 创建 changeopenspec instructions proposal--changechange-name--json# 读取 proposal 指令openspec instructions spec--changechange-name--json# 读取 spec 指令openspec instructions design--changechange-name--json# 读取 design 指令openspec instructions tasks--changechange-name--json# 读取 tasks 指令openspec instructions apply--changechange-name--json# 读取 apply 指令openspec validate--all--json# 全量校验openspec status--changechange-name--json# 查看 change 状态openspec archivechange-name--json# 归档openspec archivechange-name--skip-specs--json# 归档不同步主规格5. 创建 Changeopenspec new changechange-name示例openspec new change evan-openspec-sales-policy-iteration命名建议使用小写英文、数字和短横线。名称表达业务动作。与分支名、任务号、文档前缀保持一致。6. 写 Proposal / Spec / Design / Tasks推荐顺序proposal.md → spec.md → design.md → tasks.md6.1 proposal.md重点回答为什么做。本期做什么。本期不做什么。影响哪些模块、数据、接口、页面、测试。6.2 spec.md重点回答系统应该具备什么能力。用户在什么场景下操作。系统应该给出什么结果。哪些边界、异常、权限、历史数据要覆盖。6.3 design.md重点回答准备怎么实现。数据表和模型如何调整。前后端职责如何划分。历史数据如何兼容。风险和回滚如何处理。6.4 tasks.md重点回答先写哪些失败测试。再改哪些文件。如何验证每一步。完成后跑哪些命令。7. 如何调整需求需求调整指业务范围、验收口径或非目标变化。不要直接改代码先改 OpenSpec。操作顺序收到需求调整 → 判断是新增、删除还是修改需求 → 更新 proposal.md 的 What Changes / Non-Goals / Impact → 更新 specs/capability/spec.md 的 Requirement / Scenario → 判断 design.md 是否需要调整 → 判断 tasks.md 是否需要调整 → 运行 openspec validate --all --json → 再进入实现提示词需求有调整说明调整内容。 请先判断影响 proposal、spec、design、tasks 哪些文件。 然后更新对应 OpenSpec 文件全部使用中文。 更新后列出变更摘要和需要重新执行的验证命令。 不要先改代码。8. 如何调整技术方案技术方案调整指业务验收口径不变但实现方式发生变化。操作顺序发现技术方案需要调整 → 对照 spec.md 判断业务行为是否变化 → 业务行为不变更新 design.md → 业务行为变化先更新 spec.md再更新 design.md → 更新 tasks.md 的实现步骤、测试步骤和验证命令 → 如涉及数据库更新 SQL 和迁移说明 → 运行 openspec validate --all --json提示词技术方案需要调整说明原方案和新方案。 请先判断 spec 是否受影响。 如果业务验收口径不变只更新 design 和 tasks。 如果验收口径变化先更新 spec再更新 design 和 tasks。 更新后给出风险、迁移影响和需要重跑的测试。9. 如何调整 TasksOpenSpec 中的 plan 主要体现在tasks.md。如果只是执行顺序、任务拆分、测试步骤或验证命令变化可以只改tasks.md。操作顺序发现 tasks 不合理 → 判断是否影响 spec → 判断是否影响 design → 只影响执行方式时修改 tasks.md → 新增、删除或重排任务 → 调整测试和验证命令 → 运行 openspec status --change change-name --json提示词tasks 需要调整说明问题。 请先判断是否影响 spec 或 design。 如果不影响只修改 tasks.md。 请把任务拆得更可执行补上 TDD 步骤、验证命令和预期结果。10. 实现阶段进入实现前读取 apply 指令openspec instructions apply--changechange-name--json实现原则先读proposal.md、spec.md、design.md、tasks.md。按tasks.md顺序推进。能写测试的地方先写失败测试。每完成一个阶段就更新任务勾选。不把本期明确不做的内容带进实现。完成前重新运行测试和 OpenSpec 校验。11. 测试提 Bug 处理测试提 bug 后不要直接修代码。先分流11.1 Bug 类型判断Bug 类型判断标准OpenSpec 操作实现缺陷spec.md已写清楚但代码没做到不改 spec在tasks.md增加 bug 修复任务和回归测试任务需求遗漏测试提出的是 spec 没写的新行为先改proposal.md和spec.md再改design.md、tasks.md技术方案偏差业务口径没变但实现方案不合理改design.md和tasks.md如验收口径变化再改spec.md测试用例问题代码符合 spec但测试期望错了不改业务实现修测试并记录依据11.2 未归档 Change 的处理流程收到测试 bug → 复现 bug → 对照 spec.md 判断是否已有验收场景 → 对照 design.md 判断是否是方案问题 → 更新 tasks.md增加测试反馈 bug 修复任务 → 如需求或方案变化同步更新 proposal/spec/design → 先写失败测试 → 修复实现 → 跑回归测试 → 运行 openspec validate --all --json11.3 已归档 Change 的处理流程openspec new changebugfix-change-name然后为 bugfix 单独补proposal.md、spec.md、design.md、tasks.md。11.4 推荐提示词测试提了 bugbug 描述。 请先对照当前 OpenSpec spec 判断它属于实现缺陷、需求遗漏、技术方案偏差还是测试用例问题。 如果是实现缺陷不要改 spec只在 tasks.md 增加 bug 修复和回归测试任务。 如果是需求遗漏或方案变化请先更新对应 OpenSpec 文件再进入实现。12. 归档实现完成后归档openspec archivechange-name--json如果不需要更新主规格openspec archivechange-name--skip-specs--json13. Review 重点文件Review 关注点proposal.md范围、非目标、影响面是否完整spec.md每个场景是否能验收是否覆盖异常和边界design.md数据、接口、权限、兼容、风险和回滚是否清楚tasks.md是否可执行是否有测试验证命令是否真实14. 参考链接OpenSpec npm 包https://www.npmjs.com/package/fission-ai/openspecOpenSpec GitHub CLI 文档https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.mdSpec Kit GitHubhttps://github.com/github/spec-kitSpec Kit 安装文档https://github.github.com/spec-kit/installation.html