DV-01 · API 文档与代码同步巡检

① 场景引入

一、这件事现在是什么样

研发与开发者文档 · 真实业务触发

优选百货的集成联调群炸了：客户开发者按文档示例调 `/settlement/reconcile`，返回的 `amount` 字段在文档里是字符串、实际是数字，联调直接报错——排查发现该端点在 v2.1 灰度中改了返回结构，文档站还停在 v2.0；技术负责人要求本周内给出「还有多少个端点是这样的」的完整答案。

二、痛点 · 每条都有来源

147% 的组织承认 API 文档与实际实现不同步、只有 5% 认为自己的文档「非常好」；「没时间」是文档质量最大障碍依据 · SmartBear 2020 State of API（1,500+ 开发者）：47% 的组织承认 API 文档与实际实现不同步，只有 5% 认为自己的文档「非常好」；64% 表示「没时间」是文档质量最大障碍；70% 的开发者把代码示例列为文档最重要组成部分239% 把「文档不一致」列为最大协作障碍；44% 的开发者只能直接翻源码来理解 API 行为；68% 认为过时文档是最大挫败依据 · Postman 2024 State of the API（5,600+ 开发者）：39% 把「文档不一致」列为最大协作障碍；44% 的开发者只能直接翻源码来理解 API 行为；68% 认为过时文档是与 API 工作的最大挫败375% 的生产 API 与其 OpenAPI 规范存在实测偏差；71% 的开发者曾因更好的文档而弃用一个 API——文档就是产品的销售页依据 · Nordic APIs /

APIContext 实测研究：75% 的生产 API 与其 OpenAPI 规范存在偏差；71% 的开发者曾因更好的文档而选择 A API 弃用B API4技术写手与开发者的真实配比从 1:12 到 1:200——靠人力追代码变更速度在数学上就不成立依据 · 技术写作配比综述：常被引用的目标是 1:7 至 1:10，但真实世界的比例从 1:12 到 1:200 不等——写手配比根本追不上代码变更速度554.3% 认为缺乏文档是消费 API 的最大障碍，四年后（2023，40,000+ 受访者）仍是 52%——这不是态度问题，是结构问题依据 · Postman 2020 State of the API（13,500+ 开发者）：54.3% 认为缺乏文档是消费 API 的最大障碍；2023 年（40,000+ 受访者）该数字仍维持 52%6「产文档的系统与发代码的系统从不在同一个房间」——PR 合并那一刻，文档更新进了 backlog，而 backlog 是良好愿望安享晚年的地方依据 · 已被验证的解法：Squarespace 与 Grab 均把文档放进代码仓库、走同一套 PR 评审与 CI/CD——「改端点的 PR 必须同时改文档，否则都不许上线」；文档错误的根因是「产文档的系统与发代码的系统从不在同一个房间」7Stack Overflow 2025（800+ 开发者）：只有 30% 的开发者每天写文档、近 40% 每周都不写——初级开发者最依赖文档，而资深开发者花在文档上的时间最少依据 · Stack Overflow2025 补充调研（800+ 开发者）：只有 30% 的开发者每天写文档，近 40% 每周都不写；初级开发者最依赖文档，而资深开发者花在文档上的时间最少

三、换个做法之后

变化不在「快」，在「参与的角色」和「覆盖的范围」

✕ 现在的做法

• 47% 的组织承认 API 文档与实际实现不同步、只有 5% 认为自己的文档「非常好」；「没时间」是文档质量最大障碍39% 把「文档不一致」列为最大协作障碍；44% 的开发者只能直接翻源码来理解 API 行为；68% 认为过时文档是最大挫败75% 的生产 API 与其 OpenAPI 规范存在实测偏差；71% 的开发者曾因更好的文档而弃用一个 API——文档就是产品的销售页技术写手与开发者的真实配比从 1:12 到 1:200——靠人力追代码变更速度在数学上就不成立

✓ 交给 Agent 之后

• 多来源文件一次读入，先做口径与完整性校验，再开始算
• 每条结论绑定来源文件、字段或条号，可以被审
• 产出是企业真会流转的正式件（带签批栏），不是一张展示用的表
• 该拦的地方给出「现在还不能提交」，并给不用干等的替代方案

