---
url: 'https://aisee.wiki/openspec/boundaries/index.md'
---
# OpenSpec 的适用边界

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](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md)
* [OpenSpec Workflows](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)
* [OpenSpec conventions spec](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/specs/openspec-conventions/spec.md)