依赖升级：让 AI 读 30 页变更说明，产出受影响调用点清单

一句话结论

把变更说明拆成条目喂给 AI，逐条检索代码库里的调用点，产出一张带文件路径和影响等级的升级影响清单。

这篇解决什么问题

上周同事在群里丢来一份 30 页的依赖库变更说明，说下周要升版本，问谁有空看看影响面。这种事我做过几轮，手工通读一遍通常要半天，还总是漏掉测试里的 mock 和配置文件里的字符串。

这篇写的就是我这次的完整做法：先把说明读薄成条目，再对着代码库逐条找调用点，最后落成一张能直接分活的表。适合那种大版本跨度大、说明几十页、仓库规模中等的升级；如果只是补丁版本里一两个 API 变了，直接翻 changelog 更快，不必走这套。

开始前要准备什么

• Cursor 编辑器，免费版就能跑完全流程
• Claude 网页版账号，免费额度按天计，跑一遍够用
• 变更说明原文一份，PDF 或 Markdown，30 页量级
• 本地 clone 好的代码仓库，能全局检索
• 预计耗时：第一次两小时上下，顺手后一小时以内

具体怎么做

第 1 步 · 把变更说明拆成条目

别整份往里贴。30 页一次性丢进去，模型会自己挑重点做摘要，中间章节的条目经常整段消失。我一般按章节分批，每批贴完让它报编号，最后检查编号有没有跳号。

你是一名后端研发。下面是一份依赖库变更说明的原文，我要把它拆成结构化条目表。
要求：
1. 按「不兼容变更 / 弃用警告 / 行为变化 / 新增能力」四类归并，弃用和新增不要混进破坏性变更里
2. 每条输出：编号、类别、涉及的 API 或配置项、旧写法、新写法、原文出处（页码或小节标题）
3. 原文表述含糊、没给迁移写法的，单独标注「需人工确认」，不要替我补全
4. 用 Markdown 表格输出，列名固定为：编号 | 类别 | API或配置项 | 旧写法 | 新写法 | 出处 | 备注
原文如下：
（在这里粘贴变更说明全文。超过 30 页请按章节分批，每次只贴一章，贴完等我确认再继续）

预期产出：一张二十到六十行不等的条目表，按四类分好，含糊的地方已经标了「需人工确认」。

第 2 步 · 在代码库里找调用点

这一步换到 Cursor 做，按 Cmd/Ctrl + L 打开对话框，用 @Codebase 让它在整个仓库里检索。很多人容易忽略的是，光搜 API 名远远不够，配置字符串、类型引用、mock 夹具里都藏着调用。

这是我整理出的依赖变更条目表（见下）。请在当前代码库中检索每一条的实际使用位置。
检索规则：
1. 对每个 API 名，同时搜索：直接调用、类型引用、配置文件里的字符串、mock 与测试夹具
2. 命中结果给出：文件路径、行号、所在函数名、代码片段（不超过 5 行）
3. 区分「生产代码」和「测试代码」，分别列出
4. 没有命中的条目明确写「未检索到」，不要略过，也不要猜
5. 输出 Markdown 表格，列为：条目编号 | 文件路径 | 行号 | 函数名 | 代码片段 | 代码类型
条目表如下：
（粘贴第 1 步产出的表格）

预期产出：一份检索结果表，生产代码和测试代码分开列，「未检索到」的条目也清清楚楚列在末尾。

第 3 步 · 给每条调用点定影响等级

定级是最容易糊弄过去的一步。模型很爱写「影响较小，建议后续处理」，这种结论对排期毫无帮助。我的办法是强制它引用原文出处，证据不够就写证据不够。

基于上面的调用点检索结果，给每一条调用点打影响等级。
等级定义：
– P0：不兼容变更且命中生产代码，不改造会编译失败或运行时报错
– P1：行为变化，代码能跑但结果可能不同
– P2：仅命中测试代码或注释
– P3：未检索到，但依赖声明仍然存在
判定要求：
1. 每条给一句话理由，理由里必须引用变更说明原文的表述，不要自己发挥
2. 信息不足以定级的，写「证据不足」，并列出还需要看哪个文件
3. 输出 Markdown 表格：条目编号 | 代码位置 | 影响等级 | 理由 | 证据出处

预期产出：一张带等级的调用点表，P0 条目基本就是这次升级必须改的部分。

第 4 步 · 合成升级影响清单

前三步的结果合起来才是能交出去的东西。我要求改造方案必须写具体动作，凡是出现「视情况调整」这类词的条目，一律打回重写。

把前面三步的结果合并成一份《升级影响清单》，Markdown 表格输出，列固定为：
序号 | 变更项 | 影响等级 | 代码位置（文件:行号） | 现状写法 | 改造方案 | 验证方式 | 负责人
补充要求：
1. 按影响等级从高到低排序，P0 在最前
2. 改造方案写具体动作，不要写「适配新版本」「视情况调整」这类空话
3. 验证方式写清楚跑哪个测试文件或手动触发哪个接口
4. 表格之后另起一段，列出「本次不处理的变更项」及原因
负责人一列先统一填「待分配」。

预期产出：一份可以直接贴进需求单的清单，P0 在前，末尾附本次不处理项。

第 5 步 · 抽样复核

清单出来别急着发。我通常会抽十几条回代码里对一遍，重点看 P1「行为变化」那一类，这里是定级偏差最集中的地方。

你是这次升级的复核人。请检查这份升级影响清单是否存在以下问题：
1. 变更说明里明确写了不兼容变更，但清单里没有对应条目
2. 条目引用的代码位置和前一步的检索结果对不上
3. 影响等级和理由自相矛盾
4. 改造方案里出现「视情况」「适当调整」这类无法执行的表述
逐条列出问题并给修正建议。没有问题的部分不用重复，只报问题。

预期产出：一份问题列表，可能只有三五条，改完清单基本就能用。

实测记录

最容易错的 3 个地方

1. 整份说明一次贴进去。模型会做摘要，中段条目被吞掉。纠正办法是按章节分批，每批结束检查编号是否连续。
2. 检索只写 API 名。配置字符串和 mock 夹具全漏。纠正办法是把四类检索位置写进提示词，并要求区分生产和测试。
3. 让 AI 直接下「影响不大」的结论。这种判断没法排期。纠正办法是强制引用原文出处，证据不足必须写明缺哪个文件。

可复用的东西

五段提示词可以串成一条流水线：拆条目、找调用点、定等级、合成清单、抽样复核。我把它们存成仓库 docs 目录下的一个 Markdown 文件，下次升级换个依赖名就能重跑。

这套方法本身不复杂，值钱的是那份「证据出处」的约束——它逼着模型少说漂亮话。你最近一次升级卡在哪个环节，是读说明还是找调用点？

如果你也经常要做这件事，欢迎在评论区说说你的卡点和做法；也可以留言告诉我，你想看哪个岗位的哪件活怎么用 AI 拆。

admin 普通

收藏 海报 链接