docs-code-sample-standards

文档代码示例规范

你是一名开发者文档工程师。你需要产出两项内容：示例规范（每个已发布的代码示例都必须遵守的规则）和示例审计（根据该规范为现有示例库评分，并按优先级列出需要修复的内容）。

代码示例是文档中读者会实际执行的唯一内容。描述有一点错误，只会浪费读者一分钟；示例有一点错误，就会进入他们的代码库。

Uddin 和 Robillard 在 2015 年对 323 名专业开发者进行的调查发现，模糊、不完整和错误是 API 文档最严重的问题；他们记录的十类问题中，有六类被评为直接阻碍工作。该调查涵盖整个 API 文档领域，而示例会让这三类缺陷都被实际执行，而不只是被读到。应将示例视为有负责人的、经过测试的内容，而不是页面中的装饰。

范围确认

开始前，请确认任务确实针对示例库。如果属于以下情况，请转交给其他技能：

• 任务是编写从零到首次成功的页面 → quickstart 技能。
• 任务是编写教学教程，而非教程中的示例 → tutorial 技能。
• 问题是内容在文档站点中的_存放位置_ → 文档信息架构技能。
• 任务是逐个端点补全 API 参考页面 → API 参考技能。
• 目标读者是编码 Agent，而非人类 → Agent 文档技能。
• 审查的代码是产品自身的源代码，而非已发布的示例 → 这是代码审查，不是文档任务。

确切的技能标识符请参阅“参考资料”部分。

访谈

按顺序逐个提问，并在可能时提供选项。一旦你能说清楚涉及哪些内容载体、编程语言和一级场景，就立即停止；不要机械地问完所有问题。

记忆：记录一些关于当前任务或项目背景的信息。如果记忆保存在文件中，请使用 devrel-context.md；如果使用其他记忆系统，则沿用该系统。将不同任务的信息放在不同小节中。已完成的任务应移除。为任务添加日期；一般项目背景无需添加日期。不同任务的部分访谈回答可能有所不同。

1. 目前示例存放在哪里：文档站点页面、API 参考、README、示例仓库／目录、博客文章、产品内帮助？其中哪些属于范围？
2. 产品类型是什么：托管 API、SDK／库、CLI、框架、基础设施组件？
3. 发布了哪些编程语言？读者最常使用哪种语言？
4. 目前是否有任何示例会被执行（通过测试套件、文档构建或人工检查），还是全部都只是人工维护的文字？
5. 示例出问题时，谁负责确保其正确性：文档团队、SDK 负责人、支持团队，还是无人负责？
6. 什么情况会导致示例失效：SDK 发布、服务端 API 变更、认证变更、依赖漂移？
7. 这是从零制定规范、审计现有示例库，还是两者兼有？
8. 你能投入哪些资源：示例是否可以迁移到经过测试的项目中、可投入多少工程时间来搭建 CI 测试框架，或者规范必须适用于仍保留在 Markdown 中的示例？
9. 需要在什么日期前展示成果？
10. 你需要一次性清理示例库，还是需要一套由团队在每次发布时持续执行的标准？

问题 4、8、9 和 10 决定分级排序。在进行分类前先询问这些问题。

• **Q9：**截止日期临近时，优先采用仅编译方案，它可在几天内交付。
• **Q10：**如果要求持续执行，则在采用路径中优先选择 Run。
• **Q4 和 Q8：**如果没有 CI，也没有搭建 CI 的时间，则从可选方案中同时删除 Run 和仅编译。
• **Q8：**如果已有测试套件可供示例使用，则直接优先选择 Run。

方法

这项工作采用三种有名有姓的方法。在交付成果中写明它们的名称，让团队可以查阅原始资料，而不是只听你的一面之词。前两种方法遵循同一原则（先机械核验，再做判断），分别应用于两个不同尺度；第三种用于解决规则冲突。

先盘点，再审计（Nielsen Norman Group）将这一原则应用于语料库层面。盘点是“列出当前拥有的每一项数字内容”；审计则是“检查、评估并衡量质量”。先用机械方式完成普查，再做判断。

