一文读懂 OpenSpec：AI 时代的“规格驱动”开发利器

一、为什么我们需要 OpenSpec？

随着 AI 辅助编程工具被越来越广泛地使用，开发者们遇到了一个难以回避的痛点：AI 能看懂代码的语法和逻辑（当下存在的结果），却无法凭空猜出这些代码背后的“前世今生”（早期的业务考量与架构决策）。

当你在对话框里输入一行指令时，AI 看到的是存量的源代码和类型定义。然而，这段逻辑当初为什么要这么设计？有哪些边界条件是必须绕过的坑？未来的架构演进方向是什么？这些隐藏在开发者大脑或碎片化文档中的“软上下文（Soft Context）”，是 AI 的盲区。

OpenSpec 这一开源框架正是为了打通这种“信息断层”而诞生的。它不单是一套目录规范，更是帮助 AI 搞懂项目背景的“意图翻译器”。通过一组简单的斜杠命令（Slash Commands），OpenSpec 能把你和 AI 的协作从“直接随性地生成代码”升级为“规格驱动开发”（Spec-Driven Development）。这也意味着，在生成代码前，AI 就已经彻底搞懂了你的需求背景与技术底线。

二、OpenSpec 与 AI Skills 的比较

OpenSpec 和 AI Skills (Agent Skills) 都是为了解决 AI 编程时代“如何让 AI 更可靠地参与开发”的问题，但它们解决的问题完全不同，属于两个层级的体系。

简单一句话总结：

• OpenSpec = 规范开发流程（Specification Driven Development）
• AI Skills = 为 AI Agent 提供可复用能力（Agent Capability Extension）

核心定位对比

三、AI 规格驱动工具：GitHub Spec Kit vs. Fission-AI OpenSpec

在“规格驱动开发（SDD）”领域，目前有两个备受关注的开源利器，它们虽然目标一致，但设计哲学各有千秋：

• GitHub Spec Kit：由 GitHub 团队推出，带有浓厚的“企业级”基因。它强调严格的四阶段验证流（Specify → Plan → Tasks → Implement），并引入了独特的“宪法文件（Constitution）”来约束 AI 的行为。它更像是严谨的架构师，适合Greenfield 项目（从零开始的新项目）。
• Fission-AI OpenSpec：则更像是一位敏捷的实战派。它主张“变革隔离（Change Isolation）”，为每一个小的功能变更创建独立的目录，避免上下文污染；同时它的工作流更加轻量、灵活，非常适合在Brownfield 项目（已有存量代码的项目）中进行增量开发。

OpenSpec 的优势在于：只为新的 Change 建立规格。也就是说：

• 旧系统 = 保持不动
• 新功能 = 用 Spec 管理

随着时间推移，Spec 会逐渐积累，最终形成完整的系统知识库。这就是 OpenSpec 的核心设计哲学。本文将重点介绍 Fission-AI OpenSpec，探索它如何通过简洁的指令流，在现有代码库中释放 AI 的最大潜力。

四、OpenSpec 快速入门

# Node.js >= 20.19.0（必须，用于支持最新的文件系统 API）
npm install -g @fission-ai/openspec@latest

然后导航到你的项目目录并初始化：

cd your-project
openspec init

执行 openspec init 命令后，根据提示选择你常用的 AI 工具（例如 Claude Code、Cursor、Antigravity 等），选择完成后按回车确认，最后重启 IDE 使配置生效。

五、OpenSpec 核心目录结构

openspec/
├── config.yaml          # 全局 CLI 配置文件
├── specs/               # 存放已同步的主规范文件
└── changes/             # 存放所有的变更（Changes）
    ├── archive/         # 已归档的变更目录
    └── add-order-list-page/  # 当前正在进行的变更（新增订单列表页面）
        ├── proposal.md  # 变更提案（动机、变更内容、核心能力等）
        ├── design.md    # 技术设计文档（架构决策、风险等）
        ├── tasks.md     # 任务清单（待办事项列表）
        └── specs/       # 该变更相关的增量规范（Delta Specs）
            └── order-list-page/
                └── spec.md  # 订单列表页面的详细功能规格

六、落地指南：业务需求如何转化为 OpenSpec？

将现实中的业务需求翻译成 AI 可理解的“规格”，是使用 OpenSpec 的关键所在。这不仅仅是把文字填进 Markdown，而是一次“需求工程”的提炼过程。

1. Change 拆分（Change Decomposition）

大需求不应毕其功于一役。为了让 AI 的注意力保持集中，应当把大需求拆分为多个 Change，每个 Change 应遵循以下原则进行拆分：

• 单一能力原则：每个 Change 只解决一个核心业务点，避免“套餐式”更新导致逻辑耦合。
• 功能边界清晰：明确定义“做什么”以及“不做什么”，防止 AI 在自动编码时改动无关文件。
• 领域驱动隔离：按业务领域（如用户、订单、支付）划分 Change 集合。因为 Change 最终会通过 Sync 机制合并到主规格库，只有源头 Change 的边界清晰，才能保证最终汇总的 openspec/specs/ 知识库不会变成一团乱麻。

