reviewing-api-spec

reviewing-api-spec — SKILL.md

**变体：**标准 · **适用场景：**将已完成的 api-spec 文档作为验收门槛进行评审——检查客户端能否调用每个操作，以及服务端能否仅凭契约实现这些操作，然后输出 VERDICT: approve|revise，并提供可执行的发现项。绿地项目，或修订（范围限定于差异）。

概述

此技能是 api-spec 编写/评审配对中的评审部分。评审者加载此技能时，持有一份已完成的 api-spec 文档——即 API 表面的工程线协议契约（操作、请求和响应架构、身份验证、错误模型、分页/速率限制、版本控制、示例）。此技能围绕一个问题评判该文档：客户端工程师能否正确调用每个操作，服务端工程师能否仅凭此文档实现这些操作，并且对数据结构、错误或身份验证毫无歧义？它会应用一份固定的11 项契约完整性检查清单——与 api-spec 作者编写文档时采用的标准相同（authoring-api-spec 的第 7 步自检），确保编写标准与评审标准保持一致——然后输出单一、可由机器解析的结论，以及作者可以在一轮修订中采取行动的发现项。这是一个验收门槛——它不会编写、修复或重写契约；它只负责评判并返回发现项，由编写者进行修订。

评审标准与作者共用同一来源。作者的技术手段——风格表示法（OpenAPI / GraphQL SDL / proto）、具名 RFC 约定（RFC 9457、RFC 8594/9745、AIP-180/185）、JSON-Schema 熟练度——都是评审者根据结果进行评判的辅助方式（每个操作的双方是否都有类型定义？是否有一种一致的错误结构，并列出所有失败情况？示例是否与架构匹配？），而不是要求满足的条件。但请注意边界：完整错误模型（条件 5）、双方均有类型定义（条件 3）和每个操作的授权（条件 4）确实是 api-spec 中重要且不可或缺的条件——它就是线协议契约，因此不要将它们当作“实现细节”而评审不足。属于辅助方式的是技术手段（具名表示法/RFC），而非结果（有类型定义的操作、完整错误目录、逐操作范围）。

不受风格限制（重要）。契约可以是 REST（OpenAPI/JSON-Schema）、GraphQL（SDL + errors 数组 + 可空性），也可以是 RPC/gRPC（proto + google.rpc.Status）。应按照各自的惯用方式进行评判：GraphQL 契约确实没有 HTTP 状态码（错误通过 errors 数组传递；响应是带类型的有效负载或错误），gRPC 契约使用 google.rpc.Status + 标准代码，而非 HTTP。对非 REST 契约要求采用 REST/OpenAPI 惯例，是典型的OpenAPI 反射式错误要求修订——不要这样做。不受风格限制的原则贯穿条件 2（操作）、条件 3（双方均有类型定义）和条件 5（错误模型）：应按照契约采用的任何风格来评判这些条件。

适用时机

• 已完成的 api-spec 文档需要在客户端集成或服务端实现之前作出接受／修改决定。
• 你是独立评审者／把关人，负责评审编写者刚撰写的 api-spec。
• 在先前给出 revise 结论后，重新评审修订后的 api-spec。
• 将修订（已批准的契约 + 变更请求）作为限定变更范围的评审（cond-11）。

请勿在以下情况启用：

• 编写或修复 api-spec → 使用 authoring-api-spec。此技能绝不编写契约。
• 评审数据模型（线协议 DTO 所引用的存储实体——上游，单向）或功能规格（功能的行为——上游）→ 它们是各自独立的文档，也有各自的把关流程。
• 评审已发布、面向使用者的 api-reference（面向最终用户的说明文档，通常根据此契约生成——下游）→ 使用 reviewing-api-reference。此契约是该参考文档的唯一事实来源，反之则不成立。
• 评审实现／服务端代码（即履行契约的代码）→ 此把关流程评判的是设计文档，而不是代码。
• 评审通用／临时编写的工程设计文档、RFC、ADR、规格或计划 → 使用 design-review。此把关流程适用于文档库中的 api-spec 工件——权威标识为 frontmatter 中的 template: api-spec；仅当缺少 frontmatter 时，才将 # API Specification 标题作为备用信号。
• 检查模板／章节是否符合要求 → 这是模板方面的问题。此技能评判的是质量是否达标，而不是是否包含每个标题。

