reviewing-developer-guide

reviewing-developer-guide — SKILL.md

变体： 标准 · 适用场景： 将已完成（或修订）的开发者指南作为验收关卡进行评审——检查开发者能否据此采用、集成和操作工具，然后给出 VERDICT: approve|revise，并提供可执行的评审意见。

概述

此技能是成对的开发者指南编写/评判技能中的 评审 部分。评审者加载此技能时，会持有一份已完成的开发者指南——面向开发者工具产品（SDK、库、CLI、框架或 API 平台）的采用与集成说明，其中包括明确的入门指引、快速入门、核心概念、以代码为中心的集成指南、端到端教程、生产环境最佳实践、故障排除路径，以及指向 api-reference 的链接。此技能依据一个问题评判该指南：开发者能否仅凭这份指南安装工具、理解其心智模型、完成常见集成场景、解决常见错误，并在生产环境中运行工具；指南是否提供可运行的代码，且每个步骤都符合工具的实际行为？它会应用一套固定的可采用性与准确性检查清单——开发者指南作者遵循的标准也是同一套，确保编写标准与评审标准不偏离——然后输出一条可供机器解析的裁定，以及作者可在一轮修订中处理的评审意见。这是一个验收关卡：它不会编写、修复或改写指南；它只负责评判并返回评审意见，由编写者进行修订。

统一标准。 第 2 步中的 14 项条件并非本技能另行制定，而是 authoring-developer-guide 所遵循的可采用性与准确性标准（其第 5 步自检，逐项对应）——具体内容汇总于 references/adoptability-bar.md——因此评审标准与编写标准是同一套标准。

媒介（当前）。 待评审的指南是 Markdown（正文加围栏格式的安装/集成代码），而非渲染后的文档站点。评审的方法和标准独立于媒介——未来若使用 Figma、Confluence 或渲染后的文档作为后端，改变的只是媒介，而非本技能检查的内容。

何时启用

• 已完成的开发者指南需要在交付给集成开发者之前作出接受/修订决定。
• 你是某份刚由编写者完成的开发者指南的独立评审者/把关者。
• 在先前给出 revise 裁定后，重新评审修订后的开发者指南。
• 评判 AMEND——对已发布指南进行增量修订（例如工具发布了新版本）——仅评审变更范围（条件 12）。

不要在以下情况下启用：

• 编写或修复开发者指南 -> 使用 authoring-developer-guide（它遵循与本技能相同的标准）。本技能绝不会编写指南。
• 评审终端用户产品指南——面向消费者、供非技术用户阅读的帮助文档 -> 使用用户指南评审技能。该关卡评判终端用户的易用性；本关卡评判开发者的可采用性。
• 评审 api-reference——详尽的端点/符号目录 -> 使用 api-reference 评审技能。该关卡评判目录的完整性与契约一致性；本关卡评判链接至其中的开发者说明内容。
• 评审工程设计文档——架构规范、设计文档、ADR 或 RFC -> 使用 design-review（它会根据代码库验证设计声明）。这是不同的关卡，也采用不同的标准。
• 检查模板/章节是否符合要求 -> 这属于模板问题。本技能评判的是是否达到标准，而非是否包含每个标题。

工作流

Step 1: 以全新、独立的视角通读整份指南，并收集上游资料

从头到尾阅读开发者指南，设想自己是第一次采用该工具的开发者，不受作者的框架影响。你的立场是把关者：只有当发现表明开发者无法按照文档所述采用、集成或运行该工具，或某个步骤与工具的实际行为不符时，才值得重视。

收集已提交的上游资料（通常包括功能规范；对于 API 平台，还包括 API 参考文档）——第 2 步的准确性和覆盖度条件将依据这些资料进行检查。确定产品类型（是单一用途的轻量级 CLI，还是功能广泛的 API 平台）；评估标准会随之调整。修订时，还要收集变更请求和已修改的上游资料——cond-12 将依据这些资料进行检查。留意哪些代码示例、集成步骤或 API 参考文档链接至关重要——清单会重点审查这些内容。