四、场景闭环

5 步 · 每一步的产出都是下一步的输入

1. 端点清单对齐文档站 × 规范 × 代码三方取并集，缺文档的端点单列
2. 逐端点漂移检测参数/返回结构/示例代码/状态码四类漂移逐条登记
3. 影响面挂接每条漂移联到「哪些客户在用」（联调工单+集成登记表）
4. 修复优先级排序客户在用的漂移优先，无客户的进待办池
5. 巡检报告与修复任务派发逐端点清单 + 修复建议 + 派发状态，周度滚动

要准备什么：API 文档站全量（或核心端点文档导出）63 个端点的当前文档态——漂移的一方OpenAPI/Swagger 规范文件理想态基准——有规范就能机读对照（没有则标注退化路径）近期合并记录与发版说明v2.1 灰度改了哪些端点——漂移的另一方客户集成联调工单谁在用哪个端点——影响面与修复优先级的依据

为什么这个场景值得做

优先级评分：痛感 4 × AI 适配 4 ÷ 落地难度 2 = 8.8

最大差异点：不是「帮开发者写文档」：巡检的输入是文档站、OpenAPI 规范、近期合并记录三方对照，输出是逐端点的漂移清单（参数/返回/示例/状态码四类漂移）+ 每条的影响面（哪些客户在用这个端点——来自联调工单与集成登记表）。修复优先级按「客户在用的漂移优先」排，而不是按发现顺序排。

评分口径：痛感看「这事没做好谁会生气、生气到什么程度」；

AI 适配看「输入是否非结构化、是否要跨部门取数、错了能不能当场看出来」；

落地难度是分母 —— 需要客户先做数据治理的场景，分数会被压得很低。

五、会产出什么

判断标准只有一个：这份东西能不能直接进企业的流程

• 正式件本体：API文档同步巡检报告.xlsx 正式件 · 63 端点 × 漂移四分类 × 影响面 × 修复优先级 · 含研发负责人签批栏
• 可派发清单：本周修复任务清单.xlsx 客户在用的 9 处漂移 · 端点/修复建议/负责人/期限 · 每天可跟
• 可派发清单：待办池与环境问题移交单.xlsx 无客户漂移 8 处 + 环境问题 3 处 · 转研发待办与运维

这套东西不承诺什么：巡检只对照「文档/规范/代码实际行为」三方给出漂移清单，不直接改文档——修复由研发在评审后执行；生产环境的实际行为验证只用只读调用，不碰数据；示例代码的核对以「可运行」为准，风格问题不进清单。

② Live Demo（演示逐步）

演示模式 · 可视化预演 本页展示的是「应该怎么跑、每一步看什么、交付什么」，用的是真实业务格式的脱敏构造数据， 不宣称已接入客户生产系统，也不承诺任何效率提升百分比。

案例设定：明衡软件研发部。云梭 SCM 文档站 63 端点本周巡检：发现漂移 17 处（返回结构 6 + 参数说明 5 + 示例失效 4 + 状态码 2），其中客户在用 9 处、无客户 8 处；另有环境问题 3 处与文档无关，移交运维。

输入文件4 份巡检范围63 端点 · 全量漂移17 处 · 四类客户在用9 处 · 本周修

输入软件公司手上能拿到的东西

不需要整理格式、不需要改文件名 · 直接拖进对话框

• 01_API端点台账_63端点.xlsx 全量 API 端点台账——巡检范围的底账研发部维护 · 随版本更新
• 02_文档站导出_当前版.xlsx 文档站当前版导出——漂移对照的「文档侧」文档站导出 · 本周一
• 03_代码合并记录_近两周.xlsx 近两周 PR 合并记录——漂移对照的「代码侧」研发部导出 · 每周五
• 04_客户集成在用清单.xlsx 集成方在用端点清单——漂移影响面与修复优先级的依据客户成功部维护 · 每月更新

注意标橙色那一份 —— 02_文档站导出_当前版.xlsx。它文档站导出 ·本周一，平时压根不在核对范围里。这个场景的价值，很大一部分就来自把它读进来。