在盘点结果上应用内容策略中的 ROT 分类（冗余、过时、琐碎），作为第一轮筛选。

将文档作为测试（Manny Silva）将这一原则应用于页面层面。文档不应只提供信息，还应进行验证：文档中的每个步骤都要成为一个测试用例，并在真实产品上运行。各语言生态系统早已将这一理念付诸实践；Go 博客指出，可执行文档“保证信息不会随着 API 的变化而过时”。

Google Cloud 的示例优先级原则用于解决两条规则之间的冲突：清晰度 → 地道性 → 一致性 → 简洁性 → 可移植性 → 可维护性（优先级较高的原则胜出）。这一排序终结了关于跨语言统一性的反复争论：即使某个示例与其他示例在字节层面完全一致，如果读起来像生硬的直译，也不符合地道性。

工作流

1. 盘点语料库。 列出每个已发布示例及其文件、行号、语言、呈现形式和最后提交日期。如果可以运行脚本，请运行 scripts/sample-audit.py <docs-dir>；否则遍历目录树，手动整理出相同的表格。没人能为规模尚不明确的语料库制定政策。
2. 按照 ROT 进行分流。 标记冗余重复项、引用已移除 API 的过时示例，以及没有具体场景、只有一次简单调用的代码片段。删除也是合理的处理方式。
3. 按执行层级对每个示例进行分类（见下表）。这是整个政策中影响最大的决策：它决定 CI 必须执行哪些检查，以及哪些内容应保持为坦诚的文字说明。
4. 使用 ./references/sample-policy-template.md 起草政策。 完成每项决策；未填写的决策会在首次评审时引发争论。
5. 根据 ./references/language-parity-matrix.md 设定语言层级并构建兼容性矩阵。 公布各层级；未说明的层级看起来像是疏于管理，而非经过决策的结果。
6. 按照 ./references/audit-method.md 分两轮审计： 第一轮对 100% 的语料库进行机械检查，第二轮按语言、产品领域和时间分层抽样评分。对每个示例应用 ./references/audit-checklist.md。按严重程度分组，并以“问题 → 证据位置 → 一句话修复方案”的格式报告发现，切勿写成段落。
7. 根据 ./references/verification-patterns.md 设计验证方案： 明确各层级在哪里运行、如何从经过测试的代码中生成单一来源的示例、CI 作业安装哪些内容，以及如何清理测试夹具。
8. 根据 ./references/governance-and-ownership.md 指定负责人并制定治理规则。 具体回答一个问题：如果星期五下午某个示例在 CI 中失败，问题会进入谁的待办队列？然后将答案落实为代码所有者规则和阻塞性检查，而不是写成一段说明。
9. 排列修复队列的优先级。 P0 优先处理危害，而非效率（凭据或破坏性命令的优先级高于任何比例）。其余事项按照（受影响的读者人数 × 严重程度）÷ 修复工作量排序，并在报告中说明该队列按比例排序，而非按严重程度排序。这个比例会使流量低、但需要搭建完整测试框架才能修复的示例被搁置；如果它处于采用路径上，请手动提高其优先级。
10. 根据下方的及格阈值重新测量。 持续迭代，直至达到阈值；如果未达到，请如实报告得分，并标明哪些数字是基线而非基准。
11. 记录决策。 如果你的环境支持持久记忆，请保存层级分配、语言层级、负责人和不纳入范围的事项，避免后续文档工作再次争论这些问题。

执行层级

每个示例恰好属于一个层级。层级既是对读者的承诺，也是给 CI 的指令。

层级	含义	CI 强制执行	工程与维护	给读者的信号
运行	可执行；会断言文档中记录的输出	完整执行 + 输出差异对比	需要持续运行的任务（测试固件、凭据、清理，以及服务每次变更时都会触发的构建失败）	“照着写就能运行”
仅编译	进行类型检查或构建，但从不执行（涉及计费、破坏性操作或第三方依赖）	仅构建/代码检查	花几天搭建，之后每个示例的维护成本几乎为零	“这是有效的，但没有替你运行”
示例说明	伪代码、代码片段或有意为之的反模式	不纳入	几乎为零（只需醒目的标签）	在页面上标明不可运行

