OpenSpec 能让变更意图、行为约束、设计判断和归档历史变得清楚，但它不是所有工作的默认入口。用得太少，重要变更会缺少上下文；用得太多，小事会被流程压重。

这篇只讨论 OpenSpec 自身的适用边界：什么时候值得创建 change，什么时候只需要轻量记录，以及 OpenSpec 与 Issue、普通文档、测试、代码注释之间分别是什么关系。

核心结论

判断是否需要 OpenSpec，可以先问一句：

如果只看最终代码 diff，未来的人是否还能理解这次变更的目标、边界、行为影响和验收标准？

如果答案是否定的，就值得使用 OpenSpec。否则，Issue、提交信息、测试用例或普通文档可能已经足够。

任务类型	是否适合 OpenSpec	原因
新功能	适合	需要先定义行为变化和验收标准。
重要修复	适合	需要说明原行为为什么错、新行为如何成立。
跨模块重构	适合	需要记录影响范围、兼容性和验证方式。
架构调整	适合	需要保留设计判断和取舍。
简单错别字	不适合	没有行为变化，直接修改更清楚。
低风险样式微调	通常不适合	如果影响面很小，Issue 或提交信息足够。
纯探索想法	暂不适合	还没有可验证 change 目标。
泛项目管理记录	不适合	OpenSpec 管行为变更，不替代项目管理工具。

OpenSpec 的边界不是“重要才写文档”，而是“行为变化需要被审查、实现和归档时，才值得进入 OpenSpec”。

适合使用 OpenSpec 的场景

新功能：先定义行为再实现

新功能通常会引入新的用户行为、系统承诺或边界条件。如果直接进入实现，团队很容易在代码完成后才发现目标不一致。

适合创建 change 的信号：

• 新增可观察能力。
• 需要明确哪些场景做、哪些场景不做。
• 涉及权限、兼容性、数据、状态或错误处理。
• 后续会继续演进，需要留下事实源。

例如“支持导出当前筛选结果”就适合进入 OpenSpec，因为它至少需要回答：谁能导出、导出什么、筛选条件如何生效、失败时怎么表现。

重要修复：把错误行为和新行为说清楚

Bug fix 不一定都需要 OpenSpec。修一个拼写错误或空指针防护，直接改可能更合适。

但重要修复适合使用 OpenSpec，尤其是：

• 原行为和预期行为存在争议。
• 修复会改变用户可观察结果。
• 需要新增回归场景。
• 修复会影响多个模块或兼容性。

好的修复 change 不只是写“修复 bug”，而是说明原行为为什么不成立、修复后系统必须满足什么 requirement，以及如何验证不会再次回退。

跨模块重构：记录不该变化的行为

重构常常声称“不改变行为”，但越是跨模块重构，越需要明确哪些行为必须保持不变。

OpenSpec 在这类工作中的价值是：

• 说明重构目标和非目标。
• 记录公共接口、数据流或兼容性边界。
• 明确哪些行为必须保持。
• 把验证重点写进 tasks。

如果重构没有任何外显行为变化，delta spec 可以很轻，但 proposal、design 和 tasks 仍然能帮助审查者理解为什么要重构、如何确认没有破坏行为。

架构调整：留下取舍和风险

架构调整通常不能只靠代码 diff 解释。未来的人需要知道当时为什么选择这个方案，为什么不选择其他方案，以及哪些风险已经接受。

适合进入 OpenSpec 的架构变更包括：

• 替换关键依赖或基础设施。
• 调整认证、权限、数据存储、缓存、队列、发布链路。
• 改变模块边界或公共接口。
• 引入需要长期维护的新技术约束。

这类 change 的 design.md 尤其重要。它不替代 spec，但能记录技术判断和验证重点。

不适合使用 OpenSpec 的场景

没有行为变化的小修小补

如果一次修改只涉及错别字、格式、无行为影响的注释、局部样式微调，创建完整 OpenSpec change 通常会增加成本。

可以直接使用：

• 提交信息说明。
• Issue 或 PR 描述。
• 简短代码注释。
• 局部测试或截图。

判断标准很简单：如果未来读者看 diff 和提交信息就能理解这次修改，OpenSpec 可能不是必要工具。

还没有收敛的探索

OpenSpec change 适合承载“准备实施的可验证变化”，不适合承载所有发散想法。

探索阶段常见状态：

• 还不知道问题是否存在。
• 还没有确定目标用户或使用场景。
• 只有几个方案猜测，没有明确取舍。
• 不知道是否会进入实现。

这时更适合用调研笔记、讨论记录或临时文档。等探索收敛成明确 change，再进入 OpenSpec。

泛项目管理记录

OpenSpec 不应该替代项目管理工具。它关注的是系统行为、变更意图、实现判断和归档事实。

不适合写进 OpenSpec 的内容：

• 人员排班。
• 会议纪要。
• 纯进度汇报。
• 没有行为影响的计划列表。
• 与系统事实无关的组织安排。

这些内容可以存在于 Issue、项目看板或团队文档中，但不应该污染 openspec/specs/ 或 change artifacts。

与其他工程材料的边界

OpenSpec 与 Issue