工作流

第 1 步：以全新、独立的视角通读整个契约

从头到尾阅读 api-spec 文档，就像第一次看到它一样。你要为下一步把关（客户端进行集成 + 服务端进行实现）：只有指出 API 无法按设计调用或实现的发现才有分量。随手备好上游的功能规格（以及适用时的数据模型）——cond-2／cond-6／cond-10 会依据它们检查契约。先判断 API 风格（REST／GraphQL／gRPC，也可能是混合风格），再按照各自的惯例进行评判。输入就是文档本身——操作列表、各操作的架构、错误目录、共享类型、身份验证章节和示例都包含在文档中（模板章节）；不需要单独的配套工件。这是一次修订吗？ 如果收到的是针对现有契约的变更请求／差异，请执行限定变更范围的评审路径（启用 cond-11；范围涵盖变更的操作及其分类，以及弃用／影响范围）。首次从零开始构建时不会有变更请求——cond-11 不适用。

第 2 步：运行契约完整性检查清单，逐项评判条件

对每项条件，判定为通过或存在缺漏。只有存在真实且明确的缺陷时，条件才算未通过——“我会采用不同的设计”不算缺漏。这些条件是唯一的评判标准；不要自行添加标准。

下方的能力边界检查项仅在 capability_record 已注入编写调用并可作为评审上下文时适用。如果没有，则视为不适用——未定义边界时，不要因文档缺少能力边界标记而扣分。

