告别"靠聊天记录驱动开发"的混乱时代，用结构化的规格管理让 AI 编程助手更可控、更可靠。
前言
AI 编程助手（如 Claude Code、Cursor 等）已经极大地提升了开发效率，但一个普遍的问题是：需求只存在于聊天记录中。当你和 AI 来回对话几十轮后，很难追踪"当前到底实现了什么"、"为什么要这样设计"。更糟糕的是，换一个 AI 会话或换一个工具，之前的上下文全部丢失。
OpenSpec 正是为了解决这个问题而生的------它在你和 AI 之间建立了一层轻量级的规格层，让你在写任何代码之前先对齐"要构建什么"。
一、OpenSpec 是什么？
OpenSpec 是一个 AI 原生的规格驱动开发框架，核心思路是：
用结构化的 Markdown 文件管理项目的"行为真相"，而不是靠聊天记录来追踪需求。
它提供了一套标准的命令行工具和 AI 斜杠命令，覆盖从需求调研、规格定义、代码实现到归档的全生命周期。
与传统开发的对比
| 方式 | 需求管理 | 可追踪性 | AI 协作 |
|---|---|---|---|
| 不用框架 | 散落在聊天记录里 | 几乎为零 | 不可预测 |
| GitHub Spec Kit | 严格阶段门控 | 好，但笨重 | 需 Python 环境 |
| AWS Kiro | 锁定 IDE 和模型 | 好 | 仅支持 Claude |
| OpenSpec | Markdown 文件管理 | 完善 | 25+ 工具自由选择 |
二、核心概念
2.1 生成文档的目录结构
your-project/
├── openspec/
│ ├── specs/ # 主规格目录（系统当前行为的真相来源）
│ │ └── <domain>/ # 按领域组织（如 auth/、payments/）
│ │ ├── spec.md # 行为规格（WHAT & WHY）
│ │ └── design.md # 技术设计（HOW，可选）
│ ├── changes/ # 进行中的变更
│ │ └── <change-name>/ # 每个变更一个文件夹
│ │ ├── proposal.md # 变更提案（为什么做、做什么）
│ │ ├── design.md # 技术设计（怎么做）
│ │ ├── tasks.md # 实现任务清单
│ │ ├── .openspec.yaml # 变更元数据（schema、创建日期）
│ │ └── specs/ # Delta 规格（增量变更）
│ │ └── <domain>/
│ │ └── spec.md
│ │ └── archive/ # 已完成的变更存档
│ │ └── YYYY-MM-DD-<name>/ # 带日期前缀的归档文件夹
│ └── config.yaml # 项目配置文件
│
├── .claude/skills/ # Claude Code 技能文件（如选择了 claude）
├── .cursor/skills/ # Cursor 技能文件（如选择了 cursor）
├── .cursor/commands/ # Cursor OPSX 命令文件
└── ... # 其他 AI 工具配置 2.2 Delta Spec：OpenSpec 的灵魂
Delta Spec 是 OpenSpec 最核心的设计。它用三个标记来描述"这次改了什么"：
markdown
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
系统必须要求用户在登录时提供第二因素认证。
#### Scenario: OTP required
- GIVEN 一个启用了 2FA 的用户
- WHEN 用户提交了正确的用户名和密码
- THEN 系统应展示 OTP 验证页面
## MODIFIED Requirements
### Requirement: Session Timeout
系统应在 30 分钟无操作后使会话过期。
（之前：60 分钟）
## REMOVED Requirements
### Requirement: Remember Me
（被 2FA 功能取代，已弃用）Archive 时发生了什么？
当你执行 /opsx:archive 时：
- ADDED 的需求追加到主规格文件
- MODIFIED 的需求替换原有版本
- REMOVED 的需求从主规格中删除
- 整个 change 目录移入
openspec/changes/archive/作为审计历史
这意味着你的 openspec/specs/ 始终是项目当前行为的"唯一真相来源"。
三、安装与初始化
3.1 安装 CLI
bash
npm install -g @fission-ai/openspec@latest3.2 初始化项目
bash
cd your-project
openspec initopenspec init 会自动检测你已安装的 AI 工具（Claude Code、Cursor、Windsurf 等 25+ 工具），并生成对应的斜杠命令配置文件。
3.3 验证安装
bash
openspec --version
openspec list # 查看当前活跃的变更（此时应为空）四、完整开发流程
OpenSpec 默认使用 Core Profile，核心流程只有三步：
/opsx:propose ──► /opsx:apply ──► /opsx:archive4.1 第一步：提出变更（Propose）
当你要开发一个新功能时，只需在 AI 助手（以 Claude Code 为例）中输入：
text
/opsx:propose add-user-loginAI 会自动创建 openspec/changes/add-user-login/ 目录，并生成四个标准产物：
| 文件 | 内容 | 作用 |
|---|---|---|
proposal.md |
为什么要做这个功能、影响范围 | 对齐动机 |
specs/ |
用 ADDED/MODIFIED/REMOVED 标记的 Delta Specs | 定义行为 |
design.md |
技术方案、架构决策 | 指导实现 |
tasks.md |
分步骤的实现任务清单（带 checkbox） | 跟踪进度 |
这一步的关键价值在于：在写任何代码之前，你和 AI 先就"要构建什么"达成共识。
4.2 第二步：实现（Apply）
确认 proposal 和 specs 没问题后，直接：
text
/opsx:applyAI 会按照 tasks.md 中的清单逐项实现代码，边做边打勾：
text
✓ 1.1 创建用户模型 User model
✓ 1.2 实现密码哈希存储
✓ 1.3 添加 JWT token 生成逻辑
✓ 2.1 创建 /api/login 路由
✓ 2.2 实现登录表单校验
✓ 2.3 添加单元测试
...
全部任务完成！4.3 第三步：归档（Archive）
功能开发完成、测试通过后：
text
/opsx:archiveAI 会自动将 Delta Specs 合并进主规格库，并将 change 移入归档目录：
text
Archiving add-user-login...
✓ Merged specs into openspec/specs/auth/spec.md
✓ Moved to openspec/changes/archive/2025-05-15-add-user-login/
Done! Ready for the next feature.此时你的主规格文件已经包含了最新的需求定义，随时可以开始下一个功能。
五、需求不明确时：先 Explore
如果你还不确定具体要做什么（例如性能优化、架构重构、Bug 排查），在 propose 之前先用：
text
/opsx:exploreAI 会帮你分析代码库、调研方案，再决定怎么做。例如：
text
You: /opsx:explore
AI: 你想探索什么？
You: 我想提升页面加载性能，但不确定瓶颈在哪。
AI: 让我分析一下...
[分析 bundle 大小、检查慢查询、审查组件渲染模式]
我发现了三个主要瓶颈：
1. 未优化的大图片（占比最高）
2. ProductList 中的同步数据获取
3. Context 变化导致的频繁重渲染
你想先解决哪个？
You: 先解决数据获取的问题。
You: /opsx:propose optimize-product-list-fetching六、流程全景图
是
否
是
否
项目初始化
openspec init
需求明确？
/opsx:propose
功能名
/opsx:explore
调研分析
AI 生成
proposal / specs
design / tasks
人工审查
对齐需求
/opsx:apply
AI 按 tasks 实现代码
验证实现
（可选）/opsx:verify
/opsx:archive
合并 specs，归档 change
下一个功能？
项目完成 🎉
七、常用命令速查
CLI 命令
bash
openspec init # 初始化项目，自动检测 AI 工具
openspec update # 更新 AI 指令文件
openspec list # 查看所有活跃变更
openspec show <name> # 查看变更或规格详情
openspec validate <name> # 校验 spec 格式
openspec view # 交互式仪表盘
openspec archive <name> # 归档已完成的变更
openspec config profile # 管理 profile（core / custom）AI 斜杠命令
| 命令 | Profile | 作用 |
|---|---|---|
/opsx:propose |
Core | 一步生成所有规划产物 |
/opsx:explore |
Core | 先调研再规划 |
/opsx:apply |
Core | 按 tasks.md 实现代码 |
/opsx:archive |
Core | 合并规格、归档变更 |
/opsx:new |
Custom | 创建新变更 |
/opsx:continue |
Custom | 逐步生成规划产物 |
/opsx:ff |
Custom | 跳过审查，快速推进 |
/opsx:verify |
Custom | 验证实现与 specs 一致性 |
/opsx:bulk-archive |
Custom | 批量归档 |
/opsx:onboard |
Custom | 新成员快速了解项目结构 |
八、进阶功能
8.1 动态指令生成
OpenSpec 的 AI 不靠硬编码提示词工作。每次调用斜杠命令时，AI 会运行时执行：
bash
openspec status --json # 获取当前变更状态
openspec instructions --json # 获取动态组装的操作指令这确保了 AI 的行为随项目状态自适应，而不是执行固定脚本。
8.2 可定制的 Schema 系统
通过 openspec/schemas/ 目录，你可以自定义工作流模板。社区也提供第三方 schema bundle，类似插件生态，可以集成更多工具和工作流。
8.3 Profile 切换
如果你需要更细粒度的工作流控制：
bash
openspec config profile # 切换到 custom profile
openspec update # 应用配置，生成额外的斜杠命令九、为什么选择 OpenSpec？
与同类工具的对比
vs. GitHub Spec Kit
Spec Kit 功能全面但偏重，有严格的阶段门控、大量 Markdown 模板和 Python 环境依赖。OpenSpec 更轻量，允许自由迭代，没有刚性阶段锁。
vs. AWS Kiro
Kiro 功能强大，但锁定了 IDE 和模型（仅支持 Claude）。OpenSpec 支持 25+ AI 工具，你可以用自己喜欢的任何工具。
vs. 什么都不用
没有规格管理的 AI 编程 = 模糊的提示词 + 不可预测的结果。OpenSpec 在不增加过多仪式感的前提下，带来了可预测性和可追踪性。
核心优势
- 先对齐再构建：人和 AI 在写代码前就 spec 达成一致
- 结构化管理：每个功能独立文件夹，proposal / specs / design / tasks 四件套
- 灵活迭代：随时修改任何产物，没有刚性阶段门控
- 工具自由：不锁定 IDE，不锁定模型，支持 25+ AI 工具
- 审计历史：每次 archive 都是完整的变更记录
十、总结
OpenSpec 填补了 AI 辅助编程中"需求管理"这一关键空白。它不是要增加你的负担，而是用轻量级的 Markdown 文件 + 结构化的 Delta Spec 机制，让 AI 编程助手的工作成果更可控、更可追踪。
三步上手，今天就试试：
bash
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init然后在你的 AI 助手中输入 /opsx:propose your-first-feature，体验"先对齐再构建"的开发方式。
参考链接