OpenSpec 补上 Agent 任务约束层

OpenSpec 近期发布并持续迭代了一套轻量级 AI 规范框架，试图解决 AI 编程中一个越来越明显的问题：模型会写代码，Agent 也能调用工具，但它们经常没有稳定、可审查且能持续更新的任务边界。

**OpenSpec 是一个面向 AI 编程场景的开源规范驱动开发框架，它把需求、设计、任务和规范增量保存在代码仓库中，让开发者与 Agent 在动手改代码之前先锁定意图。**截至 2026 年 9 月 17 日，OpenSpec 已经开始在 Claude Code、Cursor、Codex 等 Agent 工作流的讨论中获得关注。

这不是又一个基础模型，也不是新的 Agent 通信协议。OpenSpec 更接近放在提示词和代码之间的“任务约束层”：上游接收人类提出的需求，下游约束 Agent 如何修改仓库，并把最终确认过的变化沉淀为项目当前规范。

AI Agent 缺的不是能力，而是任务边界

**当前 AI 编程最常见的失败并不是代码无法生成，而是 Agent 对“应该改什么”的理解在执行过程中发生漂移。**一句“给后台增加导出功能”，可能被 Agent 扩展为新增依赖、调整数据库字段、重构权限模块，最后交付一个能运行却不符合原始意图的实现。

传统提示词很难稳定解决这个问题。提示词通常描述当前对话中的要求，但随着 Agent 读取更多文件、调用更多工具和生成更多中间结果，最初的约束会逐渐被上下文稀释。即使模型拥有 200K 甚至更长的上下文窗口，也不等于它能在数十轮执行后继续正确分配注意力。

**任务约束层是位于自然语言需求与 Agent 执行之间的一组可持久化规则，用来明确目标、范围、验收条件和允许发生的变更。**它与模型的系统提示词不同，也与 CI/CD 的结果检查不同：前者在对话开始时提供指导，后者在代码完成后判断是否通过，而任务约束层贯穿提案、实施和归档全过程。

OpenSpec 的核心判断很直接：规范不能只存在于聊天记录里，也不能在代码写完后失效；规范应该和代码一起进入仓库，并成为后续修改的事实来源。

OpenSpec 怎么工作：先提案，再实施，最后归档

**OpenSpec 将一次代码变更拆成提案、实施和归档三个阶段。**这种流程并不新鲜，但 OpenSpec 的差异在于，它没有把流程包装成复杂的项目管理系统，而是使用 Markdown 文件、固定目录和 Agent 命令完成约束。

一个典型的 OpenSpec 项目会同时维护两类信息：

• specs/ 保存系统当前已经成立的规范，也就是当前事实；
• changes/ 保存尚未完成或尚未确认的变更提案，也就是候选事实。

其目录结构可以概括为：

openspec/
├── project.md
├── specs/
│   └── capability-name/
│       └── spec.md
└── changes/
    ├── change-name/
    │   ├── proposal.md
    │   ├── tasks.md
    │   ├── design.md
    │   └── specs/
    │       └── capability-name/
    │           └── spec.md
    └── archive/

**proposal.md 用于解释为什么要改、准备改什么以及哪些内容明确不改。**这一步的价值不是生成更多文档，而是迫使提出需求的人与 Agent 暴露理解偏差。如果提案阶段连范围都无法说清，直接进入编码通常只会让返工成本更高。

**tasks.md 是 Agent 可以逐项执行和核对的任务清单。**它把“完成某个功能”拆成有限步骤，使开发者能够判断 Agent 当前做到了哪里，而不是只能在几十分钟后检查一大批混杂提交。

**design.md 是按需出现的技术设计文件，而不是每次变更都必须填写的表格。**只有当修改涉及跨模块依赖、数据迁移、兼容策略或关键架构选择时，设计说明才真正有价值，这也是 OpenSpec 相对轻量的关键。

**增量规范描述的是本次变化相对于当前系统增加、修改或删除了什么。**它类似数据库迁移：开发阶段先保存差异，变更验收后再归档并合入主规范。这样做比让 Agent 每次重写完整需求文档更容易审查，也能降低无关内容被意外改写的风险。

“规范是真相，变更是提案”是最重要的设计

**OpenSpec 最值得关注的设计不是斜杠命令，而是将稳定规范与进行中变更分开。**普通需求文档常常在功能上线后迅速过期，代码逐渐成为唯一事实；OpenSpec 则试图让规范在每次归档后同步到当前状态。

