当文档中的代码示例无法编译、复制粘贴失败或 API…

为开发者文档中的代码示例建立可执行标准，并对现有示例库进行审计、分级和修复排序。

适用场景

解决思路

1. 先做范围检查：确认任务确实关于示例库；若只是写快速入门页、教学教程、文档信息架构、API 参考完整性、面向编码代理的文档，或审查产品自身源码，则转到对应技能。
2. 通过访谈确认：示例所在位置与范围、产品类型、发布语言及读者最常用语言、当前是否有执行机制、谁负责正确性、什么会触发示例失效、是新建政策还是审计还是两者、可投入的资源与截止日期、是一次性清理还是持续标准。其中问题 4、8、9、10 决定执行层级排序，必须先问。
3. 先做清单再审计：机械枚举每个已发布示例的文件、行号、语言、所在界面和最后提交日期；可运行 `scripts/sample-audit.py <docs-dir>`，否则手工遍历构建同样表格。
4. 用 ROT 三角法（冗余、过时、琐碎）做第一轮筛选：标记重复示例、引用已移除 API 的过时示例、没有场景的单调用琐碎片段；删除是合法结果。
5. 按执行层级对每个示例分类：Run（执行并断言输出）、Compile-only（只构建/类型检查，不执行）、Illustrative（伪代码、片段或故意反例）。每个示例只能属于一个层级。
6. 用 `./references/sample-policy-template.md` 起草政策，填满每个决策；未填的决策会在首次评审时变成争论。
7. 按 `./references/language-parity-matrix.md` 设置语言层级并构建对等矩阵；公布层级，未声明的层级会被读作疏忽而非决策。
8. 按 `./references/audit-method.md` 分两轮审计：对 100% 示例库做机械检查，再按语言、产品领域和年龄分层抽样做评分；对每个示例应用 `./references/audit-checklist.md`。发现以「主张 → 证据位置 → 一句话修复」报告，按严重度分组，不要写成散文段落。
9. 按 `./references/verification-patterns.md` 设计验证：哪个层级在哪里运行、示例如何从已测试代码单一来源化、CI 任务安装什么、fixture 如何清理。
10. 按 `./references/governance-and-ownership.md` 分配所有权与治理：具体回答「周五下午 CI 中示例变红时落到谁的队列」，并用 code-owner 规则和阻断检查编码该答案，而不是写成一段话。
11. 排序修复队列：P0 按危害优先（凭证或破坏性命令高于任何比率）；其余按（受影响读者数 × 严重度）÷ 修复成本排序，并在报告中说明这是比率而非严重度列表；当低流量示例位于采用路径上时手动提升。
12. 按通过阈值重新测量并迭代，直到达标；若不达标则诚实报告分数，并标注哪些数字是基线而非基准。
13. 记录决策：若环境有持久记忆，存储层级分配、语言层级、所有权和被拒绝的范围，避免后续文档工作重新争论。
14. 执行层级规则：无层级示例默认 Run（声明分配规则，不是投资建议）；Illustrative 必须在渲染页面中可见标注；优先使用语言原生 doctest 设施而非定制 harness；注意断言可选生态中缺少预期输出标记的示例会通过 CI 却从未真正运行。
15. 明确六个政策决策：覆盖范围（哪些场景值得示例，优先多步场景而非单 API 调用）、结构（所有 import、显式客户端设置、单一代码路径、预期输出、顶部注释说明用途和假设）、安全（无提示符、尖括号占位符、保留范围主机和地址、无真实感凭证、无禁用 TLS、无无保护的破坏性命令）、对等（哪些语言是一级，跨语言「同一示例」的含义）、验证（层级、来源、CI 运行内容和时间表）、所有权与新鲜度（谁修复红色示例，最后成功运行的最大年龄）。
16. 应用两条消除整类缺陷的规则：对正常操作中会失败的 API 展示一条失败路径；将认证设置集中在一处供其他示例链接，而不是重复变体。
17. 按严重度锚点分类发现：P0 危害复制者（凭证、破坏性命令、不安全默认、数据丢失）；P1 按原样无法工作（编译错误、已移除符号、缺失 import、错误输出）；P2 能工作但违反政策（缺少层级、提示符、无预期输出、对等缺口）。
18. 按通过阈值检查：已弃用 API 率低于 43%（Zhou 和 Walker FSE 2016 的测量值，作为门槛是本技能的选择）；零 P0 且采用路径上 100% 示例为 Run 且 CI 绿色；编译/运行通过率 ≥90%；≥80% 示例库为 Run 或 Compile-only 且由 CI 执行；一级语言对等覆盖 ≥90% 且无示例最后成功运行超过新鲜度窗口。
19. 跟踪 KPI：已测试示例占比和对等覆盖按发布而非按审计跟踪；红色 CI 示例到合并修复的平均时间；逐字引用示例的支持工单或 issue；每个示例的复制按钮点击（高复制示例优先获得 Run 层级）；示例年龄分布；各维度评分随时间变化而非总分。
20. 避免常见失败模式：CI 从工作树安装而非已发布产物；因不稳定失败禁用示例套件；因省略 import 导致片段无法运行；读者逐字粘贴占位符；同一场景跨语言行为不同；审计只通读顶部页面；政策写了但从不重新审计；为风格而非正确性重写示例；文档构建绿色而示例红色；给手工粘贴的 Markdown 分配所有者；引用无法溯源的基准。

适用边界 · 注意事项

• 任务只是写一个从零到首次成功的快速入门页面时，应使用 quickstart 技能。
• 任务是教学教程而非其中的示例时，应使用 tutorial 技能。
• 问题是内容在文档站点中的位置时，应使用文档信息架构技能。
• 任务是 API 参考页面逐端点完整性时，应使用 API reference 技能。
• 目标读者是编码代理而非人类时，应使用 agent-documentation 技能。
• 被审查的代码是产品自身源码而非已发布示例时，这是代码审查而非文档任务。