OpenSpec: AI 编程规范工具

OpenSpec 在目前的开发语境中通常指代 Fission-AI 推出的一款面向 AI 编程助手（如 Cursor、Claude Code、GitHub Copilot）的规范驱动开发（Spec-Driven Development, SDD）工具。

什么是 OpenSpec？

OpenSpec 是一个轻量级的开源命令行工具（CLI）和工作流规范。它充当了你（人类）和AI 编程助手之间的翻译官和契约。 OpenSpec的核心目的是解决 AI 编程时随意发挥或听不懂人话的问题，通过强制先写规格说明书（Spec）再写代码，让 AI 的输出更加可控、精准。

• 痛点：通常我们直接让 AI “加一个登录功能”，AI 可能会写出不符合项目结构、遗漏边界条件的代码（所谓的 “Vibe Coding”）。
• 解决方案：OpenSpec 强制要求在写代码前，先生成一份结构化的提案（Proposal）和任务清单（Tasks）。你确认无误后，AI 才会根据这份契约去写代码。
• 适用工具：Cursor, Claude Code, Windsurf, GitHub Copilot 等。

核心工作流 (The Workflow)

OpenSpec 的使用主要围绕三个核心命令（或步骤）进行，形成闭环：

1. Proposal (提案)：告诉 AI 你想做什么，让它先写计划。
2. Apply (执行)：让 AI 根据计划写代码。
3. Archive (归档)：功能完成后，将这次变更的规格归档，成为项目永久文档的一部分。

如何安装和初始化

安装

OpenSpec 是一个 Node.js 工具，可以直接通过 npm 安装：

npm install -g @fission-ai/openspec

初始化项目

在你的项目根目录下运行：

openspec init

# 继续如下提问，完善
请阅读 openspec/project.md 并帮助我填写有关项目、技术栈和约定的详细信息

这会生成一个 .openspec/ 或 openspec/ 目录，里面包含：

• project.md：项目的全局上下文（技术栈、代码规范、架构原则）。这是最重要的文件，你需要根据项目实际情况修改它，AI 会依据它来工作。
• AGENTS.md：给 AI 看的指令集，教它如何遵守 OpenSpec 的规则。

内置了OpenSpec命令

Kilo Code会自动发现团队工作流。将生成的文件保存在 .kilocode/workflows/ 目录下，并通过命令面板使用 /openspec-proposal.md、/openspec-apply.md 或 /openspec-archive.md 触发它们。

openspec/project.md、openspec/AGENTS.md 和根目录下的 AGENTS.md 区别

openspec/project.md (项目真理来源)

• 角色：项目上下文与技术规范 (Context)。
• 内容：
  • 技术栈定义：用什么语言、框架、库（如 TypeScript, React, Next.js）。
  • 架构设计：目录结构、模块划分、数据流向。
  • 编码规范：命名规则、代码风格、Linter 规则。
  • 业务背景：项目是做什么的，核心业务逻辑是什么。
• AI 的视角：在这个项目里写代码，我需要遵守哪些技术约束？引用哪些库？
• 变动频率：中等（随着项目架构迭代而更新）。

openspec/AGENTS.md (操作协议核心)

• 角色：OpenSpec 工作流手册 (Protocol)。
• 内容：
  • 工作流程：定义了 Proposal（提案） -> Apply（应用） -> Archive（归档）的标准生命周期。
  • 工具指令：教 AI 如何调用 CLI 命令（如 openspec new, openspec validate）。
  • 格式要求：规定 markdown 规范文档必须怎么写（Frontmatter 格式、Feature/Tech Design 章节）。
• AI 的视角：作为一名使用 OpenSpec 的 AI 员工，我该如何提交提案？我该执行什么步骤来完成任务？
• 变动频率：极低（通常只在升级 OpenSpec 工具版本时更新）。

根目录 AGENTS.md (入口索引)

• 角色：上下文锚点 / 重定向 (Entrypoint)。
• 内容：
  • 极简的声明。
  • 强制指令：要求 AI 忽略自身的默认行为，转而读取 openspec/ 目录下的配置文件。
• AI 的视角：我刚打开这个项目，这里有什么特殊规矩吗？哦，文件告诉我去看 openspec 目录。
• 变动频率：几乎不变（除非你移除了 OpenSpec）。

横向对比表

AI 工作时的读取顺序

