夜雨聆风OpenSpec：为 AI 编码助手设计的轻量级规范框架
引言
AI 编码发展迅猛，从 GitHub Copilot 到 Claude Code，从 Cursor 到 Vercel v0，开发者有了越来越多的 AI 编程选择。然而，繁荣背后有一个核心痛点始终未解：AI 强大，但不可预测。
当你用自然语言描述一个需求，AI 生成的代码可能看起来没问题，运行却报错；可能功能实现了，但实现方式完全不是你预期的那样。问题的根源不在于 AI 不够聪明，而在于需求传递的模糊性——人类和 AI 之间缺乏一个共同的、书面的、可验证的协议。
OpenSpec 正是为解决这一问题而生。
一、为什么 AI 编程需要规范
传统的软件开发中，需求文档、设计文档是人类之间的共识载体。但在 AI 辅助编程中，AI 模型的上下文窗口是有限的，对话历史会越来越长，需求的细节会在多轮对话中逐渐漂移。
具体表现为三个常见问题：
1. 需求衰减：第一轮说的"登录要支持微信扫码"，到第五轮可能变成了"登录要调用微信 API"——具体是哪个 API、回调怎么处理，都模糊了。
2. 实现偏离：AI 倾向于生成"看起来正确"的代码，而不是"业务上正确"的代码。风格统一、语法正确，但与系统其他部分格格不入。
3. 变更失控：迭代过程中，AI 会不断基于之前生成的代码做修改，形成了隐式的"上下文依赖"——改一处，可能影响另一处，且不可预测。
OpenSpec 的思路是：在写代码之前，先建立一个规范层，让人和 AI 对"要做什么"达成书面的、精确的共识。
二、OpenSpec 的四大设计原则
OpenSpec 不是唯一一个 AI 编程规范工具，但它的设计原则使其与竞品形成了鲜明差异。
2.1 Fluid not Rigid
传统规范框架（如 Spec Kit）有严格的阶段门：先写 proposal，再写 specs，再写 design，最后才是 tasks。每个阶段完成后才能进入下一阶段。
OpenSpec 允许你按任意顺序创建产物，按需创建，不需要全部完成才能开始编码。可以在实现过程中更新 design 或 tasks，这种灵活性让规范工作自然融入开发节奏，而非额外负担。
2.2 Iterative not Waterfall
传统的瀑布式流程假设需求在开始时已经稳定不变。但实际上，软件开发的本质是"学习"——开发过程中对问题的理解会不断加深。
OpenSpec 拥抱这一现实：你可以在实现过程中随时回去更新 proposal、specs 或 design，无需推倒重来。变更文件夹中的所有产物都是"活"的。
2.3 Easy not Complex
对比一下各方案的初始化成本：
| 低 |
npm install -g @fission-ai/openspec@latest，然后 openspec init，整个过程不超过 10 秒。
2.4 Brownfield-first
大多数开发者的工作不是从零开始构建新系统，而是在存量代码库上修修改改。OpenSpec 的 Delta Spec 机制正是为这种场景设计的——它描述的是"相对变化"，而非完整规格。
三、核心机制：Delta Spec
Delta Spec 是 OpenSpec 最核心的创新。它不要求你重新描述整个系统的行为，而是聚焦于"这次变更是 ADDED（新增）、MODIFIED（修改）还是 REMOVED（移除）"。
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based 2FA.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed
## MODIFIED Requirements
### Requirement: Session Timeout
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)归档（archive）时，OpenSpec CLI 自动处理合并逻辑：
• ADDED → 追加到主规格文档 • MODIFIED → 替换对应条目 • REMOVED → 从主规格中删除
这种设计带来几个关键优势：
1. 多人并行：两个变更可以同时修改同一个规格文件，只要它们修改的是不同的 requirement，就不会有冲突 2. 变更可追溯：每个变更文件夹归档后完整保留，包含完整的上下文 3. 规格演进清晰：主规格文档是增量累积的，每个变更都有记录
四、Artifact 驱动的工作流
OpenSpec 的每个变更文件夹包含四类 Artifact（产物），它们各有分工：
Artifact 之间有依赖关系，但不强制顺序：
proposal（无依赖）
↓
specs（依赖 proposal） ←→ design（依赖 proposal）
↓
tasks（依赖 specs + design）这意味着：你可以跳过 design 直接做 tasks；也可以先写 design 再补 specs。工具服务于工作流，而非反过来。
五、生态与集成
OpenSpec 另一个显著优势是广泛的工具支持。
支持的 AI 编码助手（25+）：
Claude Code、GitHub Copilot、Cursor、Vercel v0、AWS Amazon Q、Cody（Sourcegraph）、Mistral Codestral、Replit Agent、CodiumAI、Kodezi…
安装要求：
• Node.js 20.19.0 或更高版本 • 支持 npm、pnpm、yarn、bun、nix
工作流命令：
• /opsx:propose— 创建新变更• /opsx:apply— 应用任务清单• /opsx:archive— 归档变更并合并规格• /opsx:list、/opsx:show、/opsx:validate— 查看和管理变更
结语
OpenSpec 解决的不是 AI 编程的"能力"问题，而是 AI 编程的"协作"问题。它不替代 AI 的代码生成能力，而是为这种人机协作提供了一个结构化的、可预测的框架。
规范不是束缚，而是让 AI 真正发挥价值的基石。当人和 AI 在写代码之前先对齐了期望，AI 就不再是那个"强大但不可预测"的助手，而是一个真正靠谱的协作者。
如果你正在使用任何主流 AI 编码助手，不妨试试 OpenSpec——一行命令即可开始。
