小鹅通开头
如果你最近在用 Cursor、Codex 这类 AI 编程工具，八成遇到过一种“无力感”：模型确实能写出像模像样的代码，但总在某些细节上跟你理解的不一样。你要的是“给用户提醒过期时间”，它给你封装了一个完整的定时器系统；你强调“不要动现有接口”，它还是会顺手把函数签名改掉。问题不在模型能力，而在于你给 AI 的“约束”太弱了——提示词里的要求是软性的，对话上下文也会被截断，真正的项目规约根本没传递到生成链路里。OpenSpec 这个规约框架，就是冲着这个问题来的。它是一个专门给 AI 代码生成场景设计的结构化规约管理工具，用一套文件级、可提交、可回滚、可验证的规格说明（Changeset）来约束 Agent 的行为边界，让“需求—设计—任务—实施”这条链路对模型完全可见、可循证。这篇内容我结合实际使用经验，把 OpenSpec 的设计思路、安装方式、和 Cursor/Codex 的配合方法，以及我踩过的坑，一次性讲透。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
1. 为什么需要 OpenSpec：AI 生成的代码缺的不是能力，是“边界”
1.1 AI 编码的真正瓶颈：上下文失控
很多人以为 AI 编程工具好不好用，取决于模型参数量大不大。真入行做了几个项目之后，你会发现更大的瓶颈是：Agent 对项目的理解是“一次性快照”式的。它基于你当前打开的若干文件、聊天记录里的对话历史、以及系统提示词来推断需求，而不是基于一份完整的、可追溯的项目规约。
拿我前段时间做的一个内部工具举例，需求很简单：在现有用户模块上增加一个“导出 CSV”的功能。我让 Cursor 自动实现，结果是模型自己“脑补”了权限控制、异步任务队列、日志上报，还顺手把原来的 API 返回结构改了。单看每一处改动都有道理，但合在一起就是一场灾难。这背后的本质是：自然语言提示词无法形成结构性约束。你说“尽量不改动现有逻辑”，模型理解成“保留函数名就行”，可它不知道哪些变量、字段、依赖关系是团队约定的红线。
1.2 从“提示词”到“可执行的规约”
OpenSpec 的思路是：把给 AI 的约束从“聊天里的几句话”变成“项目里的一组文件”。这组文件就是 Changeset（变更集），里面按固定规则写明：这次变更要解决什么问题、涉及哪些模块、必须保留哪些行为、验收标准是什么。Agent 在动手前先读这些文件，相当于拿着一张施工图去干活，而不是凭印象边猜边写。
这个思路并不新鲜——传统软件工程里的需求规格说明书、接口契约测试都是类似逻辑。但 OpenSpec 的厉害之处在于，它把这些规约做成了可以被 Agent 和命令行工具共同消费的格式：既能被 Cursor 这类 IDE 插件读取，也能被 Git Hook 和 CLI 在提交时校验。换句话说，规约不再是“写完就躺进 wiki 的文档”，而是参与了代码生成和审查流程的活体约束。
注意：OpenSpec 不是一个代码生成器，它不负责把需求翻译成代码。它负责的是“需求、设计与任务”结构化，让 AI 在生成代码时有一个明确且不可忽略的基准线。
1.3 适用场景与目标用户
如果你属于下面几类情况，OpenSpec 大概率适合你：
- 使用 AI 编码工具做多文件、跨模块功能开发，但经常被模型“跑偏”搞烦的开发者。
- 团队里 AI 生成代码的比例越来越高，需要一种机制来保证代码风格、接口设计和架构约束不被破坏。
- 做 AI Agent 相关项目，想给 Agent 设置一套可追踪、可回滚的“操作契约”。
反过来，如果你只是偶尔让 AI 补一段几十行的工具函数，OpenSpec 属于杀鸡用牛刀。它的价值在“多步骤、多文件、涉及既有代码改动”的场景里才真正体现。
2. OpenSpec 的核心设计：一切皆 Changeset
2.1 概念拆解：项目、变更集、规格、任务
OpenSpec 的操作对象可以拆成四个层级，理解了这四个词，整个框架就掌握了大半：
- 项目（Project）：一个 Git 仓库就是一个项目，OpenSpec 在项目根目录下的
.openspec目录里存所有规约状态。 - 变更集（Changeset）：一次功能开发或缺陷修复对应的结构化描述，它是一组文件的集合，放在
.openspec/changesets/<名称>/目录下。 - 规格（Specification）：变更集里的
spec.md文件，用 Markdown 但带有固定的标题约定（比如 Requirements、Design、Tasks、Acceptance Criteria），规定了这次变更“做什么、为什么做、怎么做、做到什么算完”。 - 任务（Task）：
tasks.md里拆解出来的具体实施步骤，可以对应到实现、测试、文档等操作。AI Agent 通常按这里列出