1. 风格、基础信息与版本管理。 已说明 API 风格、基础 URL/端点和明确的版本管理方案；已说明破坏性与非破坏性变更规则，以及弃用→停止支持政策。版本管理方案缺失，或未说明破坏性变更规则／弃用政策，则为缺口。（可合并：全新构建的 v1 API 即使尚无任何弃用项，也应说明政策。不可合并的基线要求——无论规模大小，都必须具备风格、基础信息和版本管理方案。）
2. 列出并追溯每个操作。 操作列表完整且易于浏览；每个操作都对应上游功能规格中的行为（没有孤立／臆造的端点，也没有遗漏）；方法和成功状态语义正确（例如使用会改变状态的 GET，或该用 201 却用了 200，都属于缺口）。某个操作无法追溯（臆造的端点）、某项功能规格中的行为没有对应操作，或方法／状态码错误，则为缺口。（依据给定的上游材料判断——缺少功能规格本身绝不能成为要求修改的理由。）
3. 完整定义每个操作两端的类型。 请求和响应均已完整定义类型，每个字段都注明必填／可选及约束；每个响应都对应状态码（REST）／带类型的载荷或 errors（GraphQL）／带类型的响应消息（gRPC）。字段未定义类型或约束，或响应没有状态码／带类型的主体，则为缺口。只定义成功路径的操作（仅包含 2xx）不合格。（这是签名核心要求之一；不可合并的基线要求——无论规模大小，每个操作的请求和响应都必须定义类型。）
4. 身份验证与逐操作授权。 说明身份验证方案及凭据位置；根据客户端类型选择 OAuth 流程；为每个非公开操作注明必需的作用域／角色（与操作列表对应）；说明令牌生命周期、HTTPS 和不得在 URL 中传递密钥。某个操作未说明授权要求（默认开放，或只写「已登录」而未指定作用域）、未命名身份验证方案，或凭据出现在 URL 中，则为缺口。（可合并：全公开 API 无需逐操作指定作用域——但仍须说明身份验证方案／传输方式。）
5. 错误模型完整。 整个 API 采用统一的错误结构（包含机器可读代码、消息和请求／追踪 ID），并且逐个操作枚举所有具名失败情形（酌情涵盖验证失败、401／403／404／409／429／5xx），注明状态码、代码和是否可重试。某个操作只展示 2xx、各端点的错误主体随意或不一致、缺少机器可读代码／请求 ID，或未说明是否可重试，则为缺口。这是本规范的标志性要求，也是它与通用 design-review 最大的区别。（不可合并的基线要求——无论规模大小，错误模型都不能只涵盖成功路径；只读操作也须注明 401／404。）
6. 共享类型只定义一次并以引用复用；数据模型只引用、不重复定义。 可复用 DTO 只定义一次并通过引用复用（不得内联重复定义，以免产生偏差）；接口 DTO 应引用数据模型并注明差异，而不是重述数据模型。相同结构在多个操作中以内联形式重复定义（有偏差风险），或 DTO 重新定义并与提供的数据模型矛盾，则为缺口。（这是签名核心要求之一。全新构建条款：未提供数据模型时，DTO 可独立定义，不构成缺口。）
7. 分页、筛选、排序与速率限制。 集合操作须定义分页方式、响应封装和默认／最大页大小；注明可筛选／排序字段及稳定的次级排序键；说明速率限制、相关标头和 429。集合未分页或没有范围限制、已排序的分页集合没有稳定的次级排序键，或缺少最大页大小，则为缺口。（可合并：非集合／单资源 API 无需分页——绝不能仅因「没有分页」而错误地要求修改。）
8. 示例完整且一致。 每个主要操作至少提供一组完整的请求／响应示例，且与架构定义一致（字段名、类型、状态码和错误结构均相同）。示例包含架构定义中不存在的字段、类型错误、状态码错误，或错误主体不符合统一结构，则为缺口。（这是 api-spec 中与图表⇄表格同步相对应的要求。可合并：主要操作均需有示例，但不一定涵盖所有操作。）
9. 命名与版本管理保持一致。 命名约定和版本管理方案在整个 API 范围内统一应用（所有操作均遵循）。命名／大小写不一致，或版本管理方案应用不一致，则为缺口。（仅检查 API 范围内的统一性，与条件 1 的是否说明政策和条件 2 的逐操作正确性不同；不要在此重复审查。）
10. 有依据、诚实且保持一致。 操作／结构／限制／代码应反映功能规格和数据模型（不得臆造或使用套话）；明确说明假设（输入信息不足时应列为阻塞项，而非臆造结构）；不得编造；与 api-reference 保持单向关系（本契约是已发布参考文档的事实来源，而不是根据 api-reference 逆向推导）；引用数据模型（保持单向、以上游为准）；若已有已发布 API，则须与其保持一致（已确认的当前操作／结构声明须经 file:line 核实，无法确认的须标注为未经核实）。臆造字段／限制／状态码／代码、根据已发布参考文档逆向推导操作，或文档中的操作与已部署 API 不一致，则为缺口。（不可合并的基线要求——无论规模大小，都必须杜绝编造并保持单向关系。全新构建条款：全新／拟议／虚构的 API 尚无已发布版本，因此一致性检查为不适用，绝不能因此错误地要求修改。）
11. （仅修订）变更范围明确、分类正确、影响已梳理并完成版本管理。 审查相对于现有契约的变更时，变更涉及的操作须符合条件 1–10；变更须归类为新增或破坏性变更；破坏性变更须采用新版本，并附弃用→停止支持计划及迁移指南（不得在同一版本下原地修改）；分析向后／向前兼容性；标明向前／向下的连带影响（下游 api-reference 的重新同步、实现／测试计划以及现有客户端）；提升文档版本并提供变更日志；废弃的操作须标记为已弃用，不得静默删除。变更范围不明确、破坏性变更被误归类为新增（或在同一版本下原地修改）、未标明连带影响，或静默删除操作，则为缺口。（可合并：全新构建的首个版本不适用此条件——不要完整重审未变更的契约，也不要要求初稿提供变更日志。）
12. **能力边界（无 capability_record 时不适用）：**所有 entry_points 均可作为 API 操作访问；publishes/consumes 事件都有对应的异步操作；refs 字段标记为只读的跨能力引用。

