OpenSpec:让 AI 编码助手不再＂凭感觉＂写代码

ℹ️ 说明：本文介绍 OpenSpec——一个开源的 CLI 驱动框架，用结构化规约文档（Spec）替代聊天记录，让 AI 编码助手按规约而非"直觉"工作。核心工作流仅四步：init → propose → apply → archive。支持 30+ AI 工具，不绑定平台，5 分钟即可上手。

AI 编码的"信任危机"

你大概有过这样的体验——

让 AI 帮你实现一个功能，它写出了能跑的代码，但和你想的完全不是一回事。你让它改，它改了东墙塌西墙。来回几轮对话后，你开始怀疑：到底是我在写代码，还是 AI 在带我飞？

这不是 AI 不够聪明，而是需求只存在于聊天记录里。AI 没有"记忆"你的完整意图，每次对话都是一场新的猜谜游戏。这种开发方式被社区戏称为 "Vibe Coding"——凭感觉编码，感觉对了就对了，感觉错了就推倒重来。

随着 AI 编码助手从"辅助工具"变成"主力输出"，这种工作方式的代价越来越大。一个小项目来回几次还好，一个中型项目几十个功能点，靠聊天记录管理需求，几乎注定失控。

OpenSpec 登场

OpenSpec（@fission-ai/openspec）是一个开源的、CLI 驱动的框架，它用一句话概括自己的使命：

先对齐，再编码。 (Agree before you build.)

它的核心思路很简单：在你让 AI 写代码之前，先用结构化的规约文档（Spec）把"要做什么"写清楚。AI 按照 Spec 去实现，而不是按照聊天记录去猜。

OpenSpec 由 Fission AI 创建，2025 年 8 月首次提交，不到一年时间在 GitHub 上收获了 50,400+ stars，成为 AI 开发工具领域增长最快的项目之一。

四个核心理念

OpenSpec 的设计哲学可以概括为四个关键词：

Fluid（流体）而非 Rigid（刚性）——规约可以随时更新，没有死板的阶段门禁
Iterative（迭代）而非 Waterfall（瀑布）——支持反复修改，不是一次定终身
Easy（简单）而非 Complex（复杂）——Markdown 文件 + CLI 命令，上手门槛极低
Brownfield（棕地）而非 Greenfield（绿地）——不仅适用于新项目，更关注已有代码库的渐进式接入

这四点精准击中了 AI 编码的痛点：你不需要重写整个项目，不需要学习新的编程语言，不需要改变现有工具链——只需要在 AI 和代码之间加一层"规约"。

核心概念速览

OpenSpec 的世界里只有几个关键概念：

Specs（规约）

描述系统当前行为的结构化文档。按领域组织，放在 openspec/specs/ 目录下。比如：

openspec/└── specs/    ├── auth/    │   └── spec.md      # 认证模块的行为规约    ├── payments/    │   └── spec.md      # 支付模块的行为规约    └── ui/        └── spec.md      # 界面交互的行为规约

每个 spec 包含需求（Requirements）和场景（Scenarios），使用 Given/When/Then 格式和 RFC 2119 关键词（SHALL、MUST、SHOULD）：

### Requirement: User Login#### Scenario: Successful login with valid credentialsWHEN the user submits valid email and passwordTHEN the system SHALL authenticate the userAND the system MUST redirect to the dashboard

Changes（变更）

每个功能需求或修改被包装成一个独立的 Change，放在 openspec/changes/ 目录下。每个 Change 是一个自包含的文件夹，包含一组制品（Artifacts）：

openspec/└── changes/    └── add-dark-mode/        ├── proposal.md    # 要做什么、为什么做        ├── specs/         # 对当前 spec 的增量修改        ├── design.md      # 技术方案        └── tasks.md       # 实现任务清单

Delta Specs（增量规约）

这是 OpenSpec 最精妙的设计之一。对于已有项目（棕地），你不需要重写整个 spec——只需要描述变更部分：

ADDED Requirements：新增的需求
MODIFIED Requirements：修改的需求
REMOVED Requirements：删除的需求
RENAMED Requirements：重命名的需求

归档时，OpenSpec 自动把这些增量合并回主 spec。

Artifacts（制品）

一个 Change 内的各个文档（proposal、specs、design、tasks）就是制品。它们之间有依赖关系，形成一个 DAG（有向无环图）：先有提案，再写规约变更，然后出设计方案，最后拆解任务。

工作流：四步走

OpenSpec 的核心工作流非常清晰：

init → propose → apply → archive

1. 初始化（init）

这一步会：

在项目根目录创建 openspec/ 目录结构
自动检测你用的 AI 工具（Claude Code、Cursor、Copilot 等）
为每个检测到的工具生成对应的 skill 文件和 slash 命令
创建 openspec/config.yaml 配置文件

2. 提议（propose）

AI 会：

创建一个新的 change 目录
按依赖顺序依次生成 proposal → specs → design → tasks
每一步都参考已有的 spec 和项目上下文

3. 执行（apply）

AI 按照 tasks.md 中的清单逐项实现，每完成一项标记为 done。

4. 归档（archive）

OpenSpec 自动将 delta specs 合并回主 specs，然后把 change 文件夹移到带日期的归档目录。

和 OpenAPI/Swagger 有什么关系？

完全没有关系。

这是一个高频误解。OpenAPI（原名 Swagger）是一个描述 REST API 接口的标准化规范，解决的是"API 长什么样"的问题。OpenSpec 解决的是"AI 应该按什么规约写代码"的问题。两者面向不同的问题域，可以互补使用——你可以用 OpenSpec 管理 OpenAPI 文档的生成规约。

30+ AI 工具的统一层

OpenSpec 不绑定任何特定的 AI 工具。通过适配器模式，它支持：

类别	工具
CLI	Claude Code、Gemini CLI、Codex CLI、Qwen Code、Amazon Q、OpenCode
IDE 插件	Cursor、GitHub Copilot、Windsurf、Cline、RooCode
新兴工具	Kilo Code、Auggie CLI、CodeBuddy、Crush、Factory Droid

当你运行 openspec init 时，它会自动检测你项目目录中存在哪些工具的配置文件，然后为它们生成对应的 skill 和命令。

五分钟快速上手

就这么简单。你不需要改变现有的开发流程，只是在 AI 和代码之间加了一层结构化的"对齐"。

总结

OpenSpec 解决的不是"代码怎么写"的问题，而是"AI 应该怎么理解你要写什么"的问题。它用轻量的 Markdown 文件 + CLI 工具，在 AI 编码的工作流中插入了一个"对齐层"：

人先把想法写进结构化的 spec
AI 按照 spec 而非聊天记录来实现
变更用增量方式管理，不重写全部
支持 30+ AI 工具，不绑定平台

在 AI 越来越深入编码工作流的今天，OpenSpec 代表了一种趋势：从"让 AI 猜"到"让 AI 按规约执行"。这不是倒退回瀑布流，而是给敏捷开发加了一个人机协作的"合同"。

下一篇文章，我们将深入 OpenSpec 的设计哲学，探讨为什么"流体"比"刚性"更好，以及背后的架构权衡。