Step 2: 运行可采用性与准确性清单——逐项评估条件

对以下每项条件，判断为通过或存在缺口。只有存在真实且明确指出的缺陷时，条件才算未通过——“我会把章节顺序安排得不一样”不算缺口。对于每个缺口，记录具体位置和缺失内容（第 4 步会将其转化为可执行的发现）。这十四项条件是唯一标准（references/adoptability-bar.md）；不要自行添加。每项标准都应按比例应用——轻量级工具可以合理地省略不需要的内容（参见「按比例评估」）。

1. 以目标组织。 围绕开发者可以构建或实现什么来编排，按目标命名配方，而不是平铺直叙地罗列端点。缺陷：内容只是端点清单，没有引导采用的叙述。
2. 入门指南能让读者获得可验证的首次成功。 前置条件（包括凭据的获取途径——从注册到取得密钥的路径，以及引导首次调用通过测试／沙盒模式进行）-> 安装 -> 配置凭据 -> 成功完成一次真实调用 -> 通过 verify 步骤确认预期输出。可运行且可复制粘贴；展示真实价值（而非单纯的 hello-world）；使用 env-var 凭据，绝不硬编码；路径短且畅通（尽量减少首次验证成功所需的步骤——TTFC 意图是评估路径是否“短且畅通”，绝不按秒表计时）。缺陷：没有 verify 步骤、首次调用无法运行、凭据被硬编码，或路径不必要地冗长／受阻。
3. 核心概念先于配方呈现。 以便于理解的内容解释心智模型——客户端对象、领域术语、生命周期、环境，并放在集成配方之前，而不是列出参数。缺陷：缺少概念介绍，或概念被放在配方之后／揉进配方之中。
4. 集成操作指南涵盖已提供的上游资料中的常见场景。 每个常见场景都配有一个以目标命名、以代码为核心、可独立阅读的配方；代码可运行，并链接到参考文档以查看完整选项。缺陷：已提供的功能规范／API 参考中存在某个常见场景，却没有对应配方（覆盖缺口）。
5. 端到端教程从头到尾构建一个小型真实项目，并与第 4 节的查询型配方分开（正确区分 How-to 与 Tutorial 类型）。缺陷：没有端到端构建内容，或教程与配方混为一体。
6. 基于真实使用场景的最佳实践。 身份验证／密钥、可重试与致命错误的处理、重试 + 幂等性 + 退避、分页、速率限制、webhook（工具会发出 webhook 时：签名／重放／顺序）、资源管理规范（客户端复用／池化／超时）——每项都应包含推荐模式和代码片段，而不是罗列选项。缺陷：缺少生产环境相关注意事项，或只有选项清单而没有建议。
7. Diataxis 模式类型划分正确且彼此分离。 Tutorial / How-to / Explanation / Reference 各自保持独立，不让一种模式渗入另一种模式。缺陷：模式混淆（入门指南变成参考资料清单；概念散落在各个配方中；教程与配方混为一体）。
8. 链接到 api-reference，而不是重复其中的内容。 应指向详尽的端点／符号目录，将其作为事实来源，而不是在指南中再次罗列。缺陷：指南在正文中复现了目录（api-reference-linking 检查——第 3 步）。
9. 代码示例可运行，且与实际／当前工具或 API 准确一致。 每个示例都应体现已提供的功能规范／API 参考中的真实能力／端点；使用 env-var 凭据；不得与上游约定相矛盾；指南应注明示例所针对的工具版本。缺陷：示例调用了上游资料中不存在的端点／方法／能力——即凭空捏造（upstream-accuracy 检查——第 3 步）。（审阅者无法通过已提供的上游资料之外的信息判断工具版本；“声明的版本是否为当前版本”不属于绿地检查——新鲜度要求体现在 cond-12 中。）
10. 说明工具版本管理与迁移。 包括版本方案、弃用政策／时间线、变更日志链接，以及每次主版本升级前后迁移说明（篇幅应与工具类型相称）。缺陷：发布了有版本的工具，却没有提供版本管理／迁移指南。
11. 以事实为依据，不得捏造。 能力／端点／代码应与上游资料一致；对于确实存在的资料缺口，应作为明确的假设／待解决问题指出，而不是捏造端点、能力或代码路径。缺陷：捏造答案以营造内容完整的假象。（与 cond-9 的区别：对于示例中捏造的端点／方法，引用 cond-9——检查示例与上游资料是否准确；对于本应指出缺口却捏造答案／假设的情况，引用 cond-11——不要对同一个缺陷重复计入两项。）
12. 按差异范围修订（仅限修订模式）。 仅当输入中提供了变更请求 + 已变更的上游资料时才生效；首次绿地构建时为 n/a。评估变更内容，而不是整份未变更的指南：变更涉及的部分达到要求（已变更的示例可运行且与当前工具准确一致）；上游过时内容检查完整——没有示例／配方／指引仍调用已移除／重命名的能力（这是影响最大的修订缺陷）；内部保持一致（概念先于配方，教程仍可运行）；指南自身版本已更新 + 已添加变更日志条目；已标记被取代／弃用的内容。缺陷：仍有过时示例、缺少变更记录，或被取代的内容遭到静默删除。（不要重新审查未变更且仍然准确的配方。）
13. 提供故障排除／常见错误处理路径。 为常见且可预见的问题提供自助解决路径（症状 -> 原因 -> 修复方法；工具有错误代码时提供错误代码表；提供简短 FAQ），内容应超出入门指南中首次调用的 2–3 个故障场景。缺陷：开发者遇到常见且可预见的错误时，无法在指南中找到解决办法。按比例要求——对于功能单一且精简的工具，将此内容并入入门指南也合理，不算缺陷。检查的不是“是否存在一个字面标题为 Troubleshooting 的章节”。
14. 易于查找——标明从哪里开始，并按读者旅程组织内容。 初次阅读者无需预先了解 API，就能找到入门指引和满足自身目标的章节。缺陷：没有内容导览／入门指引，导致新读者找不到起点。按比例要求——单页指南自然易于查找（不算缺陷）。避免重叠（此项很重要）： cond-14 关注的是导航／易查找性——对于已由 cond-1（按目标组织）或 cond-3（概念排序）发现的缺陷，不要再提出 cond-14；只有在内容导览／入门指引本身缺失或无法遵循时，才判定 cond-14 不通过，绝不能为了端点清单（cond-1）或概念排在配方之后（cond-3）重复扣分。 三个具名检查（影响最大的检查）：

