reviewing-feature-spec

reviewing-feature-spec — SKILL.md

**变体：**标准 · **使用时机：**将已完成的功能规格说明作为验收关卡进行评审——检查其是否可实现、可测试，然后给出 VERDICT: approve|revise，并附上可执行的发现。适用于绿地项目，或修订（限定差异范围）。

概述

此技能是成对的功能规格说明生成与评审技能中的评审部分。评审者已获得一份完整的功能规格说明——位于 PRD 下方、说明每项功能如何表现的文档。此技能围绕一个问题评判该规格说明：工程师能否据此实现，测试人员能否据此验证，而无需询问作者，从而让规划人员可以据此拆分任务？它会应用一份固定的10 项可实现性与可测试性检查清单（与功能规格说明作者遵循的标准相同，以免生成标准与评审标准发生偏差），然后给出一条可由机器解析的结论，以及作者能够在一轮修订中处理的发现。这是一个验收关卡——它不会撰写、修复或改写规格说明；它只负责评判并返回发现，由编写者进行修订。

此标准与作者遵循的标准统一来源。作者使用的技巧——EARS 表述、决策表、精确的用例流程、原型覆盖、29148 词汇——都是评审者根据结果进行判断的辅助方法（行为是否明确？规则集是否完整？验收标准是否适合该功能的性质且可测试？），而不是需要强制采用的条件。擅自添加作者无需遵循的条件（例如“必须使用 EARS”“必须包含 UI 章节”）是此技能要防范的主要偏差。

何时启用

• 已完成的功能规格说明需要在工程规划或实现之前作出接受／修订决定。
• 你是某份刚由编写者撰写的功能规格说明的独立评审者／把关者。
• 在先前给出 revise 结论后，重新评审修订后的功能规格说明。
• 评审修订——已批准的规格说明加上一项变更请求——并限定差异范围进行评审（条件 10）。

请勿在以下情况启用：

• 撰写或修复功能规格说明 → 使用功能规格说明撰写技能。此技能绝不撰写规格说明。
• 评审上游 PRD（产品的做什么／为什么文档）→ 使用 PRD 评审技能。该关卡评判产品是否便于规划；此关卡评判下一层各项功能是否可实现。
• 评审工程设计文档——架构规格、设计文档、ADR 或 RFC → 使用设计评审技能。该关卡会根据代码库验证设计主张；此关卡则根据可实现性标准评判行为规格说明。
• 检查模板／章节是否符合规范 → 这是模板方面的问题。此技能评判的是质量是否达到标准，而不是每个标题是否齐全。
• 评审其他类型的文档。

工作流

步骤 1：以全新、独立的视角通读整份规格说明

从头到尾阅读功能规格说明，像初次接触它一样，不受作者的说明框架影响。你要为下一步（规划与构建）把关：只有当某项发现表明该功能无法按文档所述实现或无法按文档所述测试时，它才有分量。请随手查阅上游 PRD（或规格说明所分解的需求清单）——步骤 2 的第一个条件会从两个方向对照检查规格说明与其是否一致。**这是修订吗？**如果你收到的是针对现有规格说明的变更请求／差异，请采用限定差异范围的评审路径（启用条件 10；评审范围限定为变更区块）。首次绿地构建时不存在变更请求——条件 10 不适用。留意哪些行为、输入、边缘情况、验收标准、状态或 NFR 至关重要；检查清单会重点审查这些内容。

步骤 2：运行可实现性与可测试性检查清单——逐项评判每个条件

对于以下每项条件，判定为 通过 或 存在缺口。只有存在真实且明确指出的不足时，条件才算未通过——“我会用不同的方式表述”不算缺口。对于每个缺口，记录确切位置和缺失内容（第 4 步会将其转化为可执行的发现）。这些条件是唯一的评判标准；不要添加个人标准。

下方的能力边界检查项仅在创作调用中注入了 capability_record，且该记录可作为审查上下文时适用。若缺少该记录，则视为不适用——如果未定义边界，不要因文档缺少能力边界标记而扣分。

