OpenSpec 快速入门：让 AI 编码助手更可靠的规范驱动开发框架
OpenSpec是一个轻量级的规范驱动开发框架，通过结构化文档实现开发者与AI助手的可靠协作。其核心理念是在编码前先达成规范共识，采用"规范即真相"的双文件夹模型（specs/已实现规范+changes/待实现变更）。该框架解决传统开发中需求不明确、AI过度实现、变更难追溯等问题，提供四步标准化工作流：起草提案→审核对齐→实施任务→归档更新。安装仅需Node.js环境，通过命令
本文档使用 Claude Code 生成
目录
1. 什么是 OpenSpec?
OpenSpec 是一个轻量级的规范驱动开发框架（Spec-Driven Development Framework），旨在让开发者和 AI 编码助手（如 Claude Code、Cursor、Cline 等）通过结构化的规范文档对齐需求，从而实现更可靠、可审计的协作开发流程。
核心理念
“在编写任何代码之前，先就要构建什么达成一致”
OpenSpec 通过以下方式实现这一理念：
- 规范即真相：
openspec/specs/目录记录系统当前行为的权威规范 - 变更即提案：
openspec/changes/目录存放所有待实施的功能变更提案 - 审核优先：所有变更在实施代码前必须通过规范审核和验证
- 增量更新：每个变更以"增量"（delta）形式描述对现有规范的添加、修改或移除
关键特性
| 特性 | 说明 |
|---|---|
| 无需 API Key | 完全本地运行，无需外部服务 |
| AI 友好 | 通过斜杠命令或自然语言与 AI 助手集成 |
| 双文件夹模型 | specs/（已实现）+ changes/（待实现）清晰分离 |
| 可审计 | 所有变更历史存档在 changes/archive/ |
| 轻量级 | 仅依赖 Node.js，无复杂框架 |
2. 为什么需要 OpenSpec?
传统开发流程的痛点
场景 1：AI 助手的不可预测性
开发者: "帮我添加用户登录功能"
AI: (添加了登录功能，顺便加了注册、密码重置、邮箱验证...)
开发者: "我只要登录啊!" 🤦
问题：AI 根据聊天历史推测需求，容易过度实现或偏离意图。
场景 2：需求变更的混乱
Week 1: 开发者 A 实现了功能 X
Week 2: 开发者 B 不知道 X 的设计意图，重构时破坏了关键逻辑
Week 3: Bug 报告:"X 功能不工作了"
问题：缺少结构化的需求文档，功能设计意图随时间流失。
OpenSpec 如何解决这些问题？
| 问题 | OpenSpec 解决方案 |
|---|---|
| 需求不明确 | 强制在 proposal.md 中说明"为什么"和"改什么" |
| AI 过度实现 | 通过 tasks.md 限定具体实施范围 |
| 规范缺失 | specs/ 作为系统行为的单一真相来源 |
| 变更难追溯 | changes/archive/ 保留所有历史提案和决策 |
| 团队协作冲突 | 变更提案在实施前集中审核，避免重复工作 |
核心优势
- 确定性输出：规范明确，AI 生成的代码更可预测
- 审计友好：每次变更都有完整的提案、任务清单和规范增量
- 知识沉淀：历史归档记录项目演进的"为什么"
- 工具无关：兼容 Claude Code、Cursor、Windsurf 等主流 AI 工具
3. 安装 OpenSpec
前置要求
- Node.js：>= 20.19.0
- npm：随 Node.js 安装
检查当前版本：
node --version # 应输出 v20.19.0 或更高
npm --version
全局安装
npm install -g @fission-ai/openspec@latest
验证安装：
openspec --version
# 输出: @fission-ai/openspec/x.x.x
常用命令速览
# 核心命令
openspec init [path] # 在项目中初始化 OpenSpec
openspec update [path] # 更新 OpenSpec 指令文件
openspec list # 列出条目（默认显示变更）
openspec list --specs # 列出规范
openspec view # 显示规范和变更的交互式仪表板
openspec show [item-name] # 显示变更或规范
openspec validate [item-name] # 验证变更和规范
openspec archive [change-name] # 归档已完成的变更并更新主规范
# 管理命令
openspec change # 管理 OpenSpec 变更提案
openspec spec # 管理和查看 OpenSpec 规范
# 帮助命令
openspec help [command] # 显示命令帮助信息
4. 初始化项目
4.1 运行初始化命令
在项目根目录运行：
cd your-project
openspec init
4.2 交互式配置
初始化向导会询问以下问题：
第一步：选择 AI 工具
? Which AI coding tools do you want to configure?
❯ ◉ Claude Code
◉ Cursor
◯ Windsurf
◯ Cline
◯ Other
用空格键选择你使用的工具，回车确认。
第二步：配置斜杠命令（适用于支持的工具）
对于 Claude Code、Cursor 等工具，OpenSpec 会自动配置斜杠命令：
/openspec:proposal— 创建变更提案/openspec:apply— 实施任务/openspec:archive— 归档变更
4.3 验证初始化结果
初始化后，项目中会生成以下目录和文件：
your-project/
└── openspec/
├── AGENTS.md # AI 助手工作流指令
├── project.md # 项目上下文和规范
├── specs/ # 已实现功能的规范（初始为空）
└── changes/ # 待实施的变更提案（初始为空）
└── archive/ # 已完成变更的归档
检查配置：
openspec list
# 输出: No active changes found. (初始状态正常)
4.4 理解核心配置文件
初始化后生成的两个核心文件需要特别关注：
openspec/AGENTS.md — AI 助手工作流指令
作用：为 AI 编码助手提供 OpenSpec 工作流的详细指导，包括如何创建提案、实施任务、归档变更。
主要内容：
- 三阶段工作流程说明（创建、实施、归档）
- 提案创建的决策树（何时需要创建提案）
- 规范增量格式规范（
ADDED/MODIFIED/REMOVED） - 验证和调试技巧
- 常见错误和解决方案
特点：
- 由 OpenSpec CLI 自动管理
- 包含在
<!-- OPENSPEC:START -->和<!-- OPENSPEC:END -->标记之间的内容会自动更新 - 运行
openspec update可刷新到最新版本 - 不要手动编辑托管区域内的内容
openspec/project.md — 项目上下文配置
作用：记录项目特定的上下文信息，帮助 AI 助手理解项目的技术栈、代码规范、架构模式等。
自定义 project.md 建议：
- 初始化后立即编辑 — 根据项目实际情况填写
- 保持简洁但完整 — 包含 AI 需要的关键信息，避免过度细节
- 说明项目特有规范 — 代码风格、命名规范、架构模式等
- 定期更新 — 技术栈或架构变更时及时同步
- 团队协作 — 确保团队成员对内容达成共识
提示：
project.md的质量直接影响 AI 助手生成代码的准确性。
5. 基于 OpenSpec 四步工作流实战案例
工作流概览
┌─────────────────────┐
│ 1. 起草变更提案 │ 与 AI 分享你的意图
│ Draft Proposal │ /openspec:proposal
└──────────┬──────────┘
▼
┌─────────────────────┐ ┌──────────────┐
│ 2. 审核与对齐 │ ◄── │ 反馈循环 │
│ Review & Align │ │ 编辑规范/任务 │
│ │ └──────────────┘
│ 计划获批准 │
└──────────┬──────────┘
▼
┌─────────────────────┐
│ 3. 实施任务 │ AI 按规范编写代码
│ Implement Tasks │ /openspec:apply
│ │
│ 发布变更 │
└──────────┬──────────┘
▼
┌─────────────────────┐
│ 4. 归档并更新规范 │ 更新主规范库
│ Archive & Update │ /openspec:archive
└─────────────────────┘
案例：色彩一致性覆盖提示弹窗优化
本节通过一个完整的实战案例，演示如何使用 OpenSpec 添加"色彩一致性覆盖提示弹窗优化"功能。
5.1 起草第一个变更提案
在 OpenSpec 工作流中，提案的创建由 AI 助手自动完成。你只需要向 AI 描述想要实现的功能，AI 会根据 openspec/AGENTS.md 的指导自动生成所有必需的文件。
步骤 1：向 AI 助手描述需求
用自然语言清晰地描述你想要实现的功能。例如：
/openspec:proposal
1. PRD: https://tssoft.atlassian.net/browse/EV-xxxx 实现 overwrite 弹窗这部分需求点
2. Figma: https://www.figma.com/design/xxxx/V6.2?node-id=18463-137062&m=dev 严格依据设计稿
3. 设计稿中顶部图片预览区播放图片序列帧，素材来源项目根路径 "video/version/common/ColorConsistency.mp4"
...
提示：想要 AI 能读取需求文档以及设计稿等信息，需要添加对应 MCP 及进行身份认证。
描述要点：
- 需求背景 — 说明为什么需要这个功能，解决什么问题或抓住什么机会
- 功能描述 — 清晰列出要实现的具体功能点和用户场景
- 技术要求 — 说明必须遵循的技术约束、使用的框架或组件库
- 影响范围 — 标注会涉及哪些模块、文件或影响哪些现有功能
- 参考资料 — 如有需求文档、设计稿、API 文档等，提供链接或位置
执行后，AI 会自动：
- 根据你的需求描述创建变更提案
- 生成
openspec/changes/<change-name>/目录 - 创建
proposal.md（提案说明） - 创建
tasks.md（任务清单） - 创建
specs/<capability>/spec.md（规范增量） - 运行
openspec validate --strict验证格式
步骤 2：审查 AI 生成的提案
AI 会自动生成完整的提案结构。你需要审核以下内容：
检查 proposal.md：
AI 生成的提案会包含以下章节：
# Change:
## Why
[AI 根据你的描述总结的背景和原因]
## What Changes
- [AI 列出的具体变更点]
- [如有破坏性变更，AI 会标注 **BREAKING**]
## Impact
- 受影响的规范: [AI 识别的相关能力]
- 受影响的代码: [AI 推断的文件列表]
- [其他影响]
审核要点：
- Why 部分是否清晰说明了问题和解决方案？
- What Changes 是否完整覆盖了你的需求？
- Impact 是否准确识别了受影响的模块？
- 是否遗漏了重要的约束或依赖？
检查 specs/<capability>/spec.md：
AI 会生成规范增量，定义新增或修改的需求：
# [Capability] 规范增量
## ADDED Requirements
### Requirement: [需求名称]
[需求描述]
#### Scenario: [场景名称]
- **WHEN** [触发条件]
- **THEN** [预期结果]
- **AND** [附加条件]
## MODIFIED Requirements
### Requirement: [现有需求名称]
[完整的更新后需求]
审核要点：
- 需求描述是否准确？
- 场景是否覆盖了正常和异常情况？
- 是否使用了正确的操作标题（
ADDED/MODIFIED/REMOVED）？ MODIFIED需求是否包含完整内容？
检查 tasks.md：
AI 会将实施工作拆分为可执行的任务：
# 实施任务清单
## 1. [阶段名称]
- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]
## 2. [阶段名称]
- [ ] 2.1 [具体任务]
...
审核要点：
- 任务顺序是否合理？（数据库 → 后端 → 前端 → 测试）
- 任务粒度是否适中？（每个任务 1-2 小时可完成）
- 是否包含测试和文档任务？
- 是否遗漏了关键步骤？
步骤 3：与 AI 迭代调整
如果发现问题，直接告诉 AI 需要调整的地方：
proposal.md 中遗漏了一个重要场景：xxxx。
请在 spec 增量中添加这个场景。
tasks.md 中的测试任务太笼统，请细化为：
1. 单元测试
2. 集成测试
3. xxxxxx
变更名称 `add-color-consistency-overwrite-dialog` 太简略，请改为 `xxx` 更具描述性。
AI 会根据你的反馈更新文件，你可以重复审核和调整，直到满意为止。
提示：提案文件由 AI 生成，但你随时可以手动编辑调整。编辑后记得运行
openspec validate --strict确保格式仍然正确。
5.2 提案审核与调整
步骤 1：运行严格验证
在提案目录完成后，通常可以让 AI 帮你直接执行验证，也可手动运行验证命令：
openspec validate add-color-consistency-overwrite-dialog --strict
可能的输出：
成功：
Change 'add-color-consistency-overwrite-dialog' is valid
失败示例 1 — 缺少场景：
Error: Requirement "Two-Factor Authentication" must have at least one scenario
File: openspec/changes/add-color-consistency-overwrite-dialog/specs/color-consistency-dialog/spec.md
解决方案：确保每个
### Requirement:下至少有一个#### Scenario:。
失败示例 2 — 场景格式错误：
Warning: Scenario header format incorrect
Expected: #### Scenario: <name>
Found: ### Scenario: User login
解决方案：场景标题必须使用 4 个井号（
####）。
失败示例 3 — 没有规范增量：
Error: Change must have at least one delta
Directory: openspec/changes/add-color-consistency-overwrite-dialog/specs/
解决方案：确保
specs/目录下有至少一个能力文件夹和spec.md。
步骤 2：团队审核
验证通过后，将提案提交给团队审核：
- 创建 Pull Request 或分享提案链接
- 审核要点：
proposal.md的 Why 是否清晰？tasks.md是否遗漏关键步骤？- spec 增量是否完整覆盖需求？
- 是否有破坏性变更需要特别标注？
- 迭代调整：根据反馈修改
proposal.md、tasks.md或 spec 增量 - 再次验证：修改后重新运行
openspec validate --strict
重要提醒：提案在进入实施阶段后，规范增量应保持不可变。如果发现需求变更，应创建新的变更提案而非修改原提案。
5.3 实施任务
在 OpenSpec 工作流中，任务实施同样由 AI 助手自动完成。通过 /openspec:apply 命令，AI 会读取提案和任务清单，自动编写代码并逐步完成所有任务。
步骤 1：执行实施命令
/openspec:apply add-color-consistency-overwrite-dialog
AI 会自动执行以下操作：
-
读取提案文档
- 理解
proposal.md中的变更目标和影响范围 - 查看
design.md（如果存在）理解技术决策 - 获取
tasks.md中的完整任务清单
- 理解
-
按顺序实施任务
- 从第一个任务开始，逐项完成
- 根据项目的技术栈和代码规范生成代码
- 创建必要的文件、修改现有文件
- 编写单元测试和集成测试
-
更新任务状态
- 完成每个任务后，在
tasks.md中标���为[x] - 保持任务清单与实际进度同步
- 完成每个任务后，在
步骤 2：人工审核代码
重要：即使 AI 自动生成代码，你也必须人工审核每个变更。
审核要点：
- 功能正确性：代码是否正确实现了需求？逻辑是否符合 spec 中定义的场景？
- 代码质量：是否遵循项目的代码规范？命名是否清晰、结构是否合理？是否有明显的 bug 或性能问题？
- 测试覆盖：是否编写了必要的单元测试？测试用例是否覆盖了正常和异常场景？
- 安全性：是否存在安全漏洞？
步骤 3：本地测试
在提交代码前，务必进行本地自测：
- 所有开发自测用例通过
- 新增功能按预期工作
- 没有破坏现有功能
步骤 4：提交代码
所有任务完成且测试通过后，提交代码。
5.4 归档与更新
步骤 1：运行归档命令
功能部署且验证通过后，运行归档命令：
openspec archive add-color-consistency-overwrite-dialog --yes
参数说明：
--yes/-y：跳过确认提示（适用于 CI/CD 自动化）--skip-specs：仅归档变更，不更新specs/（适用于仅工具配置的变更）
归档操作会执行：
-
应用规范增量：将
changes/<change-name>/specs/中的增量应用到specs/ADDED需求追加到对应的spec.mdMODIFIED需求替换原有内容REMOVED需求从规范中删除
-
移动变更到归档：将
changes/<change-name>/移动到changes/archive/YYYY-MM-DD-<change-name>/
步骤 2：提交规范更新
归档操作本身不会自动提交 Git 变更，需要手动提交。
6. 使用技巧
-
大型需求拆分多个提案进行：避免单个提案过于庞大，降低审核和实施的复杂度。
-
善用语气关键词：
- MUST — 必须满足（经常用于：功能性、合规性、安全性）
- SHOULD — 强烈建议，但可以在有合理理由时例外（兼容性、性能优化等）
- MAY — 可选（非关键特性、增强功能）
MAYBE— 不常用且含糊；不要把 MAYBE 当作正式术语。要么决定用 MAY（可选），要么把 “MAYBE” 解释为"条件性（如果 X 则启用）"
7. 附录：OpenSpec 目录结构详解
目录树参考
openspec/
├── AGENTS.md # AI 助手工作流指令（自动生成和更新）
├── project.md # 项目上下文、技术栈、约定
├── specs/ # 已实现功能的规范
│ ├── color-consistency-dialog/
│ │ ├── spec.md # 需求和场景
│ │ └── design.md # 技术设计
│ ├── Axxxx/
│ │ └── spec.md
│ └── Bxxxx/
│ ├── spec.md
│ └── design.md
├── changes/ # 待实施的变更提案
│ ├── add-color-consistency-overwrite-dialog/
│ │ ├── proposal.md # 提案说明
│ │ ├── tasks.md # 任务清单
│ │ ├── design.md # 技术决策
│ │ └── specs/ # 规范增量
│ │ ├── color-consistency-dialog/
│ │ │ └── spec.md
│ │ └── Axxxx/
│ │ └── spec.md
│ └── archive/ # 已完成变更的归档
│ └── 2025-11-14-add-color-consistency-overwrite-dialog/
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
└── .openspec/ # OpenSpec 内部配置（自动生成）
└── config.json
文件和目录说明
| 文件/目录 | 作用 |
|---|---|
openspec/AGENTS.md |
为 AI 编码助手提供工作流指令，说明如何创建提案、实施任务、归档变更。由 OpenSpec CLI 管理，不要手动编辑托管区域 |
openspec/project.md |
记录项目特定的上下文信息，供 AI 助手理解项目 |
openspec/specs/<capability>/ |
存放已实现并部署的功能规范，是系统行为的唯一真相来源 |
openspec/changes/<change-name>/ |
存放待实施的变更提案，包含提案说明、任务清单和规范增量 |
proposal.md |
说明变更的背景、内容和影响，供团队审核 |
tasks.md |
提供可执行的任务清单，指导开发者逐步实施变更 |
design.md（可选） |
记录技术决策、架构考量、权衡分析，供团队理解复杂变更的设计思路 |
specs/<capability>/spec.md |
描述对现有规范的增量变更，使用 ADDED / MODIFIED / REMOVED 操作标题 |
openspec/changes/archive/ |
存放已完成并归档的变更，保留历史决策和提案。可用于查看功能的历史提案、理解设计决策、审计变更历史 |
8. 进一步学习
官方资源
- GitHub 仓库：Fission-AI/OpenSpec
- 文档中心：Fission-AI/OpenSpec | DeepWiki
- 更新日志：查看 GitHub Releases
记住核心原则：
“在编写任何代码之前，先就要构建什么达成一致”
Happy coding with OpenSpec! 🚀
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
22
0- 0
已为社区贡献4条内容
所有评论(0)