提示词就说这么几句

没有模板、没有表单 · 专业规则由 Skill 兜底

优选百货联调炸了：`/settlement/reconcile` 的 `amount` 字段文档写的字符串、实际返回数字。技术负责人要答案：还有多少端点是这样。 这是文档站 63 个端点的导出，这是 OpenAPI 规范，这是 v2.1 灰度以来的合并记录，这是联调工单和集成登记表。 帮我做全量巡检：

1. 逐端点对三方（文档/规范/代码），漂移按参数、返回结构、示例、状态码分类登记。
2. 每条漂移挂上影响面——哪些客户在用这个端点，工单里有没有已经在炸的。
3. 修复优先级按「客户在用优先」排，没客户的进待办池。
4. 文档和代码一致但示例跑不通的，单独挑出来——那是环境问题不是漂移，别混进来。 周度滚动，下周只报新增和修复的进出账。

漂移四分类、影响面挂接规则、Breaking 级判定在能力包里；现场需要的是文档站导出、规范文件、合并记录三样

——没有规范的团队走退化路径（文档对代码直比）。

触发文档站 63 端点对照代码 · 本周捞出 17 处漂移

文档与代码的对照从「想起来才查」变成每周固定动作

漂移不是事故，是默认状态——每一次「改端点但没改文档」的 PR都在制造漂移。巡检做的第一件事是让漂移有台账：新增几处、修复几处、还剩几处，肉眼可见地收敛。

第 1 步 · 四类漂移总览 · 17 处 = 客户在用 9 + 无客户 8

另有环境问题 3 处不属漂移——分类错了责任方就错了

第 3 步 · 客户影响面 · 6 家集成方 28 个在用端点，涉及漂移 9 处

联调炸群的那天能当场回答「还有多少处类似」

第 4 步 · 本周修复清单 · 9 处按客户分组，每组带期限

客户在用的先修，无客户的 8 处排进下迭代

IO成稿 · 巡检报告 + 修复清单 + 移交单

不讲省了多久 · 讲少了几个隐患、沉淀了什么

③ 能力沉淀（Skill / 提示词 / 预期输出 / 人工边界）

1. Skill 能力包

导入之后，同类任务会自动按这套规则走 —— 提示词才能写得那么短

API 文档与代码同步巡检 —— 75% 的生产 API 和它们的规范对不上 · Skill

SKILL.md 主本 + references（输出骨架 / 判据 / 渲染脚本）· 符合 WorkBuddy Skill 规范

版本 v1.0

api-doc-code-sync-audit.zip

在 WorkBuddy 里直接上传这个 zip 即可导入

包内结构

• SKILL.md 主本 —— YAML 元信息 + 执行流程 + 硬规则 + 人工边界
• references/output_template.md 输出骨架（sheet 名 / 分区顺序 / 列头）+ 可直接运行的渲染脚本
• references/judgement_rules.md 判据与口径 —— 什么情况算异常、什么情况必须拦住

references 不会一次性全读进来 —— Agent 按需取用。所以 Skill 可以写得很细，不会拖慢每次对话。

2. 原始素材

这些就是软件公司手上真实能拿到的东西 —— 格式不统一是常态，不是问题

📁DV-01 · 演示素材

脱敏构造数据 · 真实业务格式 · 埋点可核验

共 4 份

• 01_API端点台账_63端点.xlsx 全量 API 端点台账——巡检范围的底账
• 02_文档站导出_当前版.xlsx 文档站当前版导出——漂移对照的「文档侧」
• 03_代码合并记录_近两周.xlsx 近两周 PR 合并记录——漂移对照的「代码侧」
• 04_客户集成在用清单.xlsx 集成方在用端点清单——漂移影响面与修复优先级的依据

怎么用

• 把素材全部拖进 WorkBuddy 对话框（不需要整理格式、不需要改文件名）
• 粘贴下方提示词发送
• 拿到正式件初稿 —— 签批栏留空，推荐意见留空，由你填

3. 提示词卡片