相称性。“可调用 + 可实现”应与 API 的规模相称。精简的 API 可以合理地省略不需要的内容——只有一个操作 → 简短列表；没有集合 → 无分页；全部公开的只读 API → 无需逐操作设置权限范围；全新设计的契约 → 没有已发布的 API 可供核对；初稿 → 无变更日志。评判的是契约决策是否完整，而不是字数或是否包含模板中的章节。满足所有适用条件的小型完整契约，应予通过。不要因为内容简短就凭空认定存在缺漏。

第 3 步：判定结论

• approve — 所有适用条件均通过。客户端可以调用每项操作，服务端也能仅凭契约实现这些操作，且数据结构、错误或身份验证方面没有歧义。即使你能想到文风上的改进，也应予以通过；标准是可调用 + 可实现，而非尽善尽美。
• revise — 一个或多个条件存在明确缺漏，导致操作无法调用或实现（例如，操作只描述了成功路径、字段未指定类型、错误目录不一致或缺失、示例与其架构相矛盾、DTO 与数据模型相矛盾、操作没有授权机制、破坏性变更被原地修改、修订内容未限定范围等）。

不要为了体现投入或索要锦上添花的改进而要求修订。条件要么满足，要么不满足。

第 4 步：给出结论和可执行的发现

结论必须单独占一行，原样输出 VERDICT: approve 或 VERDICT: revise，不得加上代码围栏、引号或其他文字（此处的围栏仅作示例）：

VERDICT: approve

然后在后续行列出发现。若结论为 revise，每条发现都必须可执行——指出未满足的条件、确切位置以及修复方法，以便作者一次性解决问题。若结论为 approve，可以列出非阻塞说明，也可以不列。

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

revise — 错误模型完整（条件 5），§3 GET /invoices：该操作仅记录了 200 响应，没有错误情况。修复：使用统一的 Problem-Details 结构，列出所有失败情况（401 unauthorized；若有权限范围限制，则列出 403 forbidden；404 not_found），并为每种情况提供状态码、机器可读代码和是否可重试的信息，以便客户端处理每一种结果。

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

错误处理还可以更完善。（哪个操作？哪些错误？采用什么结构？）

规则

硬性规则（绝不可违反）：

• 只输出一行裁定：VERDICT: approve 或 VERDICT: revise——必须是该字面标记，单独占一行，除此之外不得包含任何内容。下游工具会解析它。
• 只评审，不编写。 返回问题；不要重写、修正或补全契约。由编写者进行修改。
• 统一评审标准。 按照第 2 步中的十二项条件评审——这与作者（authoring-api-spec 第 7 步自检）采用的标准相同。不要另设条件，也不要套用更严格的个人标准。
• 评判结果，不强求辅助方法。 风格标记法（OpenAPI/SDL/proto）、所列 RFC（9457/8594/9745/AIP）和 JSON-Schema 熟练度，都是作者的技巧——应评判操作是否有类型定义／错误目录是否完整／示例是否匹配，绝不要说“你没有使用 OpenAPI／RFC 9457／$ref”。（错误模型／双方类型定义／逐操作授权这些结果是条件 cond-3/4/5 的真实要求，只有技巧才是辅助方法。）
• 不偏向任何风格——不要条件反射般要求 OpenAPI。 不要因为 GraphQL/gRPC 契约缺少 HTTP 状态码／OpenAPI／REST 资源而要求修改；应评判其 errors 数组和可空性（GraphQL），或 google.rpc.Status 和 proto（gRPC）。这是本门禁要防范的首要偏差。
• 不要错误地要求修改。 满足所有适用条件的契约都应通过，即使小型 API 的契约很精简也一样。只有存在真实且明确的问题时才要求修改。精简 API 合理地省略分页、逐操作作用域和变更日志。
• 不要错误地批准。 不要为了迁就而忽略真实问题。只有成功路径的操作、无类型定义的字段，或相互矛盾的示例，都应判定为 revise。
• 错误模型不是成功路径（条件 5）。 操作只展示 2xx 是真实问题，而非风格问题（客户端无法处理失败）。这是 api-spec 中最常被忽略的部分。
• 根据文档提供的上游内容进行评审。 对照契约的 depends_on 集合及其引用的文档进行评估。未产出／未交付的上游文档（例如缺失的 feature-spec 或 data-model）绝不能成为要求修改的理由。契约若忽略了已产出且本应追溯的上游内容，则可据此指出问题。
• Amend 评审仅限于变更范围。 对照现有契约审查变更时，应评审差异、分类、弃用情况和影响范围（cond-11）——不要重新评审未变更的契约，也不要要求首次起草的全新契约提供变更日志。
• 全新契约的一致性检查为 N/A，不算问题。 若没有已发布的 API 可供核验（新建／拟议／虚构的契约），将 cond-10 的一致性检查标记为 N/A——缺少可供核验的已部署接口，本身绝不是阻塞问题。
• 每条要求修改的问题都必须可操作——指出未满足的条件、位置和具体修复方法。