1. 可追溯至上游需求。 每项功能都对应到特定的 PRD 目标／需求／指标，且每条上游功能条目都由某个规范章节覆盖——两个方向都要检查。没有上游条目的功能属于孤立项（范围蔓延）；没有功能对应的上游条目属于覆盖缺口。孤立项、未覆盖条目或未说明／无法重建的可追溯性均为缺口。（不可折叠的基线——无论规模大小，不服务于任何 PRD 条目的功能都是有问题的。）
2. 行为明确且可观察。 每种行为都只能有一种解释方式，以可观察的系统响应表述，且不涉及实现方式。流程连贯（包含主要成功场景；分支归类为替代路径或异常路径）。如果同一段文字可能导出两种实现方式、没有可观察输出、夹带实现选择，或依赖于关键需求异味（主观／薄弱／含糊的术语、没有参照对象的比较、漏洞、开放式的“等等”），则为缺口。（不可折叠的基线。）
3. 输入／输出／状态完整。 每项输入都列明来源、类型、校验规则以及必填／可选；每项输出都列明结构／响应及副作用；有状态的功能包含状态转换表（每个（状态、事件）单元格都定义下一状态或明确标记为非法；初始／终止状态有名称）；组合型功能的规则集完整（不存在会导致行为未定义的输入组合）。缺少校验规则／输出结构、有状态功能的转换需靠猜测，或规则组合没有定义操作，均为缺口。（可折叠：无状态功能无需状态表；非组合型功能无需决策表——不算缺口。）
4. 涵盖边界情况和错误处理，且逐一说明响应。 应处理常见的边界／失败路径——空值／空内容、重复／幂等性、并发／竞态、权限／可见性、限制／溢出（每个限制都要测试边界值）——并且每个已列出的边界情况都说明预期处理方式。适用的边界情况未提及，或虽已列出却未说明系统如何处理，均为缺口。（可折叠：轻量功能的失败场景较少——边界情况较少没有问题；但每个边界情况都必须说明处理方式，这一规则是不可折叠的基线。）
5. 验收标准可独立测试。 每种行为和边界情况都附带测试人员无需询问作者即可执行的通过／失败标准——Given／When／Then 或基于规则的检查清单。对于概率型／ML功能，确定性的 G/W/T 不适合输出：针对指定数据集的指标阈值标准（精确率／召回率／延迟 ≥ X）以及低置信度／回退行为都可以测试并通过；确定性的**“模型准确”／“结果相关”**则是本条拒绝的模糊标准。没有可衡量通过／失败标准的模糊／主观标准，或没有标准的行为，均为缺口。一个章节中有 4 个以上标准属于拆分异味——应标记，但不能自动阻止。（不可折叠的基线。）
6. 单一且一致。 每项需求只表达一个想法（将“以及”连接的内容拆开）；术语保持一致；不存在内部矛盾。复合需求、含义发生变化的术语，或相互矛盾的章节，均为缺口。（可折叠：简短规范涉及面较少——但无论规模大小都必须保持一致。）
7. 可行且可规划。 能在已说明的约束条件内构建；输入／输出和标准足够具体，可据此规划任务／里程碑。已说明的约束导致所需行为无法实现，或规范过于抽象而无法估算／排序，均为缺口。
8. 公开说明未解决的问题，而非将其掩盖。 对真正的未知事项应明确说明，不应将其伪装成已确定的静默假设。规范看似完整却并非如此——明显尚未决定的问题未提及或被宣称为已决定——即为缺口。
9. 在功能需要时列出非功能需求。 对该功能至关重要的非功能类别（性能、可靠性／幂等性、安全／授权、隐私、UI 无障碍 WCAG 2.2 AA、限制／配额、兼容性）应有数值化／可核验的目标；对于其性质要求必须有目标的功能，模糊的“应该快速／安全”即为缺口。（可折叠：简单功能可以确实不需要任何此类要求；只要求适用的少数类别——绝不要求功能不需要的类别。明确声明为尽力而为的非功能需求不算缺口。）
10. （仅修订）变更范围明确、影响清晰、版本已更新。 对照现有规范审查变更时：变更涉及的区块符合条件 1–9；变更／新增的功能仍可追溯至 PRD 条目（或明确标记需要修改上游 PRD）；文档自身版本已更新，且包含变更日志条目（谁／何时／什么／为什么）；被取代的内容已标记，而非悄然删除；内部或下游追溯链条均未断裂（列明受影响的技术设计／测试计划／API 规范集合）。变更范围不明确、追溯关系断裂、缺少变更历史或内容被悄然删除，均为缺口。（可折叠：首次从零开始构建时，此条件不适用——不要对未变更的规范进行全面复审，也不要要求初稿附带变更日志。）
11. 能力边界（无 capability_record 时不适用）： 所有 owns 实体均已覆盖；所有 publishes 事件均已触发；所有 consumes 事件均已处理；未覆盖任何 refs 实体；scope 声明中的否定条款已遵守。