• 上游准确性检查（cond-9）。对照提交的功能规格说明 / api-reference，抽查集成步骤和代码示例。虚构的能力或端点是影响最大的缺陷，也属于具名缺口。如果缺少上游资料（非 API CLI 没有 api-reference），应标记为假设，并根据提交的内容判断其是否易于采用；缺少上游资料不是要求修改的理由。
• Api-reference 链接检查（cond-8）。指南必须指向 api-reference 内部，不能重新列出目录。内联重复列出属于缺口；提供清晰指引则通过。
• 修订模式下的过时内容清查检查（cond-12，仅修订模式）。工具变更后，指南中不能再有任何位置引用已移除或已重命名的能力。残留的过时示例是修订中最严重的缺陷。

合乎比例。“采用、集成并据此运行”应根据产品规模而定。精简的单一用途 CLI 指南可以合理地省略不需要的章节——减少示例，将概念说明精简，或把故障排查并入入门指南，无需迁移矩阵，且单页内容易于查找——这属于正确的篇幅把控，而非缺口。广泛的 API 平台则需要扩展示例、webhook、故障排查和迁移说明。评估时应关注首次可验证的成功，以及正确的生产集成，而不是章节数或字数。满足所有适用条件的小型完整指南应予通过。（无论规模大小，条件 2 和 9 仍然适用：首次调用必须可验证，且不得伪造任何示例。）