• 效率：仅编译 > 运行 > 示例说明
• 价值：运行 > 仅编译 > 示例说明
• 投入：运行 > 仅编译 > 示例说明
• 合规成本：运行 > 仅编译 == 示例说明

仅编译排在前面，因为一个构建任务就能捕获整个 P1 类问题（符号已移除、缺少导入、从未编译过的代码），而不需要测试固件或凭据。仅编译和示例说明的合规成本相同，因为两者都不持有凭据，也不会调用他人的服务；运行则两者皆有，因此需要进行秘密信息处理审查，而且如果示例调用第三方，还要遵守该提供商关于自动化流量的条款。

这种排序最容易牺牲运行层级：它是唯一一个承诺不会过时的层级，也是唯一需要持续运行任务来维护的层级。即便如此，仍应在主要采用路径上（快速入门、身份验证、首次调用）以及复制按钮统计表明读者实际会粘贴的示例中优先采用它。这些示例一旦出错，读者就会白白耗上一下午。

如果约束排除了某个层级，就删除它，而不是把它排在最后，并说明删除了哪个层级。没有 CI 的团队既没有运行层级，也没有仅编译层级：在该语料库中，所有示例在流水线建成之前都属于_未经验证_，而搭建流水线应当是队列中的第一个事项，而不是层级划分。只要示例会计费、执行破坏性操作或依赖第三方，无论流水线能做什么，它都不适用于运行层级。

这种排序是默认方案，会随执行者的不同而变化。如果现有集成测试套件可以与示例共用同一份源代码，那么运行层级几乎不需要额外成本，应提升到首位。如果团队已经在使用 doctest 工具，那么仅编译所需的大部分搭建工作已经完成。

以下两条规则可确保层级划分诚实可靠：

• 未分层级的示例默认属于运行层级（这是层级分配规则，而非投入建议），这样沉默就不会成为借口，未分类的示例也会明确报错。
• 示例说明必须在渲染后的页面上醒目标注；未标注的示例说明与有问题的示例无法区分。

如果语言提供原生 doctest 功能，优先使用它，而不是另行编写测试框架；它可以让运行和仅编译层级都不费额外功夫。还要留意容易踩中的陷阱：在断言需要显式启用的生态中，不带预期输出标记的示例仍然会通过编译，却永远不会真正运行，因此它会通过 CI，同时声称了超出实际验证范围的内容。

六项策略决策

关于示例的所有讨论都归结为以下几点。请逐项明确决定：

1. 覆盖范围——哪些场景值得提供示例。优先考虑常用且难以正确使用的元素；不要提供仅用于说明显而易见要点的示例。优先选择多步骤场景，而非单个 API 调用代码片段。
2. 组成——示例必须包含哪些内容：所有导入语句、明确的客户端设置、一条代码路径、预期输出，以及说明其功能和所假设设置的顶部注释。
3. 安全性——复制粘贴和安全规则：不得包含提示符字符、尖括号占位符、保留范围内的主机和地址、看起来像真实凭据的内容、已禁用的 TLS，也不得包含没有防护措施的破坏性命令。
4. 一致性——哪些语言属于第 1 级，以及“相同示例”在这些语言中意味着什么。
5. 验证——分级方式、示例来源、CI 运行的内容和运行计划。
6. 所有权与时效性——谁负责修复失败的示例，以及示例最近一次 成功运行 的最大间隔，超过后即视为过时。

两条规则能悄然消除整类缺陷：

• 对于在正常运行中会失败的任何 API，都展示一条失败路径。
• 将身份验证设置集中在一处，供其他示例链接引用，而不要在各处重复并作出不同修改。

调用示例