当你在编辑器（如 Cursor/Windsurf）中开始一个新任务时，实际的数据流向是这样的：

1. 第一步（握手）：AI 扫描根目录，看到 ./AGENTS.md。
   • AI 反应：收到，本项目启用了 OpenSpec 规范，我需要去查阅详细文档。
2. 第二步（学习流程）：AI 读取 openspec/AGENTS.md。
   • AI 反应：明白了，如果要修改代码，我不能直接写，必须先创建一个 spec 提案文件，并遵循特定格式。
3. 第三步（理解背景）：AI 读取 openspec/project.md。
   • AI 反应：好的，这个项目用的是 React 19 和 Tailwind，我在写代码时会遵循这些技术栈。
4. 第四步（执行）：AI 结合上述信息，开始生成符合规范的提案或代码。

示例：

• https://github.com/Fission-AI/OpenSpec/blob/2e51ae26d3ab51ea18c2a3c81230d52cc74abe3c/AGENTS.md?plain=1#L6
• https://github.com/Fission-AI/OpenSpec/blob/2e51ae26d3ab51ea18c2a3c81230d52cc74abe3c/openspec/AGENTS.md
• https://github.com/Fission-AI/OpenSpec/blob/2e51ae26d3ab51ea18c2a3c81230d52cc74abe3c/openspec/project.md

具体使用步骤演示

假设你要在一个 React 项目中添加黑暗模式。

第一步：提出提案 (Proposal)

在 Cursor 或 Claude Code 的对话框中，输入类似以下的指令（如果你配置了 Slash Command）：

“我想添加黑暗模式支持，请创建一个 OpenSpec proposal。”

或者在终端运行 openspec proposal。

AI 会生成以下 Markdown 文件（通常在 openspec/changes/ 目录下）：

• proposal.md: 描述为什么要改，改什么。
• design.md: 详细的设计思路（比如使用 Context API 还是 CSS 变量）。
• tasks.md: 一步步的执行清单（TODO List）。
• specs/: 具体的规格变更（新增了什么需求，修改了什么逻辑）。

你的工作：阅读这些文件。如果 AI 的设计不对（比如你想用 Tailwind 但它设计的是原生 CSS），现在就让它改文档，而不是等它写完代码再改。

第二步：执行代码 (Apply)

当你对 Proposal 满意后，告诉 AI：

“Proposal 看起来不错，请执行 Apply。”

或者运行相关命令。AI 会读取 tasks.md，一项一项地去修改项目源码。因为它已经有了详细的设计文档，写出的代码通常准确率极高。

第三步：归档 (Archive)

代码写完并通过测试后，你需要告诉 AI：

“功能已完成，请 Archive。”

OpenSpec 会将这次变更的规格（Spec）合并到项目的主规格文档中，并清空临时的变更文件夹。这样，你的项目不仅有了代码，还有了一份始终与代码同步的最新技术文档。

示例命令

# 查看活跃的变更文件夹
openspec list

# 规范和变更的交互式仪表板
openspec view

# 显示变更详情（提案、任务、规范更新）
openspec show <变更名称>

# 检查规范格式和结构
openspec validate <变更名称>

# 将完成的变更移动到archive/（使用--yes为非交互式）
openspec archive <变更名称> [--yes|-y]

示例目录

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 当前认证规范（如果存在）
└── changes/
    └── add-2fa/              # AI创建整个结构
        ├── proposal.md       # 为什么和什么变更
        ├── tasks.md          # 实施清单
        ├── design.md         # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md   # 显示添加内容的增量

为什么要用它？

1. 不再抽卡：AI 不会随机生成代码，而是严格遵循设计文档。
2. 上下文记忆：传统的 AI 聊天记录一多就会遗忘之前的要求。OpenSpec 把要求固化在 Markdown 文件里，AI 随时可以查阅。
3. 自动维护文档：开发过程就是写文档的过程，项目永远有一份最新的 project.md 和规格说明。
4. 无 API Key：它主要是一个本地的规范和文件结构，不依赖特定的昂贵云服务（使用你原本的 AI 订阅即可）。

总结

如果你经常觉得 AI 编程助手写出来的代码不能用或者逻辑混乱，OpenSpec 就是为了解决这个问题而生的。它用**先思考，后行动**的策略，强迫 AI 变得更加严谨和工程化。