优选百货联调炸了：`/settlement/reconcile` 的 `amount` 字段文档写的字符串、实际返回数字。技术负责人要答案：还有多少端点是这样。 这是文档站 63 个端点的导出，这是 OpenAPI 规范，这是 v2.1 灰度以来的合并记录，这是联调工单和集成登记表。 帮我做全量巡检：

1. 逐端点对三方（文档/规范/代码），漂移按参数、返回结构、示例、状态码分类登记。
2. 每条漂移挂上影响面——哪些客户在用这个端点，工单里有没有已经在炸的。
3. 修复优先级按「客户在用优先」排，没客户的进待办池。
4. 文档和代码一致但示例跑不通的，单独挑出来——那是环境问题不是漂移，别混进来。 周度滚动，下周只报新增和修复的进出账。

为什么这么短就够了：漂移四分类、影响面挂接规则、Breaking 级判定在能力包里；现场需要的是文档站导出、规范文件、合并记录三样——没有规范的团队走退化路径（文档对代码直比）。

换成你自己的业务：把素材换成你手上的真实文件即可。导入 Skill 之后，

该走几步、什么口径、什么情况必须拦住，Agent 自己知道 —— 你只需要说清这是什么事。

自己组织输入的三步法

• 用自然语言说清核心需求 —— 就按平时跟同事交代活的方式说：什么事、什么文件、什么要求。不用讲究格式。
• 调用 Skill 补齐专业规则 —— 导入本页 Skill 后，流程、口径、硬规则 Agent 自己知道。
• 用「增强提示词」补全遗漏 —— 输入框旁边有增强按钮，把随口说的话补成更完整的表述。

分工：自然语言负责「这是什么事」，Skill 负责「该怎么做」，增强提示词负责「别漏了什么」。

4. 预期输出

不方便现场跑的时候可以直接拿这份给客户看 · 与实跑结果同结构

📋正式交付物

带签批栏 / 冻结首行 / 开筛选 —— 判断标准是「能不能直接进企业的流程」

共 3 份

• DV-01_API文档同步巡检报告.xlsx 正式件 · 63 端点 × 漂移四分类 × 影响面 × 修复优先级 · 含研发负责人签批栏
• DV-01_本周修复任务清单.xlsx 客户在用的 9 处漂移 · 端点/修复建议/负责人/期限 · 每天可跟下载
• ↓XLSDV-01_待办池与环境问题移交单.xlsx 无客户漂移 8 处 + 环境问题 3 处 · 转研发待办与运维

Skill 里固化了什么：`/settlement/reconcile` 的漂移被完整还原了63 个端点巡检完，漂移不止一处排除性结论把技术动作翻译成钱

输入清单：API 文档站全量（或核心端点文档导出）63 个端点的当前文档态——漂移的一方OpenAPI/Swagger 规范文件理想态基准——有规范就能机读对照（没有则标注退化路径）近期合并记录与发版说明v2.1 灰度改了哪些端点——漂移的另一方客户集成联调工单谁在用哪个端点——影响面与修复优先级的依据

人工边界：巡检只对照「文档/规范/代码实际行为」三方给出漂移清单，不直接改文档——修复由研发在评审后执行；生产环境的实际行为验证只用只读调用，不碰数据；示例代码的核对以「可运行」为准，风格问题不进清单。

升为客户真实案例还缺什么：客户当前真实输入文件（不要整理过的）岗位现行 SOP 与审批链（金额分档、谁签字）至少一次真实出过问题的案例客户当前正在用的正式输出模板客户确认的阈值口径（多少天算临期、多少金额算大额）

5. 同一角色下的其他场景

研发与开发者文档 · 产出即下一步输入

• DV-02 · 发布说明与迁移指南起草：发了 changelog 不等于更新了文档，这是两件事

上下游串起来就是完整链路。每一步的产出都是下一步的输入，不用在不同工具之间来回复制粘贴。

场景内容基于 WorkBuddy 产品能力整理，演示中的企业、人物与数据均为虚构，不代表任何客户的实际成效；痛点引用的公开来源已做脱敏处理。网页版由原资料转换，部分演示表格以原文形式展示。