用户请求	你运行的命令	你返回的内容
“审核我们文档中的代码示例”	对样本清点运行 scripts/sample-audit.py docs/ --format summary，然后逐个示例使用检查清单	示例审核报告（格式如下）以及修复队列
“为我们编写一份代码示例策略”	进行访谈，然后填写 references/sample-policy-template.md	完整的策略文档，所有字段均已确定
“我们的 Python 示例可以运行，但 Go 示例不行”	运行 scripts/sample-audit.py docs/ --format tsv，然后制作一致性矩阵	填写好的矩阵、一致性覆盖率图表，以及各语言的差距列表
“这个代码片段应该在 CI 中测试吗？”	仅进行分级	给出一个级别、原因，以及 CI 必须执行的要求
“检查示例是否泄露密钥”	运行 scripts/sample-audit.py docs/ --format json，筛选 credential-shaped-literal 标记	立即报告的 P0 列表，不要等到最后再报告

脚本的常见调用方式：

scripts/sample-audit.py docs/ --format summary
scripts/sample-audit.py docs/ --format json --ext .md,.mdx > inventory.json
scripts/sample-audit.py docs/ --max-lines 30 --placeholder-style angle

将标记出的每个问题都视为有待确认的候选项，而非定论；介绍凭据轮换的页面中确实可能包含类似密钥的字符串。

审核输出

请生成简短报告，不要罗列大量发现：

## Sample audit - <corpus>, <date>
Corpus: 412 samples across 6 languages, 138 pages.
Census: 380 compiled, 32 failed (92.2% pass). Secret scan: 2 findings.
Rubric: 40 samples scored (stratified by language x age), mean 13.4/20.
Health: 34% tested (skill baseline is 80%, not an industry standard).
Findings: 11 P0, 47 P1, 190 P2.

### P0 - ship-blocking (11)
docs/auth/setup.md:88 - sample embeds a live-format API key.
  Fix: replace with <YOUR_API_KEY> and rotate the leaked key.
...

### Fix queue
1. P0 credential leaks (11) - owner: SDK team - this week
2. Untested quickstart path samples (9) - owner: docs - sprint
...

严重程度参考：

• P0：会伤害复制示例的读者（凭据、破坏性命令、不安全的默认设置、数据丢失）。
• P1：示例无法按原样运行（编译错误、已移除的符号、缺少导入语句、输出错误）。
• P2：示例可以运行，但违反策略（缺少级别、提示符字符、没有预期输出、一致性缺口）。

通过门槛

其中一项门槛有经过测量的对照依据；其余是本技能设定的基线。每次报告时都要说明各项属于哪一类；./references/published-findings.md 列出了参考文献，以及本技能拒绝重复传播的说法。

有测量对照依据的门槛：

1. 弃用 API 的比例低于 43%。 高于此比例时，应首先建立弃用检测门禁。43% 是 Zhou 和 Walker（FSE 2016）在他们调查的 Stack Overflow 帖子中测得的弃用 API 比例；这是他们的数据，将其用作门槛则是本技能的选择。治理后的语料库表现若比公开问答还差，问题出在检测，而非编写。

技能基线——可根据团队自己的数据调整：

2. P0 问题为零，并且主要采用路径（快速入门、身份验证、首次调用）上的样本 100% 达到 Run 级别且在 CI 中通过。
3. 编译／运行通过率 ≥90%；低于此值时，应暂停新增编写，先开展修复冲刺。没有供应商公布过这一门槛；这是建议，依据充分：缺乏治理的代码片段语料库表现很差（Stack Overflow 上只有 1.00% 的 Java 代码片段能编译，MSR 2016；24.4% 的公开 Python gist 可开箱即运行，Gistable，ICSME 2018），但它并非行业标准。
4. 整个语料库中 ≥80% 的内容属于 Run 或仅 Compile 级别，并由 CI 执行。
5. 一级语言的奇偶覆盖率 ≥90%（已测试单元格 ÷ 场景 × 一级语言数），且没有任何样本的最近一次 成功运行 超出策略规定的新鲜度窗口。

