编写优质规范
你很少会从空白页面开始编写规范。你只需用平实的语言描述变更，/opsx:propose 就会自动起草需求和场景，之后你再将其打磨完善。本文聚焦于最后一步——明确“优质规范”的标准，以及如何引导AI产出符合要求的草稿。本文是审查变更的配套文档：审查是找出草稿中的薄弱点，而编写则是明确一份扎实的规范应该具备哪些要素。
规范描述行为，而非代码
规范描述的是系统做什么，是任何人都可以核查的行为说明，而非系统的构建方式。规范由需求（行为声明）和场景（证明需求成立的具象示例）两部分组成。
markdown
### 需求：会话超时
系统 SHALL 在会话闲置30分钟后将其过期。
#### 场景：闲置超时
- GIVEN 一个已认证的会话
- WHEN 会话闲置30分钟无任何活动
- THEN 会话失效，用户必须重新认证实现细节（比如队列、依赖库、表结构）请保留在 design.md 或代码中。当行为与实现被混入同一个需求时，该需求将不再可测试，且会在代码变更的瞬间就变得过时。
优质需求的构成
优质需求是对单一行为的声明，表述足够直白，你可以把它交给其他人直接进行测试。
一条声明，一个
SHALL/MUST。 如果一个需求包含三个“此外还有”的从句，那它实际上就是三个需求，需要拆分。可观测。 非代码相关人员也能判断该需求是否成立。“系统 SHALL 在上传文件超过10MB时显示错误横幅”是可观测的；“系统 SHALL 优雅处理大文件上传”则不是。
合适的强度。 OpenSpec 使用RFC 2119定义的关键词，不同关键词的含义不同：
关键词 含义 MUST/SHALL强制性要求，没有协商余地。 SHOULD强烈建议，但在有合理理由的情况下可以例外。 MAY真正可选。 默认优先使用
MUST/SHALL。只有当你确实想表达“除非有充分理由否则必须遵守”时，才使用SHOULD。
需求的检验标准是：从未接触过代码的测试人员能否判断该需求是否通过？ 如果答案是否定的，说明需求需要进一步打磨。
优质场景的构成
场景是需求发挥价值的地方。每个场景都是具体的 GIVEN / WHEN / THEN 结构，可以直接转化为自动化测试。
- 覆盖对应需求。 只是用其他措辞复述需求的场景没有任何测试价值，需要将其设定为带有明确结果的具体情境。
- 覆盖关键场景，而非仅覆盖正常流程。 合法的登录场景很容易编写，但空输入、过期令牌、重复点击、异常情况才是bug的藏身之处，也是场景价值最高的地方。
- 在标题中明确场景名称。 “场景：拒绝过期令牌”能让审查者一眼看出覆盖的内容，而“场景：测试2”则做不到。
一个好习惯：在批准变更前，先问自己“如果哪个场景出问题我会最不满？” —— 并确保该场景已经被明确命名覆盖。
选择合适的变更类型
变更通过三种章节类型描述对规范的修改，选择正确的类型才能保证归档后的规范准确可信：
## ADDED Requirements— 此前不存在、全新添加的行为。## MODIFIED Requirements— 已存在、正在变更的行为。需要包含完整的新版本内容；附上一句简短的变更说明能帮助审查者快速理解。## REMOVED Requirements— 即将移除的行为，需要说明移除原因。
归档时，ADDED 内容会被追加到主规范中，MODIFIED 会替换旧版本，REMOVED 则会被删除。如果把真实变更标记为 ADDED，最终会出现两条冲突的需求；如果把新行为描述为 MODIFIED，则没有可替换的旧内容。如有疑问，打开当前规范查看该需求是否已经存在即可。
控制变更规模
编写规范时最常犯的错误不是措辞糟糕的需求，而是一个变更试图涵盖三个变更的内容。优质变更只有一个核心意图，可以用一句话说清楚。 比如“添加深色模式切换开关”“对登录接口做速率限制”“将会话存储从Cookie迁移走”。如果描述变更时需要大量使用“此外还有”，这就是需要拆分的信号。
变更过大的迹象：
- 提案的范围看起来像是一系列不相关的功能列表。
- 审查这个变更需要整整一个下午，没人愿意做。
- 两个人无法同时协作开发，会产生冲突。
- 一半的任务可以独立交付。
更小的变更更容易审查，更容易在一次专注的开发会话中完成，也更容易在六个月后只剩归档内容时快速理解。你完全可以并行推进多个变更——详见编辑与迭代和工作流。
反过来也会出现过度设计的情况：修复一行拼写错误不需要写三条需求加一份设计文档。流程的复杂度要和变更的影响范围匹配。
如何引导AI产出优质草稿
由于 /opsx:propose 负责生成初稿，你得到的结果质量和你输入的内容质量直接相关。你不需要手动编写需求，只需要精准引导AI即可：
- 明确意图和边界。 “添加深色模式切换开关，首次加载时跟随系统设置——不要修改现有的主题API。” 范围外的要求和范围内的要求同样重要。
- 明确你关心的场景。 “确保覆盖手动选择过主题的用户的场景。” AI只会覆盖你指出的内容。
- 然后编辑。 规范就是普通的Markdown格式，你可以收紧模糊的
SHALL表述，删除没有测试价值的场景，补充它遗漏的用例——也可以直接要求AI修改：“超时需求的表述太模糊，把它明确为30分钟。”
起草、打磨、重复。经过几轮这样的操作，就能产出一份你信得过的规范，这就是整个流程的意义所在。
快速检查清单
- [ ] 每个需求都是带有
SHALL/MUST的可观测行为。 - [ ] 需求中没有嵌入实现细节。
- [ ] 每个需求至少有一个能真正覆盖它的场景。
- [ ] 重要的边界和异常场景都有对应场景，而非仅覆盖正常流程。
- [ ] 变更类型（ADDED/MODIFIED/REMOVED）相对于当前规范的使用是正确的。
- [ ] 整个变更只有一个可以用一句话说清楚的核心意图。