【AI-SSD】openspec_v1.1使用心得
OpenSpec v1.1的 使用指南；文档着重于“规格驱动开发（Spec-Driven Development）”的流程，涵盖了从安装、交互流程到进阶使用的全方位解析。
·
这是一份 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 的最新版本 ：
npm install -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 1 file (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 与文件系统之间的交互流转。
代码段
5.2 决策与操作流程图 (Flowchart)
展示了从需求提出到最终归档的完整决策路径。
代码段
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: 0 in 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 command find ……/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
5
6 ## 2. 实体类和 Mapper
7
8 -- [ ] 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 尽量不想关的子任务；
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
9
0- 0
已为社区贡献2条内容
所有评论(0)