【AI-SSD】openspec_v1.1使用心得
这是一份 OpenSpec v1.1 使用指南。该文档着重于“规格驱动开发（Spec-Driven Development）”的流程，涵盖了从安装、交互流程到进阶使用的全方位解析。
1. 项目简介
OpenSpec 是一个为 AI 辅助编程设计的规范管理工具。它的核心理念是 “Agree before you build”（先对齐，再构建）。通过结构化的 Markdown 文档管理变更提案（Proposals）和项目规范（Specs），确保人类意图与 AI 实现的高度一致，防止代码逻辑在迭代中发生偏离。
2. 快速开始 (How to Use)
2.1 前提条件
在开始之前，请确保您的开发环境满足以下要求 ：
- Node.js: 版本需 ≥20.19.0
- 包管理器: npm
2.2 安装与验证
使用 npm 全局安装 OpenSpec 的最新版本 ：
npminstall -g @fission-ai/openspec@latest 安装完成后，验证版本以确保安装成功 ：
$ openspec --version 1.1.1 2.3 初始化项目
进入您的项目根目录，运行初始化命令 ：
# 会让选择对应 ai-agent openspec init
会引导选择 AI 工具（如 Claude Code），并生成以下核心目录结构 ：
. ├── changes # 存放所有活跃的变更提案（Proposals）及任务列表（Tasks）。 │ └── archive │ └── 2026-02-03-integrate-center-service │ ├── design.md │ ├── proposal.md │ ├── specs │ │ ├── ogin │ │ │ └── spec.md │ │ ├── center-query │ │ │ └── spec.md │ │ └── service-type-management │ │ └── spec.md │ └── tasks.md ├── config.yaml #向openspec进行上下文约定和技术栈等声明 └── specs ├── login │ └── spec.md ├── center-query │ └── spec.md └── service-type-management └── spec.md 3. 核心命令详解 (Command Reference)
🚀 启动与规划 (Planning)
| 命令 | 描述 | 适用场景 |
|---|---|---|
/openspec-new-change | 发起新变更启动结构化的分步工作流。 | 适用于创建新功能或复杂修复，需要一步步梳理需求时。 |
/openspec-ff-change | 快速变更 (Fast-Forward) 跳过中间步骤，一次性生成所有规划工件。 | 适用于需求非常明确，无需分步确认的场景。 |
/openspec-explore | 探索模式作为思维伙伴探讨想法、排查问题或厘清需求。 | 在正式变更前进行头脑风暴，或在变更过程中理清思路。 |
/openspec-continue-change | 继续推进创建下一个阶段的工件（如 Proposal -> Specs）。 | 当你确认当前文档无误，希望 AI 进入下一阶段时使用。 |
🔨 实施与验证 (Implementation)
| 命令 | 描述 | 适用场景 |
|---|---|---|
/openspec-apply-change | 实施变更依据 tasks.md 开始编写代码。 | 规划完成，开始让 AI 动手写代码。 |
/openspec-verify-change | 验证变更验证代码实现是否匹配变更工件的要求。 | v1.1 新增。在归档前，确保实现是完整、正确且连贯的。 |
📦 归档与同步 (Finalization)
| 命令 | 描述 | 适用场景 |
|---|---|---|
/openspec-archive-change | 归档变更完成开发，将变更合并到主规范并清理工作区。 | 任务全部完成并通过测试后。 |
/openspec-bulk-archive-change | 批量归档一次性归档多个已完成的变更。 | 当同时并行处理多个任务时。 |
/openspec-sync-specs | 同步规范仅同步 Delta Specs 到主规范，不归档变更。 | 想要更新主文档但暂时保留变更工作区时。 |
🎓 辅助命令
| 命令 | 描述 |
|---|---|
/openspec-onboard | 新手引导。在真实代码库中通过旁白引导你走完一个完整流程。 |
4. 核心工作流 (Core Workflow)
OpenSpec v1.1 的核心流程围绕 “提案 (Proposal) -> 应用 (Apply) -> 归档 (Archive)” 展开。
步骤 1: 提出需求 (Scaffold)
当有新功能或 Bug 修复时，通过 AI 指令创建提案。OpenSpec 会在 changes/ 目录下生成结构化文档 。
- 交互指令: /openspec-new-change <需求描述>
示例:
/openspec-new-change 对接呼叫中心创建用户登录功能的提案
⏺ Write(openspec/changes/integrate-center-service/proposal.md) ⎿ Wrote 39 lines to openspec/changes/integrate-center-service/proposal.md ## Why 当前系统……支持企业订阅不同服务类型，并提供通话查询接口。 ## What Changes - 在企业表中新增字段存储服务类型配置，支持数据库持久化 … +29 lines (ctrl+o to expand) ⏺ Bash(openspec status --change "integrate-center-service") ⎿ Change: integrate-center-service Schema: spec-driven Progress: 1/4 artifacts complete … +6 lines (ctrl+o to expand) ⏺ 完美！proposal已创建成功。现在让我为您总结一下已完成的工作和下一步计划： ✅ 已完成 成功创建了OpenSpec变更 integrate-center-service，包含： Proposal核心内容 Why（为什么） #### ❯ /openspec-continue-change 1.不要修改企业表，生成一个企业绑定业务服务表；创建企业的对应新建一条数据…… ⏺ I'll help you continue working on your OpenSpec change. Let me first check what changes are available. # design ⏺ 好的，让我创建 design 工件。首先获取指令： ⏺ Bash(openspec instructions design --change "integrate-center-service" --json) ⎿ Running… 步骤 2: 验证与审查 (Validate)
AI 会生成 proposal.md 和 tasks.md。开发者可以使用 CLI 命令查看详情，并验证规范格式是否合法 。
- CLI 命令:
openspec validate <change-name> --strict - 或者直接在claude中使用 integrate-center-service
❯ /openspec-verify-change integrate-center-service ⏺ 我将验证 integrate-center-service 变更的实现情况。 Bash(openspec status --change "integrate-center-service" --json)步骤 3: 应用变更 (Apply)
确认提案无误后，指示 AI 开始编写代码。AI 会读取 tasks.md 并逐项执行 。
- 交互指令:
/openspec:apply <change-name>
❯ /opsx:apply ⏺ 好的，让我开始实施任务。 使用变更：integrate-center-service 如需使用其他变更，请运行 /opsx:apply <变更名> ⏺ Bash(openspec instructions apply --change "integrate-center-service" --json) ⎿ {"changeName":"integrate-center-service", "changeDir":"……/openspec/changes/integrate-center-service", … +173 lines (ctrl+o to expand) ⏺ 实施变更：integrate-center-service (schema: spec-driven) 进度：0/31 任务完成 让我开始实施任务。 --- 任务 1/31：创建企业绑定业务服务表 DDL 脚本 步骤 4: 归档 (Archive)
开发完成并测试通过后，将变更合并到主规范（Specs）中，并清理工作区 。
- 交互指令:
/openspec:archive <change-name> - 底层行为: 系统会自动将
changes/下的内容合并进specs/目录，并移动到archive/目录。
❯ /opsx:archive ⏺ 我将帮助您归档一个已完成的变更。 首先让我查看可用的变更列表。 ⏺ Bash(openspec list --json) ⎿ {"changes":[{ … +8 lines (ctrl+o to expand) ⏺ 我找到了一个进行中的变更。让我检查其详细状态。 ⏺ Bash(openspec status --change "integrate-center-service" --json) ⏺ ⎿ Running… { ✢ Churn"changeName":"integrate-center-service", "schemaName":"spec-driven", ─────… +28 lines (ctrl+o to expand)──────────────────────────────────────────────────── ⏺ 现在让我检查 main specs 目录的状态,然后创建这三个新的 spec 文件。 ⏺ Read 1file(ctrl+o to expand) ⏺ Main specs 目录为空。我将创建三个新的 capability spec 文件。根据依赖关系,按以下顺序创建: 1. service-type-management (基础能力)2. login (依赖 service-type-management)3. center-query (依赖 agent-login) ⏺ Bash(mkdir -p openspec/specs/service-type-management openspec/specs/login openspec/specs/center-query) ⏺ 归档完成 (with warnings) 变更: integrate-center-service 工作流模式: spec-driven 归档位置: openspec/changes/archive/2026-02-03-integrate-center-service/ Specs 同步状态: ✓ 已同步到 main specs --- 警告: - 归档时包含 9 个未完成任务 (测试和生产部署相关) - 单元测试、集成测试、性能测试、并发测试 - 生产环境 DDL 执行、代码部署、生产验证 归档内容: - ✅ 所有工件已完成 (proposal, design, specs, tasks) - ✅ Delta specs 已同步到 main specs: 探索模式(openspec-explore+ff)
❯ /opsx:explore # 讨论背景资料 1. jst模块：@SessionStateController中/event 作为核心业务事件处理入口；里面记录了时间状态变更，由test-02模块通过feign 接口TestClient 调用； 2. vcc-test模块：@TestSwitchController中/pVideo 和 /Video 以及 /hangUp 是业务中和前端交互主叫接口，内部也涉及到状态变更； 3. 状态变更调整涉及到redis缓存调整；socket消息发送；在StateMachineService 和第2点中接口都有相关操作； # 讨论诉求 基础：现在需要进行日志优化：能够通过一个特殊标识：sessionId查询到所有相关的日志，方便排查问题； 1. 在基础上新增一个关键字标识：能够查询出核心日志； 2. 在基础上新增一个关键字标识：能够查询出所有socket日志； 3. 在基础上新增一个关键字标识：能够查询出所有redis操作日志； 4. 在基础上新增一个关键字标识：能够查询出所有状态变更日志； 5. 在基础上新增一个关键字标识：能够查询出现异常的日志； # 讨论点 如何更好实现日志优化改造 配合opx:ff(openspec-ff-change)使用
5. 过程可视化
5.1 交互时序图 (Sequence Diagram)
展示了开发者、AI 助手、OpenSpec CLI 与文件系统之间的交互流转。
代码段
OpenSpec CLI文件系统 (openspec/)AI 助手 (Claude/Cursor)开发者OpenSpec CLI文件系统 (openspec/)AI 助手 (Claude/Cursor)开发者阶段一：提案生成 (Planning)阶段二：审查与验证 (Validate)阶段三：任务实施 (Implementation)loop[任务循环 (按章节执行)]阶段四：归档同步 (Finalization)发起指令: /openspec:new-change <需求>1创建 changes/[name] 目录2生成 proposal.md, design.md 和 tasks.md3生成 Delta Specs (增量规范)4提示：提案已就绪，请审查5openspec show [name] (查看状态)6openspec validate [name] --strict (验证格式)7沟通与调整 (Refine Design)8更新 Specs 和 Task List9执行指令: /openspec:apply [name]10编写/修改代码11完成章节任务后更新 tasks.md (勾选 [x])12执行 /openspec-verify-change (一致性检查)13执行指令: /openspec:archive [name]14openspec archive [name] --yes15将 Delta Specs 合并至主 specs/ 目录16移动变更至 archive/ 目录17状态更新：Source of Truth 已同步18
5.2 决策与操作流程图 (Flowchart)
展示了从需求提出到最终归档的完整决策路径。
代码段
否
是
否
是
会话异常中断
任务完成
存在偏离
成功
开始开发任务
是否存在现有规范?
openspec init 建立基准
执行 /openspec:new-change
编写 Proposal & Design
CLI 验证通过?
根据错误信息修正 Markdown
执行 /openspec:apply 实施
代码实现中...
/openspec-continue-change 恢复上下文
verify 验证连贯性?
修正代码或更新 Spec
执行 /openspec:archive 归档
变更结束: 系统状态一致
6. 关键命令速查 (Cheatsheet)
| 命令 | 说明 | 适用场景 |
|---|---|---|
openspec init | 项目初始化 | 首次在项目中使用 OpenSpec 时 |
openspec list | 列出活跃提案 | 查看当前有哪些正在进行的开发任务 |
openspec show <name> | 查看提案详情 | 深度审查某个变更的 Proposal、Tasks 和 Delta |
openspec validate <name> | 验证格式 | 确保生成的 Markdown 格式符合 OpenSpec 标准 |
openspec archive <name> | 归档变更 | 开发完成，将变更合并到主规范库 |
openspec view | 启动仪表盘 | 以交互式可视化界面查看所有 Specs 和 Changes |
7. 注意事项 (Precautions)
- 环境一致性: 务必确保 Node.js 版本 ≥20.19.0，否则 CLI 可能无法正常运行或报错 。
- 指令上下文:
/openspec:*系列指令是 AI Agent (如 Claude Code) 的 Slash Command，必须在 AI 对话框中执行，而非在系统终端执行 。 - Source of Truth:
openspec/specs/目录是项目的唯一事实来源。不要手动随意修改这里的文件，建议通过 Proposal -> Archive 的流程进行更新，以保证变更的可追溯性 。 - 严格模式: 在执行 implementation 之前，建议总是运行
openspec validate <name> --strict，这能避免因 AI 生成格式错误导致的归档失败 。
8. 如何精通 (Mastery)
要从入门到精通 OpenSpec v1.1，建议关注以下几点：
- 善用 Delta 思维: 理解 OpenSpec 的变更机制是基于“增量（Delta）”的。在
changes/目录中，AI 只是在描述“主要规范通过此次变更发生了什么变化”，而不是重写整个规范。 - 任务驱动开发: 学会审查
tasks.md。如果 AI 生成的任务列表颗粒度太粗，请要求它重新拆解。更细的颗粒度意味着更可控的代码生成。 - 保持 Specs 清洁: 随着项目迭代，定期查看
openspec view仪表盘，确保主规范文档没有冗余或过时的逻辑。虽然 OpenSpec 自动处理合并，但定期的认为审查能保持“大脑”的清晰。
$ openspec view OpenSpec Dashboard ════════════════════════════════════════════════════════════ Summary: ● Specifications: 3 specs, 14 requirements ● Active Changes: 0in progress ● Completed Changes: 0 Specifications ──────────────────────────────────────────────────────────── ▪ center-query 6 requirements ▪ login 4 requirements ▪ service-type-management 4 requirements ════════════════════════════════════════════════════════════ - 混合使用 CLI 与 AI: 熟练的开发者会在 Terminal 中使用
openspec list/show快速获取信息，而在 Chat 中使用/openspec:apply指挥 AI 干活，实现“双流（Dual-Stream）”工作模式。
9. 使用注意点
代码存放位置声明
- 新创建的类存放的位置尽量定义好：否则ai去项目查找很耗token；最好有一个规则定义，直接查找项目规范；
Bash commandfind ……/vcc-api -name "*Service.java" -type f 2>/dev/null |grep -E "service/(I|impl)"|head -3 Find service files in vcc-call-api 声明task完成整个在修改
- 告诉ai，弄完一整个task在更新，而不是一个todo，容易消耗token（多次读取）
现在更新 tasks 文件： ⏺ Update(openspec/changes/integrate-center-service/tasks.md) ⎿ Added 3 lines, removed 3 lines 56## 2. 实体类和 Mapper 78 -- []2.1 创建 SysEnterpriseServiceBinding 实体类（commons 模块） 9 -- []2.2 创建 SysEnterpriseServiceBindingMapper 接口（test 模块） 10 -- []2.3 创建 ISysEnterpriseServiceBindingService 接口和实现类（test 模块） 8 +- [x]2.1 创建 SysEnterpriseServiceBinding 实体类（commons 模块） - 添加openspec全局配置
Task Management Policy - 仅在处理完一个章节任务在更新任务清单 配置之后，会有如下的效果
迭代总结
- 会话丢失新开会话，之前的change/proposal关联不上，容易产生两个spen的任务
- 因此可使用git worktree 尽量不想关的子任务；