第 3 步：判定结果

• approve — 所有适用条件均通过。开发者仅凭本指南，就能安装工具、理解其模型、完成常见集成场景、处理常见错误并在生产环境中运行；代码可运行，且每个步骤都与工具相符。即使你能想到风格上的改进，也应批准；标准是易于采用且准确，而非完美或面面俱到。
• revise — 一个或多个条件存在真实、明确的缺口，阻碍采用、集成或运行：没有可验证的首次成功；概念说明放在示例之后；缺少已提交场景所需的示例；存在虚构或过时的端点 / 能力；重复目录而非提供链接；Diataxis 模式混淆；需要故障排查的工具没有故障排查途径；入门指引难以找到；修订后仍残留过时示例；或答案内容有虚构。

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

第 4 步：给出判定结果和可执行的发现

判定结果单独占一行——原样写 VERDICT: approve 或 VERDICT: revise，不得添加代码围栏、引号或其他文字（此处围栏仅作示意）：

VERDICT: approve

然后在后续行列出发现。判定为 revise 时，每条发现都必须可执行——说明未通过的条件、具体位置，以及如何修复——以便作者一次性解决。判定为 approve 时，可选择提供不影响通过的备注；不得让备注暗示必须修改。

好的发现应指出缺口并给出修复方法：

revise — 上游准确性（cond. 9），「发送消息」示例：它调用了 client.messages.schedule(at=...)，但提交的 api-reference 中没有调度端点或 schedule 方法。修复方法：替换为 api-reference 中的实际能力，或将调度标记为待确认问题，而不是发布虚构调用。

revise — 修订模式下的过时内容清查（cond. 12）：指南已升级到 SDK v3，但「退款」示例仍调用已在 v3 中移除的 Client(key=...)。修复方法：检查所有示例并改为 Client.from_env()；标明 v2 写法已弃用。

不好的发现含糊且不可执行：

代码示例可以写得更详细。(哪个示例？有什么问题？如何修复？)

规则

硬性规则（绝不违反）：

• 只输出一行判定：VERDICT: approve 或 VERDICT: revise——必须是该字面标记，独占一行，除此之外不输出任何内容。下游工具（_parse_verdict）会解析它。
• 评审，不撰写。 返回问题；不要重写、修正或补充指南。由撰写者进行修订。
• 以统一标准为准。 根据第 2 步的十四项条件（references/adoptability-bar.md，与作者撰写时采用的标准相同）进行评审。不要另设条件，也不要采用更严格的个人标准。
• 避免误判为需修订。 指南满足所有适用条件时，即使内容精简且只针对单一用途的工具，也应批准。只要篇幅适度，能帮助用户首次成功并覆盖交付的场景，就不算缺陷。只有存在明确指出的实际缺口时才要求修订。
• 避免误判为通过。 不要为了表示友好而对真正的缺口予以批准。阻断性缺口应判为 revise。
• 条件 14 不得重复扣分。 如果问题已由条件 1（目标组织）或条件 3（概念排序）捕捉到，不要再以可发现性（条件 14）为由提出问题；只有缺少或无法遵循的入门指引才判定条件 14 不通过。
• 虚构或过时的端点／能力属于缺口，而非依据不足（条件 9／条件 12）。示例调用了交付的上游内容中不存在的功能（或已因工具变更而移除），这是影响最大的缺陷。
• 必须链接目录，不得重复收录（条件 8）。
• 首次成功必须可验证（条件 2）——首次调用必须可运行、可验证，并提供预期输出；凭据必须通过环境变量提供，不得硬编码。
• 先讲概念，再讲操作示例（条件 3）。
• 修订仅限变更范围（条件 12）——评审变更、过时内容检查和变更历史，而非整份未变更的指南；不要仅因未重新论证未改动的操作示例，就误判一次内容干净、范围较小的修订。
• 根据指南收到的上游内容进行评审。 未交付的上游内容绝不能成为要求修订的理由——应将其标记为假设。但如果指南忽略了已交付的上游内容（例如某个场景没有对应操作示例，或示例与 api-reference 矛盾），则可作为合理的问题提出。
• 每条修订意见都必须可执行——指出未通过的条件、具体位置和明确的修复方法。