这套机制可以压缩成三句话：

1. Specs as Source of Truth： specs/ 始终描述系统现在应当如何工作；
2. Changes as Proposals： 未完成的修改先进入 changes/，不能直接冒充现状；
3. Lock Intent Before Code： Agent 编码前先确认目标、范围和验收场景。

**这种“当前状态加变更增量”的模式比一次性生成一份大型 PRD 更适合已有代码库。**真实工程中的需求往往不是从零开始，而是在现有权限、接口、数据结构和兼容约束上做局部修改。Agent 只需读取当前规范与本次增量，不必每次重新理解整套产品。

例如，为已有文件导出功能增加 CSV 格式时，增量规范可以明确三项内容：新增 CSV 输出、保持原有 XLSX 行为不变、超过 10 万行时转为异步任务。这样的约束比“支持 CSV 导出”多了边界和验收条件，也比把整个导出系统重新描述一遍更节省上下文。

OpenSpec 与 Spec Kit、普通 Markdown 有什么区别

**OpenSpec 不是规范驱动开发领域的唯一方案，它的竞争力主要来自低仪式感。**GitHub 的 Spec Kit 更强调从宪章、规范、计划、任务到实施的完整工作流，适合从立项开始建立统一流程；OpenSpec 更关注已有项目中的单次变更，并允许开发者只在必要时补充设计内容。

| 方案 | 核心组织方式 | 默认流程重量 | 适合场景 | 主要优势 | 主要风险 | |---|---|---:|---|---|---| | OpenSpec | 当前规范与变更提案分离 | 较轻 | 已有代码库、持续小步变更 | 增量清晰，容易进入版本控制 | 依赖人工审查，复杂并行变更仍会冲突 | | GitHub Spec Kit | 宪章、规范、计划、任务、实施 | 较重 | 新项目、团队统一工程流程 | 阶段完整，治理边界明确 | 文档和上下文开销更高 | | 普通 Markdown 需求 | 团队自行约定文件 | 最轻 | 小团队、一次性任务 | 几乎没有学习成本 | 目录、状态和归档规则不统一 | | 仅使用聊天提示词 | 约束留在会话中 | 表面最轻 | 原型、短任务 | 启动速度快 | 不可追踪，跨会话容易丢失意图 |

**OpenSpec 与 Spec Kit 的差异不是“谁更先进”，而是对流程成本的取舍不同。**Spec Kit 试图提供一套相对完整的规范驱动方法，而 OpenSpec 更像可以嵌入现有仓库的薄层。对于只有两三名开发者、需求每天变化的团队，后者通常更容易真正执行；对于审计、合规和跨团队协作要求较高的项目，OpenSpec 本身可能还不够。

**OpenSpec 与普通 Markdown 的差异则在于状态模型。**团队当然可以手工创建 requirements.md 和 todo.md，但如果没有“当前规范、待实施提案、已归档变更”的明确边界，文档很快会再次退化为无人维护的附件。

它补的是约束层，不是执行层

**OpenSpec 无法保证 Agent 严格执行规范，它只能让偏差更容易被发现。**模型仍然可能误读需求、跳过任务、修改范围外文件，或者用一个看似通过测试的实现绕开真实业务条件。

这意味着 OpenSpec 不能替代以下工程设施：

• 自动化测试与回归测试；
• 代码审查和权限控制；
• 沙箱、容器与文件系统隔离；
• CI/CD 质量门禁；
• Agent 的工具调用审计；
• 针对仓库的上下文检索与长期记忆。

**AI 编程栈可以被粗略分成模型、工具协议、执行框架、任务约束和验证系统五层。**模型负责推理与生成，MCP 等工具协议负责连接外部能力，Agent Harness 负责规划和执行，OpenSpec 负责描述本次任务应该做什么，测试与 CI 则负责验证结果是否成立。

| 层级 | 解决的问题 | OpenSpec 是否覆盖 | |---|---|---:| | 基础模型 | 能否理解和生成代码 | 否 | | 工具与协议 | 如何连接文件、数据库、浏览器等工具 | 否 | | Agent 执行框架 | 如何规划、调用工具和循环执行 | 否 | | 任务约束层 | 应该改什么、不能改什么、如何验收 | 是 | | 测试与质量门禁 | 结果是否正确、安全、可部署 | 否 |