2. 需求转化核心步骤（The Transformation Flow）

在每个拆分好的 Change 中，需求转化为代码的核心工作流如下：

阶段一：需求 → Proposal

第一步不是写 Spec，而是写 Proposal。Proposal 需要说明：

• 为什么要做这个功能
• 解决什么问题
• 影响哪些模块
• 是否有替代方案

💡 Proposal 的本质是：记录架构决策。

阶段二：Proposal → Design

Design 描述技术实现思路，例如：

• API 设计
• 数据结构
• 架构调整
• 风险分析

💡 Design 解决的问题是：系统要怎么实现这个需求。

阶段三：Design → Tasks

Tasks 将设计拆分为具体任务，例如：

• 新增导出 API
• 新增导出按钮
• 新增文件下载逻辑
• 新增权限校验

💡 Tasks 是 AI 生成代码的主要依据。

3. 规格颗粒度控制（Spec Granularity）

Specs 是开发者与 AI 之间的“契约”。颗粒度的把握直接影响代码质量：

• 拒绝信息过载：不要在 Spec 中事无巨细地复述已有的代码逻辑。AI 的长处是理解上下文，你应该只提供它无法通过直接阅读源码获取的增量信息。
• 补充关键盲区：如果设计稿未出或接口文档残留，应在 Spec 中明确标注占位规则或 Mock 约定。
• 动态迭代优化：OpenSpec 允许在开发过程中不断修正 Spec。如果发现 AI 理解有偏差，应在 changes/xxx/specs/ 下补充细节，然后再次执行 /opsx:apply 进行增量修正。

七、工作流：从“标准”到“进阶”

OpenSpec 提供了灵活的配置方案。通过 openspec config profile 命令，你可以在标准（Minimum）和全量（Full）工作流之间切换。

1. 标准工作流：追求极致效率 (Fast Track)

适合需求明确、逻辑简单的任务。这是默认的“快车道”，只需三个关键动作即可完成闭环。

2. 精细工作流：深度掌控质量 (Control Mode)

对于涉及核心业务逻辑、跨模块修改或高风险任务，建议开启全量模式。

八、进阶：规格的“自我生长”与迭代

很多开发者关心：“下次迭代已存在的功能时，AI 会参考之前的设计吗？”

答案是：会，但这依赖于 OpenSpec 的 Sync（同步）机制。

1. 物理传承而非记忆：/opsx:sync 会将当前 Change 中的 Delta Specs 合并到 openspec/specs/ 主规格库，使后续变更可以参考这些已有规格。
2. 增量设计：再次迭代同一功能时，AI 会先扫描主规格库，识别出已有的“项目宪法”，在新的方案中明确说明：“基于现有 order-list-page/spec.md，我们将新增...”。
3. 价值积累：你每一次归档，都是在给 AI “喂”项目知识。随着项目迭代，AI 会越来越懂你的业务逻辑和设计规范。

九、核心避坑与进阶技巧

1. 规范同步：别让 AI 变成“断网式”协作

关键提醒：在执行 /opsx:archive 时，并非所有 AI 工具都会自动触发增量规范（Delta Spec）的同步。

为了确保你的架构决策能被永久记录并传承给下一次迭代，强烈建议在归档前手动执行 /opsx:sync。

2. 精准选择：/opsx:propose vs. /opsx:ff

两者分别对应了开发者对 AI 信任度的两种状态：

• Propose 细节：AI 会从创建文件夹、写提案到任务拆解全部包办。
• FF 细节：先执行 /opsx:new 创建空变更，接着运行 /opsx:continue 让 AI 生成初步的 proposal.md。在你手动修改并确认核心方案无误后，再用 /opsx:ff 让 AI 补完剩下的规格和技术实现细节。

3. 多任务管理与灵活性

• 多任务并存：OpenSpec 支持同时开启多个变更（Change），但同一时刻只有一个“当前激活”状态。
• 灵活切换：想新增任务用 /opsx:new；想续接之前的任务，直接输入 /opsx:continue <change-name>。
• 动态调整：即使已经进入编码阶段，你依然可以修改任何规划件（如 tasks.md），修改完成后再次运行 /opsx:apply，AI 会自动识别差异并更新实现。

十、结语

在这个 AI 编程效率百倍提升的时代，比“写得快”更重要的，是“控得住”。OpenSpec 提供的规格驱动流程，正是我们从“AI 编码”迈向“AI 研发管理”的关键一环。本文内容仅代表个人观点，不足之处，敬请谅解。

参考资料

• 项目代码：https://github.com/forever-project/feature-mode-temp
• OpenSpec 官方文档：https://github.com/fission-ai/openspec