优先事项（可酌情调整）：

• 按严重程度排列问题——先列阻断性缺口（虚构／过时内容、缺少首次成功），再列轻微问题。
• 每条意见都注明条件编号／名称，便于作者对应标准。
• 批准时的备注应尽量少，并明确说明其不构成阻断问题。

易忽略的问题

• 为了完整而批准，而非为了可采用性。 各个章节都齐全，开发者仍可能无法集成（首次调用无法验证、示例虚构了一个端点、概念放在操作指南之后）。评判标准应是开发者能否采用 + 集成 + 运维，而不是模板是否填满。
• 可运行示例中隐藏的虚构端点。 将每个关键示例与提交的 api-reference/feature-spec（条件 9）逐一抽查——这是影响最大的主要缺陷。
• 工具变更后过时的示例。 修改时，示例仍调用已移除或重命名的功能；读起来没问题，一运行就出错——这是主要的修改缺陷（条件 12）。执行过时内容检查。
• 目录在正文中重新罗列。 指南为了方便，可能会用参数表重现所有端点——于是多出一份会逐渐过时的副本（条件 8）。这类内容看起来很全面，很容易被放行。
• 把概念塞进操作指南。 心智模型被零散地解释在操作步骤中，读者还没建立模型就先看到了代码（条件 3）。看似完整，实则不然。
• Diataxis 模式混杂。 “入门教程”实际上是参考文档的堆砌，或者教程与查阅指南被合并在一起（条件 7）。模式混杂后读起来没问题，却既不适合学习，也不便于查阅。
• 重复处罚可查找性问题。 针对端点堆砌（属于条件 1）或概念放在操作指南之后（属于条件 3）而提高条件 14 的判定，会夸大审查问题。条件 14 仅针对缺失或无法遵循的入门指引。
• 过度标记故障排查问题。 功能单一、轻量的工具将常见错误纳入入门指南是合理取舍，并不代表缺少条件 13。只有当工具的错误情况确实需要时，才要求专门的故障排查章节。
• 过度标记缺少上游文档。 非 API 的 CLI 没有可供链接或准确性核对的 api-reference——这是需要注明的假设，不是需要修改的问题。
• 系统性过度标记（误判为需修改）。 被要求找问题的审查者容易过度纠正，把合格的指南判为有缺陷。只有存在明确指出的真实缺陷时，条件才算存在差距；不能仅因为某个章节不是你会采用的写法就判定有问题。听起来似是而非的小问题，是此处审查错误的主要来源。
• 误判篇幅适中的指南需要修改。 功能单一、轻量的工具，指南规模小是恰当的。因内容简短而凭空制造缺陷，会引发本可避免的反复修改；应根据工具类型调整标准。
• 混淆开发者指南与用户指南或 api-reference 的审核标准。 开发者指南讲述开发者如何采用工具；不要用终端用户易用性或目录完整性的标准来评判。
• 判定标记格式不一致。 “Approved”“LGTM”“needs work”或埋在段落中间的判定都无法解析。请单独一行输出字面内容 VERDICT: approve|revise。

反模式