比例原则。 “足以据此构建和测试”应根据功能规模调整。精简功能可以合理省略不需要的章节——没有状态 → 不需要状态表；没有组合逻辑 → 不需要决策表；没有故障面 → 边缘情况可以更少；功能简单 → 不需要非功能需求（NFR）；初稿 → 不需要变更日志。评判时应看决策是否完整，而非字数或模板章节是否齐全。满足所有适用条件的精简完整规格说明应当通过。不要仅因内容简短就认定存在缺漏。

步骤 3：判定结果

• approve — 所有适用条件均已满足。工程师可以按文档构建该功能，测试人员可以验证该功能；规划工作可以据此拆解任务。即使你能想到风格上的改进，也应批准；标准是可实现性 + 可测试性，而非尽善尽美。
• revise — 一个或多个条件存在明确缺漏，导致无法构建或测试（例如，孤立功能、行为含糊、缺少对边缘情况的处理、无法测试的验收标准、未定义的状态转换、缺少关键的 NFR 指标、修订未限定范围或破坏连带内容等）。

不要为了体现工作量或索要锦上添花的内容而要求修改。条件要么满足，要么不满足。

步骤 4：输出判定结果和可执行的发现

将判定结果单独输出一行——原样输出字面文本 VERDICT: approve 或 VERDICT: revise，独占一行，前后不得加代码围栏、引号或其他文字（此处的围栏仅为示例）：

VERDICT: approve

然后在后续行列出发现。若为 revise，每项发现都必须可执行——指出未满足的条件、确切位置以及修复方法，以便作者一次性解决。若为 approve，可以选择列出非阻塞说明；不得让这些说明暗示必须修改。

好的发现会指出缺漏和修复方法：

revise — 验收标准（条件 5），“对结果排序”功能：唯一的标准是“相关性模型准确”，测试人员无法据此执行通过/失败判断。修复方法：在指定数据集上设定指标阈值，例如“在 2026-Q2 留出集上，precision@10 ≥ 0.80”，并补充低置信度时的回退方案。

不好的发现含糊且无法执行：

验收标准可以更全面一些。（针对哪个功能？为何不达标？怎样修复？）

规则

硬性规则（绝不违反）：

• 必须且只能输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记单独占一行，除此之外不包含任何内容。下游工具会解析它。
• 只做评审，不代写。 返回问题；不要重写、修正或补全规范。由编写者进行修订。
• 统一评判标准。 按照第 2 步中的十项条件进行评审——这也是作者撰写规范时采用的同一标准。不要另设条件，也不要采用更严格的个人标准。
• 评判结果，不强求辅助方法。 EARS、决策表、用例格式、原型覆盖项、29148 词汇都是作者的方法——应评判行为是否明确、规则集是否完整、验收标准是否可测试，绝不要说“你没有使用 EARS／添加 UI 章节／绘制决策表”。这是防止偏离标准的首要规则。
• 不得错误地要求修订。 只要规范满足所有适用条件，就应予以批准，即使小功能的规范很简短也是如此。只有存在真实且明确的问题时才要求修订。对于精简功能，合理地省略非功能需求、状态表、决策表和变更日志并无不妥。
• 不得错误地批准。 绝不能为了好说话而忽略真实问题。阻塞性问题必须判为 revise。
• 边界情况没有对应处理方式就是问题（条件 4）。 不能让实现者自行编造行为。
• 依据文档提供的上游内容进行评审。 根据文档的 depends_on 集合进行评估。未产出的上游内容绝不能成为要求修订的理由。文档忽略了本应参考的已产出上游内容，则可以作为问题提出。
• 修订评审仅限变更范围。 收到针对现有规范的变更时，应评审变更及其影响范围（条件 10）——不要对未变更的规范进行完整重审，也不要在全新初稿中要求提供变更日志。
• 每项修订问题都必须可操作——指出未满足的条件、所在位置以及具体的修正方式。

偏好（可调整）：

• 按严重程度排列问题——先列阻塞性问题，再列次要问题。
• 在每项问题中注明条件编号或名称，便于作者对照评判标准。
• 批准说明应简短，并明确标注为非阻塞项。

易忽略之处