建议（可覆盖）：

• 按严重程度排列问题——先列阻塞性问题，再列次要问题。
• 在每条问题中注明条件编号／名称，方便作者对照标准。
• 对于通过的评审，备注应尽量少，并明确说明其不构成阻塞。

注意事项

• 以完整性而非可调用性为标准批准。 每个部分都可能齐备，但 API 仍不可调用（某个操作只覆盖顺利路径、某个字段未指定类型、某个示例与其架构相矛盾）。判断标准应是 API 是否可以调用和实现，而非 模板是否已填完。
• 条件反射式要求 OpenAPI。 要求 GraphQL API 提供 HTTP 状态码，或要求 gRPC API 提供 OpenAPI，是最常见的偏差——GraphQL 合约用 errors 数组和可空性来定义是正确的，gRPC 合约用 google.rpc.Status 和 proto 来定义也是正确的。应根据各风格本身的惯例来判断。
• 放过只覆盖顺利路径的操作。 一个列出 200／201 就结束的操作看起来似乎完整了——但如果没有错误情况，客户端就无法编写 catch 分支（条件 5）；必须列举所有失败情况，否则就是缺漏。
• DTO 反转／逆向工程得出的合约。 如果合约中的数据结构与上游数据模型相矛盾，或者其操作是根据已发布的 api-reference 逆向工程得出的，就颠倒了依赖关系（条件 6／条件 10）——数据模型在上游，api-reference 在下游。
• 与架构不一致的示例。 示例中的字段未在架构中声明（或类型／状态错误），会悄无声息地破坏合约，影响照搬示例的人（条件 8）。
• 臆造条件（标准偏移）。 添加审核标准并未要求的私有要求（“必须使用 RFC 9457／OpenAPI／$ref”），会让审核标准偏离产出标准。只根据结果评判所用技巧。
• 系统性过度标记（误判为需修改）。 受托寻找问题的审核者容易过度纠正。只有明确指出具体且真实的缺陷，才算存在缺漏；不能把自己会做出不同选择当作缺漏。
• 混淆 api-reference 与设计审核。 api-spec 的评判标准是合约是否可调用且可实现——这不同于 api-reference（已发布的消费者文档，面向下游使用者），也不同于 design-review（负责审核通用设计文档／RFC／ADR／规格说明／计划）。此审核环节是 doc-library 中 api-spec 产物的专属审核者。
• 判定标记偏差。 “Approved”、“LGTM”、“needs work”或埋在段落中间的判定结果都无法解析。请单独一行输出字面内容 VERDICT: approve|revise。

反模式

