OpenSpec 是什么以及怎么用

2026年4月22日

OpenSpec 是什么以及怎么用

发布日期：2026-04-22
最后更新：2026-04-22
说明：本文是 OpenSpec 专题的总览入口，重点帮助读者快速建立对 OpenSpec 的整体认知。

先说结论

OpenSpec 可以理解为一套面向 AI 编码协作的 Spec-Driven Development 结构。
它试图解决的核心问题，不是“如何让模型更聪明”，而是：

  • 如何把需求讲清楚
  • 如何把变更范围显式化
  • 如何让 AI 在实现之前就获得稳定上下文
  • 如何在实现之后把事实重新归档

简单说，OpenSpec 更像一个 变更与规范管理系统，而不是单纯的 Prompt 模板集合。

一、OpenSpec 在解决什么问题

在没有 OpenSpec 的情况下，很多 AI 开发任务依赖的是：

  • 聊天记录
  • 人的临时描述
  • 局部代码上下文
  • 一次性的“你大概明白了吗”

这种方式在简单任务里可以工作，但一旦需求变复杂、协作方变多、改动时间线变长，就会出现这些问题：

  • 需求容易漂移
  • 变更边界不清楚
  • 同一个功能前后定义不一致
  • AI 只能“猜当前系统应该是什么样”

OpenSpec 的思路是：
把这些原本散落在聊天和脑中的信息，沉淀成结构化 artifact。

二、OpenSpec 的核心结构

典型的 OpenSpec 结构大致是这样：

openspec/
├── specs/                    # 当前系统事实
├── changes/
│   └── <change-name>/
│       ├── proposal.md       # 为什么做
│       ├── specs/            # 要改哪些行为
│       ├── design.md         # 怎么实现
│       └── tasks.md          # 分步任务
└── config.yaml

这几个部分分别回答不同问题：

  • specs/
    描述系统当前已经成立的行为事实

  • proposal.md
    描述这次变更为什么存在

  • spec delta
    描述系统行为要怎样变化

  • design.md
    描述技术实现思路和关键决策

  • tasks.md
    把实现拆成可执行步骤

这也是 OpenSpec 最关键的地方：
它不是让 AI 直接从一句需求跳到代码，而是让 AI 先穿过一层结构化 artifact。

三、它的工作流长什么样

flowchart LR
    A[提出变更意图] --> B[proposal]
    B --> C[spec delta]
    C --> D[design]
    D --> E[tasks]
    E --> F[AI / 人执行实现]
    F --> G[验证]
    G --> H[archive 回写 specs]

这个流程的意义在于：

  1. 先定义意图
  2. 再定义行为变化
  3. 再定义实现方式
  4. 最后才进入代码实现

这会让 AI 的实现不再只依赖即时对话，而是建立在更清晰的输入对象上。

四、OpenSpec 最适合什么场景

它最适合下面几类场景：

4.1 存量系统持续迭代

当系统已经运行了一段时间，功能之间有依赖，需求也不是单文件小改时，OpenSpec 很适合把每次变更单独抽出来管理。

4.2 多人、多角色协作

如果产品、前端、后端、测试都需要围绕同一份行为定义协作，那么 spec 可以成为共享事实，而不是只存在于某个开发者的理解里。

4.3 跨仓库共享规范

这也是我后面单独写 跨仓库AI协作方案-Spec与上下文工程 的原因。
一旦规范不再只服务一个仓库，OpenSpec 的价值会更明显。

4.4 需要可追溯的 AI 交付链路

如果你希望未来能回看：

  • 当时为什么这么改
  • 这次变更到底改了哪些行为
  • AI 是基于什么上下文实现的

那 OpenSpec 的 artifact 结构会比纯聊天式开发更有优势。

五、OpenSpec 不擅长什么

OpenSpec 很有用，但它也不是万能的。

它不太适合：

  • 纯一次性的小修小改
  • 团队完全没有维护 artifact 的意愿
  • 只想“马上开始写代码”，不愿意先做结构化定义

因为它的优势本来就建立在一件事上：
先把变更管理做清楚，再把实现交给 AI

如果团队没有这个前提，它很容易退化成“多了一堆没人维护的文件”。

六、怎么和其他上下文工程一起用

在我的使用里，OpenSpec 通常不是单独存在的。
它更适合和下面这些东西一起组成上下文工程体系：

  • AGENTS.md
    负责“怎么写”

  • OpenSpec
    负责“写什么”

  • MCP
    负责连接数据库、文档、接口、日志等外部事实

从这个角度看，OpenSpec 更像是中间那层：
它把变更定义收住，再把这些定义交给 Agent 去执行

七、如果你准备开始用 OpenSpec

我更建议按这个顺序开始：

  1. 先在一个中型需求上试一次完整 change 流程
  2. 不要一上来就覆盖全项目
  3. 先把 proposal / spec delta / tasks 写清楚
  4. 再让 AI 基于这些 artifact 实现
  5. 完成后归档回 specs/

最开始，重点不是“把所有模板都写得很完整”，而是让团队先体会到一件事：

当需求和变更被写清楚之后，AI 的实现质量会更稳定，审查成本也会更低

延伸阅读