**把 OpenSpec 称为完整的 Agent 框架并不准确。**它不负责调度多个 Agent，不提供运行时沙箱，也没有解决模型权限控制问题；它真正补上的，是 Agent 开始执行前经常被省略的结构化约定。

轻量是优势，也可能成为上限

**OpenSpec 的最大优势是采用成本低。**规范文件可以直接进入 Git，变更能通过 Pull Request 审查，开发者不需要维护另一套与代码割裂的 SaaS 系统。框架本身也不按模型调用次数收费，实际成本主要来自团队维护规范的时间以及所使用模型的推理费用。

**OpenSpec 的最大风险是“写了规范”等于“完成治理”的错觉。**如果提案只是把用户的一句话扩写成三页套话，或者任务列表完全由同一个 Agent 生成并由它自己验收，那么流程增加了文件数量，却没有增加有效约束。

**长上下文开销也是规范框架无法回避的问题。**当仓库积累数百个能力规范和大量历史提案时，把所有文件一次性塞给模型会挤占代码上下文，并降低注意力质量。更合理的方式是按能力检索当前规范，只加载与本次变更相关的历史记录，再通过任务拆分保持每个执行回合足够小。

**并行变更会进一步考验 OpenSpec 的增量模型。**两个 Agent 如果同时修改同一能力，一个调整权限规则，另一个改变数据结构，文本层面的差异文件并不能自动解决语义冲突。团队仍然需要明确负责人、合并顺序和重新验证机制。

哪些团队现在值得尝试

**OpenSpec 最适合需求变化频繁、已经使用编码 Agent、但又不想引入重型流程的中小型开发团队。**这类团队通常已经感受到纯提示词开发的不稳定，却没有足够资源搭建完整的 Agent Harness 和内部知识平台。

以下场景能较快体现它的价值：

• Agent 经常擅自扩大修改范围；
• 同一需求需要跨多个会话或多天完成；
• 团队需要在 Pull Request 中审查需求，而不只是审查代码；
• 已有系统缺少持续更新的行为规范；
• 多个开发者或 Agent 需要围绕同一变更协作。

**一次性脚本、探索性原型和几个小时内废弃的实验不一定需要 OpenSpec。**在这些场景里，维护提案和归档的成本可能高于返工成本，直接使用简短任务清单反而更高效。

**高合规行业也不能只依赖 OpenSpec。**金融、医疗和关键基础设施项目仍需要需求签署、权限隔离、审计记录、测试证据与发布审批；OpenSpec 可以成为其中的输入格式，但不能代替正式治理系统。

判断：方向正确，但成败取决于能否保持克制

**OpenSpec 抓住了 Agent 工程化的真实缺口：模型能力增长得很快，任务定义和变更治理却仍停留在聊天框里。**当 Agent 从补全几行代码升级为连续工作数十分钟、修改几十个文件时，一份可版本化、可审查、可归档的任务契约就不再是额外负担，而是必要基础设施。

**OpenSpec 当前最合理的定位是“规范层积木”，而不是 AI 软件开发的终极答案。**它与模型、MCP、Agent Harness、Memory 和测试系统是互补关系：OpenSpec 定义意图，Harness 执行任务，Memory 保留经验，测试系统验证结果。

**OpenSpec 是否能长期成立，关键不在于增加更多模板，而在于保持轻量。**如果未来为了覆盖所有企业流程而不断增加阶段、角色和必填文档，它会重走传统需求管理工具的老路；如果它能坚持用少量结构表达目标、增量和验收条件，就有机会成为不同编码 Agent 之间通用的任务描述层。

官方目前没有公布 OpenSpec 相对纯提示词或其他规范框架的统一成功率、缺陷率和 token 消耗基准，因此暂时不能用跑分证明它能让 Agent “更聪明”。但它至少让失败变得更可解释：开发者可以判断问题来自需求没有写清、Agent 偏离提案，还是测试没有覆盖，而不是只能面对一段无法复盘的聊天记录。

参考来源

• OpenSpec 官方 GitHub 仓库：项目源码、安装说明、目录结构与规范驱动工作流的主要依据。
• GitHub Spec Kit 官方仓库：用于对比更完整的规范驱动开发流程及其阶段设计。
• Spec Kit 与 OpenSpec 实践讨论：开发者对上下文开销、流程复杂度和实际落地问题的经验讨论。