• 盖章式批准。 草草浏览后就批准，只为避免来回修改——设置审核关卡是为了发现开发者无法据此集成的指南；放过虚构的端点或从未验证的首次调用，会让开发者卡在第一步。
• 吹毛求疵式修改。 因章节顺序偏好、文风或被包装成缺漏的锦上添花项而阻止通过。只有真正阻碍采用或准确性的缺漏才需要修改。
• 悄悄重写。 “直接把示例修好更省事”——在评审过程中编写内容，会打破产出与评判之间的分工。
• 臆造条件。 添加标准中没有的私有要求（“还应该包含 Postman 集合 / 视频 / 名为‘故障排除’的标题”），会导致评审标准偏离产出标准。只评判这 14 项条件——那些方法角度（文档即代码 / CI、IA 技术、无障碍检查清单、类型叠加、评分标准）都是辅助方法，依据结果评判，绝不能强制要求。
• 贪大求全。 要求一个轻量、单一用途工具的指南涵盖完整而广泛的方案、webhook、迁移矩阵和专门的故障排除章节。标准要求的是首次可验证的成功，以及涵盖已提交的场景，而不是尽可能长的指南。
• 跳过上游 / 过时情况抽查。 仅凭看起来合理就批准代码示例。准确性（cond-9）和修订时检查过时内容（cond-12）是影响最大的维度；绝不能跳过。
• 模棱两可的结论。 “基本批准，但是……”或写两行结论。必须只有一个决定，且恰好使用一个标记。

输出

针对一份开发者指南，给出单一评审结果：

• 一行结论 — VERDICT: approve 或 VERDICT: revise，逐字照写，单独占一行。
• 发现 — 若为 revise，每个阻塞性缺漏对应一条可执行的发现（未通过的条件 + 位置 + 具体修复方法）；若为 approve，可选提供非阻塞性备注。

抽象的使用者是负责协调 produce->review 循环的任何对象：approve 表示接受该指南，供集成开发者使用；revise 则将发现返回给产出者，进行范围明确的修订。

相关内容

• authoring-developer-guide — 这对技能中负责产出的部分；它撰写的指南遵循本技能评判的同一套 14 项可采用性与准确性标准。将二者配对后，标准以 references/adoptability-bar.md 为唯一来源，避免产出与评审标准出现偏差。
• user-guide-review 技能 — 面向终端用户产品指南（非技术性内容）的评审关卡。文档、受众和标准均不同；本技能评判开发者能否采用指南，而非终端用户能否使用产品。
• api-reference-review 技能 — 面向完整端点 / 符号目录的评审关卡。文档和标准均不同；本技能评判的是链接到该目录的开发者叙述性指南。
• design-review 技能 — 面向工程设计文档（架构规范、设计文档、ADR、RFC）的评审关卡，会根据代码库核验其中的论述。关卡和标准均不同；不适用于开发者指南。
• 开发者指南模板 / 内容模板工具 — 负责章节结构；本技能评判的是质量是否达到标准，而非结构是否符合要求。

渐进式披露

• references/adoptability-bar.md — 作为唯一来源的 14 项可采用性与准确性标准（authoring-developer-guide 产出时采用的同一套标准）：逐项列出通过 / 缺漏信号和已完成的发现示例，包括新增的 cond-12（修订时检查过时内容）、cond-13（故障排除）、cond-14（可发现性与重叠防护），以及深入扩展的 cond-2/6/9。加载此文件以详细应用该标准。
• references/sources.md — 评审方法的研究溯源：作为唯一来源的可采用性与准确性标准、Diataxis 模式分离准则、链接而非重复规则、修订时检查过时内容，以及关于评审者过度纠正的证据（这些证据支撑了避免错误要求修改的原则）。仅在审查指导依据时加载。

Body budget

• description <= 1,024 chars (agentskills.io cap). Claude truncates the combined description + when_to_use at 1,536 chars in the skill listing.
• Body <= ~500 lines / 5,000 tokens — kept in context every turn.
• Per reference file: warn >10k tokens, error >25k. Total references: warn >25k tokens, error >50k.