• 敷衍批准。 为了避免反复修改而草草浏览后批准——放过只覆盖顺利路径的操作或与数据模型矛盾的 DTO，会导致无法处理的失败，或线路与存储数据不匹配。
• 吹毛求疵要求修改。 把命名、记法或锦上添花的内容说成缺漏，以此阻止通过。只有真正阻碍可调用性／可实现性的问题才需要修改。
• 条件反射式要求 OpenAPI 并据此要求修改。 因 GraphQL／gRPC 合约未使用 HTTP 状态码／OpenAPI 而要求修改——这是 api-spec 特有的主要偏差。
• 悄悄重写。 “直接修好合约更容易”——在审核过程中代为撰写，会模糊产出与评判之间的界限。
• 臆造条件。 添加审核标准并未要求的要求（指定记法／RFC）——只根据结果评判。
• 对修订内容进行完整复审。 因小幅改动而重新评判整份未改动的合约——应按比例审核改动部分及其分类、弃用情况和影响范围（条件 11）。
• 含糊的判定。 “基本批准，但是……”或输出两行判定结果。只能有一个决定，且只能使用一个标记。

输出

针对一份 api-spec 文档的单条评审结果：

• 一行结论——单独一行原样写出 VERDICT: approve 或 VERDICT: revise。
• 问题发现——若结论为 revise，则针对每项阻塞性缺陷给出一条可执行的问题发现（未通过的条件 + 位置 + 具体修复方法）；若结论为 approve，则可选提供非阻塞性备注。

抽象的消费者是负责协调产出→评审循环的对象：approve 表示接受该契约以供集成/实施；revise 则将问题发现返回给产出方，进行有范围限制的修订。Medium：当前被评审的工件是文本型 Markdown api-spec（操作表 + 围栏代码块中的 schema + 示例对）；评审标准与媒介无关。

相关内容

• authoring-api-spec——配对工具中的产出环节；它按照本技能评审的同一套十一项条件标准（其第 7 步自查）编写契约。将两者配对可确保产出和评审采用同一标准，不会产生偏差。
• data-model（若存在）——上游；线上的 DTO 引用其中的实体（单向）；条件 6/条件 10 检查契约是否引用该模型，而非重新定义或与之矛盾。
• 上游的 feature-spec——契约所公开的行为；条件 2/条件 10 会追溯至该规格（仅在提供该规格时评审）。
• reviewing-api-reference——用于把关下游已发布 api-reference 的工具（通常由本契约生成）。本契约是该参考文档的事实来源（条件 10 的单向规则）；绝不能从 api-reference 反向推导。
• design-review 技能——用于把关通用工程设计文档、RFC、ADR、规格和计划（它会根据代码库核实声明）。本技能专门评审文档库中的 api-spec 工件；design-review 不涵盖该工件。
• api-spec 模板 / 内容模板工具——负责章节结构；本技能评判的是是否符合质量标准，而非结构是否符合要求。

渐进式披露

• references/api-spec-quality-bar.md——十二项检查条件的详细说明，包含每项条件的通过/缺陷信号和问题发现示例（双方均有类型检查、完整错误模型检查、共享类型/引用数据模型检查、逐操作授权检查、分页/平局决胜规则检查、示例与 schema 匹配检查、单向性/与已发布 API 一致性检查、不受风格影响的防护，以及限定差异范围的修订信号）。遇到边界情况、需要更明确地判断通过与否时加载。
• references/sources.md——评审方法的研究来源（OpenAPI/JSON-Schema、GraphQL SDL、gRPC/proto、RFC 9110/9457、RFC 8594/9745、AIP-180/185、分页和速率限制惯例）。

正文预算

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

变更日志

• 1.0.0（2026-06-15）——初始发布。通过改编典范姊妹技能 reviewing-data-model 创建全新的评审工具；十一项契约完整性标准与 authoring-api-spec 的第 7 步自查逐项共用同一来源；不受风格影响（不默认采用 OpenAPI）；沿用 VERDICT: approve|revise 契约、依据给定上游进行评审、根据代码核实与已发布 API 一致性的规范及绿地项目条款，以及比例原则 / 避免误判为 revise / 不臆造条件等反模式。