Issue 适合记录问题、讨论、优先级、指派和状态。OpenSpec 适合记录可实施变更的规范依据。

对象	更适合记录
Issue	问题发现、讨论过程、优先级、谁负责、当前状态。
OpenSpec change	变更目标、行为变化、设计判断、任务清单、归档历史。

一个 Issue 可以链接一个 OpenSpec change，但不应该把完整 spec 写在评论串里。评论适合讨论，OpenSpec 适合沉淀。

OpenSpec 与普通文档

普通文档适合解释系统如何使用、如何部署、如何排查问题。OpenSpec 适合解释行为事实和行为变化。

文档类型	适合内容
用户文档	面向使用者的操作说明。
运维文档	部署、监控、排障、恢复步骤。
架构文档	长期系统结构和关键约束。
OpenSpec	当前行为事实、change 过程、归档后的行为演进。

它们可以互相引用，但不要互相替代。用户手册不应该承载未实现的 change；OpenSpec 也不应该写成面向用户的完整使用手册。

OpenSpec 与测试

测试证明实现是否满足某些条件，OpenSpec 说明这些条件为什么存在。

测试回答：

• 这个行为现在是否通过。
• 某个边界是否被覆盖。
• 回归是否被防住。

OpenSpec 回答：

• 为什么需要这个行为。
• 行为边界是什么。
• 哪些场景必须成立。
• 变更完成后事实源如何更新。

好的实践是让 spec 场景能映射到测试或人工验收，而不是让测试替代 spec。测试可以失败或被重写，OpenSpec 应该保留行为意图和历史原因。

OpenSpec 与代码注释

代码注释适合解释局部实现为什么这样写。OpenSpec 适合解释系统行为为什么这样定义。

如果一个说明只对某几行代码有意义，写注释更好。如果一个说明影响需求、行为、兼容性、验收或归档历史，应该进入 OpenSpec。

例如：

内容	更适合位置
某个正则为什么这样写	代码注释。
为什么导出最多允许 10,000 行	OpenSpec spec 或 design，必要时再在代码附近引用。
某个缓存 key 为什么需要包含租户 ID	design 或代码注释，取决于影响范围。
用户无权限时必须看到什么提示	spec。

不要把长期行为约束藏在代码注释里，也不要把局部实现解释塞进 spec。

如何判断 change 粒度

是否使用 OpenSpec 之外，还要判断 change 粒度。

一个 change 通常应该有清晰目标和可验证结果。太大的 change 会让 proposal、spec、design 和 tasks 都变得含混；太小的 change 会让流程成本超过收益。

这里可以把“是否使用 OpenSpec”和“如何拆 change”分开看：

• 先判断这件事是否值得进入 OpenSpec。
• 再判断它应该是一个 change，还是拆成多个 change。
• 最后才把 change 拆成 tasks。

不要把 tasks 当成 change，也不要把一个长期计划塞进单个 change。

可以用下面的问题判断：

问题	如果答案是“是”
这次变更能否用一句话说明目标？	粒度可能合适。
是否有明确完成标准？	可以进入 OpenSpec。
是否涉及多个互不相关目标？	可能需要拆成多个 change。
是否只是一个实现步骤？	可能应该放进 tasks，而不是单独 change。
是否需要单独审查行为变化？	适合独立 change。

OpenSpec change 是工作单元，不是任务拆分的最小单位。一个 change 可以包含多个 tasks；一个大型计划也可以拆成多个 change。

过度使用的风险

OpenSpec 最大的误用，是把它变成“所有事情都必须填表”。

过度使用会带来几个问题：

风险	表现
流程成本过高	小改动也要写一堆 artifact，团队开始绕开流程。
内容质量下降	大量低价值 change 让真正重要的规范被淹没。
specs 失真	没有行为价值的内容进入事实源，后续更难维护。
审查疲劳	审查者无法区分重要 change 和普通杂项。

解决办法不是放弃 OpenSpec，而是建立门槛：只有当变更需要清晰行为边界、协作上下文或归档历史时，才创建 change。

轻量记录怎么做

不使用 OpenSpec，不等于不记录。

低风险工作可以用更轻的方式：

• 提交信息说明原因。
• Issue 描述问题和验收截图。
• PR 描述影响范围和验证命令。
• 测试名称表达行为意图。
• 代码注释解释局部非显然实现。

这些材料足够时，不需要额外创建 OpenSpec change。OpenSpec 应该保留给需要更强上下文和事实源维护的工作。

决策清单

创建 change 前，可以用这张清单判断：

检查项	判断
是否改变系统行为？	没有行为变化时，通常不需要 OpenSpec。
是否需要审查目标和非目标？	需要时适合写 proposal。
是否有可验证场景？	有场景才适合写 spec。
是否有设计取舍或风险？	有取舍时适合写 design。
是否需要跨多步推进？	需要时适合写 tasks。
是否需要归档为长期事实？	需要时适合完整 OpenSpec 流程。

如果这张清单里多数答案都是“否”，可以考虑轻量处理。如果多数答案是“是”，OpenSpec 通常能带来足够收益。

参考资料

• OpenSpec Concepts
• OpenSpec Workflows
• OpenSpec conventions spec

贡献者: sincerly90

上一页OpenSpec Schema 是什么