OpenSpec v1.13.0 – 轻量级、可配置的 AI 规范框架

OpenSpec v1.13.0 – 轻量级、可配置的 AI 规范框架

要点： OpenSpec v1.13.0 提供了一种低开销的方式，利用 AI 代理来编写、管理和验证软件规范。然而，从业者警告称，在大型且不断演进的代码库中，可能会出现规范漂移、工件生成过多以及审查负担过重等问题。

---

OpenSpec 旨在解决的问题

• 目标： 使团队与 AI 编码代理在构建内容和构建方式上保持一致，从而减少错误实现。
• 核心理念： 编写规范（例如 proposal.md、design.md、tasks.md），并让该框架驱动一个可重复的工作流：探索 → 提案 → 实现 → 验证 → 归档。
• 支持的工具： Claude Code、Codex、Cursor、GitHub Copilot、Gemini、CLI、OpenCode 以及其他 33 种以上工具（详见官方文档）。
• 当前状态： v1.13.0，GitHub 获得 68.8k 星标，开源地址：https://github.com/Fission-AI/OpenSpec/。

---

工作流结构

阶段	命令	目的
探索 (Explore)	/opsx:	映射问题空间并理解现有代码库。
提案 (Propose)	/opsx:	生成 proposal.md、specs/、design.md、tasks.md。
实现 (Implement)	/opsx:	执行从规范中派生的任务。
验证 (Verify)	/opsx:	检查实现是否符合规范。
归档 (Archive)	/opsx:	存储已完成的变更以供将来参考。

该框架非常精简：它不规定语言或构建系统，仅提供一组基于 Markdown 的工件和一个编排 LLM 调用的 CLI。

---

社区反馈 – 赞誉与痛点

正面评价

• 流程规范有所帮助 – 用户 @mafro 指出，即使他们放弃了规范文件本身，流程（提案 → 审查 → 实现 → 审查）依然具有价值。
• 迭代式规范可行 – @jmathai 报告称，一个 471 行的规范被代理成功实现且没有问题，凸显了其在大规模功能生成方面的潜力。
• 存在轻量级替代方案 – @pramodbiligiri 构建了一个类似的工具 (shipsmooth)，每个工作单元仅创建一个规范和任务文件，强调了极简主义。

主要批评

• 规范与代码脱节 – @mafro 观察到在数月开发后，代码与规范之间出现了“巨大的分歧”，并得出结论：“代码本身就是规范”。
• 工件爆炸 – 多位评论者（如 @whinvik、@open‑paren）抱怨 OpenSpec 生成了过多的 Markdown 文件，导致审查变得繁琐，并增加了文档过时的风险。
• 缺乏理论基础 – @ricardobeat 指出，文档侧重于用法，而没有解释该框架为何有效或提供基准测试。
• 与旧方法的对比 – @twen_ty 询问 OpenSpec 与 20 世纪 90 年代的 UML 转代码流水线有何不同，并指出“规范漂移”仍然是一个根本性问题。
• 采用阻力 – @gps372 警告称，对于那些已经被 JIRA、SharePoint 等工具淹没的组织来说，如果没有领导层的支持，OpenSpec 将很难推广。
• 以人为本的担忧 – @hmokiguess 认为 AI 在“写作”方面仍然优于“阅读”，真正的瓶颈在于人类的决策；像 OpenSpec 这样的框架仅解决了一个“锦上添花”的工作流层。

---

实际使用模式

• 个人或小型团队项目往往能从结构化工作流中受益，特别是当规范保持简短并与实现紧密耦合时。
• 大型、多开发者代码库容易出现“规范腐烂”，即文档变得陈旧；审查者最终在规范审查上花费的时间比在代码审查上还要多。
• 混合方法正在兴起：一些团队保留用于高层意图的轻量级规范，同时依赖 ADR、不变性日志和单元测试来提供具体保证（正如 @mafro 所述）。
• 工具集成：用户经常将 OpenSpec 任务列表通过管道传输到自定义脚本中（例如 @recroad 的 Bash 循环），以减少 Token 使用量并保持每次 LLM 调用的小型化。

---

与相关框架的对比

框架	主要关注点	Token 效率	工件管理
OpenSpec	迭代式 Markdown 规范 + CLI 编排	中等 – 每一步都是独立的 LLM 调用	每个功能生成多个 Markdown 文件
GSD (opengsd.net)	端到端可追溯性，自主模式	高 Token 消耗 (~4×)	集中式项目管理器，文件较少
SpecKit / SpecDD	系统组件边界与变更流程	因实现而异	最小重叠；更专业化
Spekk‑CLI	声明式规范，可安装的代理技能 (Go 二进制文件)	低 – 单个二进制文件，无运行时依赖	每个单元一个规范 + 任务

---

实践建议

1. 从小处着手 – 在扩展到整个仓库之前，先在单个功能或原型上使用 OpenSpec。
2. 将规范与 ADR 和不变性日志结合 – 这通过记录无法在单元测试中捕获的决策来减轻漂移。
3. 自动化审查 – 编写“规范到代码差异”检查脚本（例如在生成的文件上使用 git diff），以便尽早发现过时的工件。
4. 定义“快速通道” – 对于微小的变更，跳过完整的规范生成，使用轻量级计划，正如 @cg‑enterprise 所建议的那样。
5. 监控 Token 使用量 – 将大型任务列表拆分为小块；对相关步骤重用相同的 LLM 上下文，以保持在模型限制内。

---

展望

OpenSpec 表明，一个轻量级的、以 Markdown 为中心的规范层可以与现代 LLM 编码代理集成。社区的混合反馈突显了两个待解决的挑战：

• 在长开发周期中保持规范的保真度。
• 在工件粒度与人类审查带宽之间取得平衡。

未来的版本需要更强大的规范版本控制、自动陈旧检测以及与现有项目管理工具的集成，才能成为重量级问题跟踪器的可行替代方案。