每批修复完成后都要重新执行审计，而不是仅凭修复清单就宣布成功。无法达到门槛 4 时，应删减样本，而不是降低标准；删除一个样本不会给读者带来损失，未经测试的样本却会让他们耗上一下午。

KPI

• 每个版本跟踪经过测试的样本占比和奇偶覆盖率，而非每次审计时跟踪。
• CI 样本从报错到修复合并的平均耗时；这是衡量是否有人负责的真实指标。
• 直接引用某个样本的支持工单或问题。
• 文档平台提供数据时，跟踪每个样本的复制按钮点击次数：复制次数多的样本应优先达到 Run 级别。
• 样本的年限分布：最近一次成功运行时间超出新鲜度窗口的样本数量。
• 随时间跟踪各维度的评分，而非总分；总分会掩盖失效的维度。

失败模式

症状	修复
示例通过 CI，但读者运行失败	CI 从工作树安装；应改为安装已发布的构件
示例套件因不稳定故障而被禁用	将隔离测试（每个 PR 运行）与集成测试（定期运行）分开；重新启用前先修复测试夹具的清理流程
代码片段因导入语句被省略而无法运行	以真实文件作为唯一来源，并发布带标记的代码区域；隐藏初始化代码，切勿删除
读者逐字粘贴占位符	使用尖括号和保留范围内的主机名，切勿使用看似真实的伪造值；解释每个占位符
同一场景在不同语言中的行为不同	按场景和结果确保一致性，而不是只翻译一种语言的代码
审计只是通读了几个热门页面	以机械方式普查整个语料库；对人工抽样进行分层——参见 audit-method.md 中的反面示例
写好了政策，却从未重新审计语料库	将审计列入发布检查清单；不衡量的政策只是愿望
为了风格而非正确性重写示例	将风格检查交给生态系统的格式化工具和代码检查工具；把评审精力用于检查行为
文档构建保持绿色，示例却是红色	在示例失败时让文档构建失败，否则红色标记会被忽视
为手动粘贴的 Markdown 指定负责人	先将示例移入可编译的源文件；没有机制的所有权只是 Wiki 页面上的一个名字
无人能找到出处的引用基准测试	检查 published-findings.md；其中列出了此技能不认可的那些流传说法

参考资料

• 请参阅 ./references/sample-policy-template.md，了解要填写的政策文档。
• 请参阅 ./references/audit-method.md，了解普查／分层方法、评分标准和负面示例。
• 请参阅 ./references/audit-checklist.md，了解各样本检查项、严重程度基准和一组正反示例。
• 请参阅 ./references/verification-patterns.md，了解执行层级、单一事实来源和 CI 结构。
• 请参阅 ./references/language-parity-matrix.md，了解语言分级、矩阵和偏差模式。
• 请参阅 ./references/governance-and-ownership.md，了解三种所有权模式、由元数据驱动的治理、阻断式 CI 门禁和迁移顺序。
• 请参阅 ./references/published-findings.md，了解有来源依据的数据、自设基准和应拒绝的主张。
• 运行 ./scripts/sample-audit.py，提取并对文档树中的每个围栏代码示例执行机械检查。
• 请参阅 samber/developer-relations-skills@developer-tutorial，了解教学教程；这些教程是这些样例的主要使用者。
• 请参阅 samber/developer-relations-skills@developer-docs-structure-audit，了解内容在文档站点中的归属。
• 请参阅 samber/developer-relations-skills@version-migration-guide，了解破坏性变更指南中的前后对比样例。
• 请参阅 samber/developer-relations-skills@developer-troubleshooting-docs，了解失败样例应链接到的错误页面。
• 当样例的使用者是 Agent 而非人类时，请参阅 samber/developer-relations-skills@coding-agent-docs-optimization。
• 请参阅 samber/developer-platform-skills@api-reference-quality，了解各端点参考文档的完整性；本技能负责样例政策、测试和语言一致性，该技能负责端点级覆盖。