欢迎光临
我们一直在努力

【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 的最新版本 :

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 与文件系统之间的交互流转。

代码段

OpenSpec CLI文件系统 (openspec/)AI 助手 (Claude/Cursor)开发者OpenSpec CLI文件系统 (openspec/)AI 助手 (Claude/Cursor)开发者#mermaid-svg-nBPWS2o5JJWsSsh6{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-nBPWS2o5JJWsSsh6 .error-icon{fill:#552222;}#mermaid-svg-nBPWS2o5JJWsSsh6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-nBPWS2o5JJWsSsh6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-nBPWS2o5JJWsSsh6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-nBPWS2o5JJWsSsh6 .marker.cross{stroke:#333333;}#mermaid-svg-nBPWS2o5JJWsSsh6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-nBPWS2o5JJWsSsh6 p{margin:0;}#mermaid-svg-nBPWS2o5JJWsSsh6 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-nBPWS2o5JJWsSsh6 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-nBPWS2o5JJWsSsh6 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-nBPWS2o5JJWsSsh6 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-nBPWS2o5JJWsSsh6 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-nBPWS2o5JJWsSsh6 .sequenceNumber{fill:white;}#mermaid-svg-nBPWS2o5JJWsSsh6 #sequencenumber{fill:#333;}#mermaid-svg-nBPWS2o5JJWsSsh6 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-nBPWS2o5JJWsSsh6 .messageText{fill:#333;stroke:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-nBPWS2o5JJWsSsh6 .labelText,#mermaid-svg-nBPWS2o5JJWsSsh6 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .loopText,#mermaid-svg-nBPWS2o5JJWsSsh6 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-nBPWS2o5JJWsSsh6 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-nBPWS2o5JJWsSsh6 .noteText,#mermaid-svg-nBPWS2o5JJWsSsh6 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-nBPWS2o5JJWsSsh6 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-nBPWS2o5JJWsSsh6 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-nBPWS2o5JJWsSsh6 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-nBPWS2o5JJWsSsh6 .actorPopupMenu{position:absolute;}#mermaid-svg-nBPWS2o5JJWsSsh6 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-nBPWS2o5JJWsSsh6 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-nBPWS2o5JJWsSsh6 .actor-man circle,#mermaid-svg-nBPWS2o5JJWsSsh6 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-nBPWS2o5JJWsSsh6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}阶段一:提案生成 (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)

展示了从需求提出到最终归档的完整决策路径。

代码段

#mermaid-svg-Razy9NErd8I2O2nz{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Razy9NErd8I2O2nz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Razy9NErd8I2O2nz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Razy9NErd8I2O2nz .error-icon{fill:#552222;}#mermaid-svg-Razy9NErd8I2O2nz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Razy9NErd8I2O2nz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Razy9NErd8I2O2nz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Razy9NErd8I2O2nz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Razy9NErd8I2O2nz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Razy9NErd8I2O2nz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Razy9NErd8I2O2nz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Razy9NErd8I2O2nz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Razy9NErd8I2O2nz .marker.cross{stroke:#333333;}#mermaid-svg-Razy9NErd8I2O2nz svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Razy9NErd8I2O2nz p{margin:0;}#mermaid-svg-Razy9NErd8I2O2nz .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-Razy9NErd8I2O2nz .cluster-label text{fill:#333;}#mermaid-svg-Razy9NErd8I2O2nz .cluster-label span{color:#333;}#mermaid-svg-Razy9NErd8I2O2nz .cluster-label span p{background-color:transparent;}#mermaid-svg-Razy9NErd8I2O2nz .label text,#mermaid-svg-Razy9NErd8I2O2nz span{fill:#333;color:#333;}#mermaid-svg-Razy9NErd8I2O2nz .node rect,#mermaid-svg-Razy9NErd8I2O2nz .node circle,#mermaid-svg-Razy9NErd8I2O2nz .node ellipse,#mermaid-svg-Razy9NErd8I2O2nz .node polygon,#mermaid-svg-Razy9NErd8I2O2nz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Razy9NErd8I2O2nz .rough-node .label text,#mermaid-svg-Razy9NErd8I2O2nz .node .label text,#mermaid-svg-Razy9NErd8I2O2nz .image-shape .label,#mermaid-svg-Razy9NErd8I2O2nz .icon-shape .label{text-anchor:middle;}#mermaid-svg-Razy9NErd8I2O2nz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Razy9NErd8I2O2nz .rough-node .label,#mermaid-svg-Razy9NErd8I2O2nz .node .label,#mermaid-svg-Razy9NErd8I2O2nz .image-shape .label,#mermaid-svg-Razy9NErd8I2O2nz .icon-shape .label{text-align:center;}#mermaid-svg-Razy9NErd8I2O2nz .node.clickable{cursor:pointer;}#mermaid-svg-Razy9NErd8I2O2nz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Razy9NErd8I2O2nz .arrowheadPath{fill:#333333;}#mermaid-svg-Razy9NErd8I2O2nz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Razy9NErd8I2O2nz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Razy9NErd8I2O2nz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Razy9NErd8I2O2nz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Razy9NErd8I2O2nz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Razy9NErd8I2O2nz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Razy9NErd8I2O2nz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Razy9NErd8I2O2nz .cluster text{fill:#333;}#mermaid-svg-Razy9NErd8I2O2nz .cluster span{color:#333;}#mermaid-svg-Razy9NErd8I2O2nz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Razy9NErd8I2O2nz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Razy9NErd8I2O2nz rect.text{fill:none;stroke-width:0;}#mermaid-svg-Razy9NErd8I2O2nz .icon-shape,#mermaid-svg-Razy9NErd8I2O2nz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Razy9NErd8I2O2nz .icon-shape p,#mermaid-svg-Razy9NErd8I2O2nz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Razy9NErd8I2O2nz .icon-shape rect,#mermaid-svg-Razy9NErd8I2O2nz .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Razy9NErd8I2O2nz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Razy9NErd8I2O2nz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Razy9NErd8I2O2nz :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

会话异常中断

任务完成

存在偏离

成功

开始开发任务

是否存在现有规范?

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: 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 尽量不想关的子任务;
    赞(0)
    未经允许不得转载:171主机测评 » 【AI-SSD】openspec_v1.1使用心得
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址