北京时间 2026 年 10 月 31 日，开源 AI 编程规格工具 OpenSpec 发布 1.16.0，为需求场景增加步骤完整性检查，并修复了无效配置被忽略的问题。对已经让 AI 写需求、拆任务和改代码的开发者来说，这次更新值得关注，因为一份排版漂亮的需求文档，仍可能没说清“什么情况下，应该出现什么结果”。本文用一个 CSV 导出的例子，说明新检查能拦住哪些遗漏、怎样试用，以及为什么校验通过仍需要人工验收。

[配图建议：一份需求文档被放大镜检查，缺失的结果框由黄色纸片补齐；紫色纸张与荧光黄点缀的编辑插画风格。]

OpenSpec 1.16 需求场景检查概念封面：把验收条件写清楚

原创 AI 生成概念图，用于解释流程，并非软件界面或测试结果。

一、新增检查，先把“场景写了一半”找出来

OpenSpec 的基本做法，是把需求和场景保存在 Markdown 文件里，先与 AI 对齐计划，再进入实现。官方流程会组织提案、规格、设计和任务清单；开发者可以打开文本逐项修改，而不必只依赖一段越来越长的聊天记录。这是项目已有的工作方式，并非 1.16 才出现的能力。来源：固定版本项目说明

这次新增的是一个更具体的检查：当 Scenario: 中没有 WHEN/GIVEN 步骤，或没有 THEN 步骤时，openspec validate 会给出警告；检查覆盖变更中的规格增量和主规格。这里不能把“WHEN/GIVEN”理解成两者缺一不可，发行说明表达的是缺少这一类步骤。来源：1.16.0 发行说明

最容易误读的地方，是把新增警告当成默认阻断。

情况 1.16 的处理方式 团队应怎样理解
场景缺少上述步骤，普通校验 给出警告 需要阅读输出，不能只看命令结束
同类问题，严格校验 --strict 因警告失败 可以把这类遗漏作为检查关卡
配置文件不可读或不是有效 YAML validate 退出码为 1 应先修复配置，再谈规则是否生效

对于新增的场景警告，普通校验和归档流程的原有通过行为并未变成强制拦截；配置错误则是另一种失败条件。因此，升级版本和启用严格模式，是两个不同的决定。来源：发行说明

[配图建议：同一份缺步骤文档分别进入“普通校验：警告”和“严格校验：失败”的分支；清晰标注文字的二维流程图风格。]

二、拿 CSV 导出举例：有结果，才有可讨论的验收条件

假设你让 AI 给管理后台增加“导出当前筛选结果”。下面是一段本文编写的示例，不是工具运行输出：

### Requirement: Export filtered records
The system SHALL export records matching the active filters as CSV.

#### Scenario: Export the current filter
- WHEN the user clicks Export with a filter active

它有需求、有场景标题，也有触发动作，看起来已经像一份规格。但读完之后，测试人员仍不知道下载文件应当满足什么条件。新检查能提醒这个场景缺少 THEN，帮助评审者发现文档尚未写完。

进一步补上结果，可以写成：

- THEN the downloaded CSV contains only records matching that filter

这让讨论落到一个可观察的行为上：筛选了什么，导出的记录就应满足什么。接着，团队还应自行确认空结果、筛选条件变化、导出失败等情况；这些边界是否需要独立场景，取决于真实产品规则。

“有 THEN”只是起点，“THEN 写得能否检验”才决定评审价值。如果结果写成“系统正常处理”，格式可能完整，业务要求却仍然模糊。官方写作指南强调，需求应描述可观察行为，场景应覆盖重要边界，而不只是重复需求句子。来源：规格写作指南

对 AI 编程团队，这种文本有一个实际价值：产品、开发和测试可以围绕同一条行为讨论。它不能替大家做决定，却让“我们是不是理解了同一个功能”更容易被检查。

[配图建议：CSV 导出示例的前后对照，左侧只有触发动作，右侧增加可观察结果和待确认的空结果分支；技术杂志批注插画风格。]

三、校验通过以后，还剩两层工作

第一层是业务审查。结构检查不会自动知道，某个角色是否有导出权限、敏感字段是否应该出现，或者空结果应下载空表还是提示用户。这些都需要团队给出明确规则，再写进需求和场景。遗漏了一个完整场景，与已有场景少写一步，是两种不同的问题。

第二层是实现验证。规格写得清楚，并不代表代码已经正确实现。仍要检查实际下载内容、异常处理和回归结果。官方 CLI 文档将 validate 定位为规格与变更的结构校验，并包括对部分变更关系的检查；它不是“跑完业务测试”的替代品。来源：CLI 校验说明

可以把协作过程拆成三次提问：

  • 结构审查：有没有必要的需求和场景步骤？
  • 业务审查：规则、边界和预期结果是否说对了？
  • 实现验证：软件实际运行时，是否符合这些预期？

这里的代价也应算进去：规格会占用编写和维护时间，需求变化后要同步修改，严格检查还可能让旧文档的积欠集中暴露。对于纯文案修正，长篇规格未必划算；对于反复返工的跨角色功能，先把验收条件写清楚更有意义。这是本文的使用判断，不是项目提供的效率测试结论。

[配图建议：结构审查、业务审查、实现验证三道检查位置依次展开，每道都有不同的负责人和问题；简洁信息图风格，不使用通过率数字。]

四、怎样试用：先检查一个小变更，再决定是否接入流水线

已经使用 OpenSpec 的团队，可以先在分支里选择一个范围明确的变更。下面命令依据 1.16 文档整理，本文未安装运行，不代表实测记录：

# 检查名为 export-filtered-records 的变更
openspec validate export-filtered-records

# 把包括新增场景问题在内的警告作为失败条件
openspec validate export-filtered-records --strict

export-filtered-records 是示例名称，需要替换成自己的变更名。先看普通检查报告，再看严格检查差异，能帮助团队判断有哪些旧问题需要处理。准备接入持续集成时，可以评估 openspec validate --all --strict --json；它覆盖所有变更与规格，切勿把单个试点无警告等同于整个仓库已准备好。来源：CLI 参数与用法

升级前还要确认安装方式：通过 npm 安装 1.16，要求 Node.js 至少 22.12.0；独立二进制不依赖 Node，Homebrew 则管理自己的 Node。已有用户应按对应渠道升级，再确认实际调用的版本。来源：1.16.0 安装变更

首次使用者，可以先从官方项目说明进入初始化流程，不必一开始就对整个仓库强制严格检查。试点目标也应具体：找到一条过去难以验收的需求，让另一位同事仅凭规格就能说出该怎样验证。

[配图建议：一个小变更先经过普通检查和严格检查，再由团队决定是否推广到仓库；低干扰的开发工作流示意图风格。]

今天就做一步：重写一条“正常处理”

OpenSpec 1.16 提供了更细的结构提醒，也让无效配置更难悄悄绕过校验；真正的收益，取决于团队是否把提醒转成清楚的验收条件。

今天可以做的一步是：找出最近一条由 AI 起草、预期结果写着“正常处理”的需求，把它改成别人能够观察和复核的行为。如果项目已经使用 OpenSpec，再对这个变更运行普通与严格校验，记录差异；尚未使用，也可以先完成这次人工评审。

你所在团队更常遇到哪种返工：需求缺少边界，还是实现偏离了已经明确的预期？欢迎留下一个具体例子。

[配图建议：一条模糊需求被改写为带触发条件和可观察结果的验收条目；手写批注与纸张拼贴结合的收尾插画风格。]