• 为完整性而非可构建性批准。 每个部分都可能齐全，但功能仍无法构建（行为含糊、边缘情况没有响应、标准无法测试）。应判断功能能否构建和测试，而不是模板是否已填完。
• 列出却未处理的边缘情况。 规范即使列举了 null/empty、重复、并发和限制情况，看起来很全面，但如果没有说明系统对每种情况会做什么，构建要求仍不够明确（条件 4）。
• 对概率性功能设定确定性门槛。 不要仅仅因为某个数据集上的指标阈值标准“不是 Given/When/Then”就否决它——对于模型/排序器来说，这就是可测试的形式（条件 5）。反过来，“模型很准确”确实存在缺口。
• 擅自添加条件（评审标准偏移）。 添加评审标准未要求的内部要求（“应该使用 EARS／提供时序图／制定发布计划／设置 UI 部分”），会让评审标准偏离产出标准，导致不必要的返工。辅助材料只按结果评判。
• 系统性过度标记（误判为需修改）。 受命查找问题的评审者容易矫枉过正，把合格的规范判为有缺陷。只有指出明确且真实的缺陷，才算发现缺口，而不是指出某句话可以换种写法。
• 对精简功能误判为需修改。 小功能的规范本就可以很短；它不需要的部分（没有状态、NFR、决策表、变更日志）折叠或省略都不算缺口。
• 对 NFR／修订要求过高。 不要要求功能并不需要的 NFR 类别（条件 9 讲究适度），也不要对绿地草案应用条件 10。
• 混淆功能规范评审与 PRD 门禁或设计评审。 功能规范评估的是单个功能能否实现——它比 PRD 的产品规划性低一个层级，且不同于工程设计文档对代码一致性的评审。
• 裁决标记偏移。 “Approved”“LGTM”“needs work”，或埋在段落中的裁决，都无法解析。请单独一行原样输出 VERDICT: approve|revise。

反模式

• 走过场批准。 为避免反复修改而草草浏览后批准——放过含糊的行为或未处理的边缘情况，最终会变成缺陷或开发中途的紧急补救。
• 吹毛求疵要求修改。 把措辞、格式或锦上添花的内容包装成缺口并据此阻止通过。只有真正阻碍实现或测试的问题才需要修改。
• 悄悄重写。 “直接改掉更省事”——在评审过程中代为撰写，会破坏产出与评判的分离。
• 擅自添加条件。 添加评审标准未要求的要求（指定方法、要求特定部分）——这是此门禁主要要防止的偏移。
• 对修订内容进行完整重评。 围绕一处小改动重评整份未变的规范——应适度评审改动及其连带影响（条件 10）。
• 含糊其辞的裁决。 “基本批准，但是……”或输出两行裁决。只能有一个决定，且只能使用一个标记。

输出

针对一份功能规范，给出一份评审结果：

• 一行裁决——原样单独一行输出 VERDICT: approve 或 VERDICT: revise。
• 发现项——若为 revise，每个阻碍性缺口对应一条可执行的发现项（未满足的条件＋位置＋具体修复方法）；若为 approve，可选择提供非阻碍性备注。

抽象的使用方是负责协调产出→评审循环的主体：approve 表示接受该规范并进入下一阶段（规划／构建）；revise 表示将发现项返回给撰写方，以便进行范围有限的修订。媒介：当前受评审的产物是文本形式的 Markdown 功能规范；评审标准不依赖媒介。

相关内容

• feature-spec-authoring 技能——这对技能中负责产出的部分；它会按照本技能评审所依据的同一套 10 条条件标准编写规格说明。将两者配对可统一标准，避免产出与评审各行其是。
• PRD-review 技能——上一级的关卡，用于评审产品需求文档（讲述是什么／为什么）。文档不同，标准也不同。
• design-review 技能——用于评审工程设计文档（架构规格说明、ADR、RFC）的关卡，会根据代码库核实相关主张。关卡不同，标准也不同。
• feature-spec 模板／content-template 工具——负责章节结构；本技能评判的是是否达到质量标准，而非结构是否合规。

渐进式披露

• references/implementability-bar.md——展开说明十项检查条件，包含每项条件的通过／差距信号、标准边界情况检查清单、状态表 + 决策表 + 概率型验收标准 + NFR + 按变更范围限定的修订信号，以及已完成的发现示例。当某项条件的判断处于边缘时，加载此文件，以便更准确地判断通过／差距。
• references/sources.md——评审方法的研究依据（需求质量标准、EARS、BDD/Gherkin、INVEST、可追溯性、边界情况 + 概率型验收标准 + 变更影响技术，以及评审者过度纠正的证据）。

正文篇幅预算

• description ≤ 1,024 个字符（agentskills.io 上限）；在列表中，description + when_to_use 合计超过 1,536 个字符的部分会被截断。
• 正文约 500 行／5,000 个词元（软性目标——质量优先；如果持续超过 700 行／7,000 个词元，则标记）——每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个词元时警告，超过 25k 时错误。参考文件总计：超过 25k 个词元时警告，超过 50k 时错误。