使用者痛点

• AI 编程助手直接写代码导致需求理解错误、代码偏离业务意图
• 多轮对话后上下文漂移，开发逻辑不连贯
• 变更上下文散落在聊天记录中，难以追踪和维护
• 规格没有沉淀，后续维护者难以理解原始设计意图
• 复杂变更缺乏结构化管理，难以控制风险和进度
• 团队协作时规格同步困难。容易产生冲突
• 实现过程中发现设计问题却无法方便地回溯更新规格
• 归档流程复杂，历史变更记录管理混乱
• 轻量级项目想快速迭代，重量级项目需要细粒度控制——一刀切的流程无法满足不同场景需求
• AIOps 和传统 DevOps 之间缺乏有效衔接机制

OpenSpec 是一个面向 Spec-Driven Development 的本地 CLI + AI slash command 工作流工具。

它解决的是：AI 编程时代如何让机器围绕明确、可审查、可演进、可归档的规格来工作的问题。

主要理念是：把规格作为程序行为的事实来源，通过 artifact 依赖关系让 AI 的实现过程有清晰上下文。

. 使用者痛点背景：为什么需要 OpenSpec？

• 减少误解风险：先达成共识再实现，降低需求理解错误概率 80%
• 提高协作效率：团队成员通过同一套规格工作，减少沟通成本 70%
• 保持知识沉淀：每次变更都形成可追溯记录，降低维护成本 60%
• 灵活适配场景：支持快速迭代到精细控制两种模式切换。覆盖所有开发场景需求

. 主要目录结构

openspec/├── specs/│ └── /│ └── spec.md├── changes/│ └── /│ ├── proposal.md│ ├── design.md│ ├── tasks.md│ └── specs/│ └── /│ └── spec.md└── config.yaml

这个结构直观展示了： 1. specs/ 是当前程序行为的事实来源 2. changes/ 是进行中的变更工作区 3. 每个 change 包含完整的上下文信息

使用者最关注点 - "我该把什么放在 specs 下？" - "一个 change 应该包含哪些文件？" - "proposal.md 和 design.md 有什么具体区别？ "

实际使用场景 markdown

$ openspec init # 初始化目录结构 $ /opsx:propose add-payment-gateway # 自动创建 change 和所有 artifact

$ openspec archive payment-gateway # 自动合并规格并归档

$ openspec show payment-gateway # 查看历史变更记录和当前规格状态

. CLI 命令与 OPSX Slash Commands 对比

. 使用者常见疑问

常见问题	OpenSpec 的方法
"如何让AI先分析清楚再写代码而不是直接写错？"	/opsx:explore → /opsx:propose → /opsx:apply 三步走流程强制分离探索→规划→实现阶段
"如何避免长期项目中上下文漂移?"	$ openspec validate 周期性校验 artifact 一致性 $ openspec archive old-change 强制将已完成 change 融入主规格	"如何管理复杂功能的逐步实现?"	/opsx:new → /opsx:continue ×N → /opsx:apply 分阶段生成 artifact 提供细粒度控制	"如何处理发现设计问题时需要回头修改?"	$ openspec status 查看进度 直接修改任意 artifact 再继续/b/

. 极简 vs 深度工作流对比

比较维度
主要模式/th/th colspan='5'> 模式/th/
	适合场景/th/	适合场景/th/
	小功能特性 快速迭代 明确需求 低风险变更 复杂架构调整 高风险业务功能 长期大型项目 多人协作环境

极简模式/th/深度模式/th/ - 一次性生成所有 artifacts - 最少步骤完成 - 默认命令优先级高 - 较少配置项 - 主要使用 /opsx:* slash commands - 分阶段生成 artifacts - 每步都可停止审查 - 需要显示选择 profile - 支持自定义 workflow - 主要使用 openspec CLI 配合 slash commands/tr< /opsx:propose <-> /opsx:apply -> ... -> /opsx:sync -> /opsx:archive/t//opsx:new -> -> ... -> -> .../tr< $ openspec list/td/$ openspec config profile/$ openspec update/$ openspec validate/tr< **关键选择因素**： - 项目周期长短 - 功能复杂度 - 风险等级 - 人员参与数量 **转换方法**：两种模式可以随时切换： bash openspec config profile extended # 转为深度模式 openspec update # 生效新配置 openspec config profile core

. 推荐使用方式

**典型场景应对方案**

挑战描述	推荐命令序列	预期结果
新增简单功能且需求明确	/exploer``/propose /apply /sync /archive	一小时内完成
不熟悉领域先探索	/exploer -> new `-> apply`	阶段性输出
高风险金融功能	/new /verify`/sync | archive	全链路质量把关
长周期重构项目	init project-wide spec``use bulk-sync periodically``archive milestone increments	大块拆小块

领域常用方法 markdown

SaaS 网站建议做法:

• 每个微服务单独建立 OpenSpec 项目
• 公共组件集中管理在 org-level repo 中

金融领域特殊要求:

• 必须启用 模式 workflow profile * 每个商品交易相关变更必须阶段 * 强制要求提出前做探索分析 * 涉及资金安全的任务必须手动标注为 critical

团队协同建议 bash

cd project && git checkout -b feat/login-v2 && ops new login-v2 && ...

git checkout feat/login-v2 && ops continue --next design.md && ...

git checkout feat/login-v2 && ops verify --focus security-compliance && ...

. 常见陷阱及避免方法

❌ 错误做法: "/opsk apply" 跳过 proposal 阶段 ➡︎ ⚠︎ 高概率出错 ✅ 正确做法: "/opsk propose " ➡︎ "/opsk apply"

❌ 错误做法: "只修改 proposal 不更新 delta specs" ➡︎ ⚠︎ 一致性丢失 ✅ 正确做法: "同时更新相关 artifacts"

❌ 错误做法: "将未完成 change 提交到 master" ➡︎ ⚠︎ 主线污染 ✅ 正确做法: "$ ops archive "

❌ 错误做法: "忽略 verify 阶段在高风险领域" ➡︎ ⚠︎ 安全隐患 ✅ 正确做法: "$ ops verify --strict "

bash {line-numbers}

常用方法检查脚本

checkproposal { if;n echo " Missing proposal";exit 1，fi }

check_specs { local expected=$ if;n echo " Empty delta specs";fi }

validate_workflow { if ] && ];n echo " Missing verification";exit 1，fi }

。

---