写或审计破坏性变更的版本迁移指南：按影响面排序…

当需要为库/SDK/CLI/框架/托管 API/数据库 schema 的重大版本升级编写或审计迁移指南时使用，产出让读者以最少阅读、最少意外完成 N→N+1 升级的文档。

适用场景

解决思路

1. 先做范围检查：若用户要的是逐版本发布清单→转 changelog 技能；若在决定版本方案、弃用窗口或日落政策→转 API versioning-policy 技能；若要在自己代码库执行升级→那是消费方任务；若要按错误文本索引日常故障页→转 troubleshooting-docs 技能；若读者需学习新版本概念→转 tutorial 技能。
2. 用两条定律判断是否该写指南：Churn Rule——凡是你控制消费方（内部服务、monorepo、你运营的平台），应自己完成迁移（codemod + 简短说明），只有消费方确实是别人的代码库时才写指南；Hyrum's Law——文档契约不等于影响面，未文档化的行为、时序、错误文本和 bug 兼容性都有人依赖，仅凭 changelog 做的清单必然不全。在工作笔记顶部写明你处于 Churn Rule 的哪一侧。
3. 选择指南类型：默认是库/SDK 形态；schema、云、移动端、浏览器/平台迁移差异大，schema 迁移是带每步回滚的操作 runbook 而非带代码片段的散文，非普通库/SDK 升级时先读 references/guide-types-beyond-libraries.md。
4. 做访谈（一次问一个，能多选就多选，知道版本对、表面和受众后就停）：1) 迁移对象是库/SDK、框架、CLI、托管 API、数据库 schema、移动应用还是多个独立版本化的表面；2) 覆盖哪个确切版本对，是否支持多版本跳跃（N-3 → N）还是只支持单跳；3) 谁升级：自选时机的开源用户、有通知窗口的付费客户，还是被强制要求的内部团队；4) 破坏性集合是否已冻结，还是清点本身就是本次工作；5) 有哪些自动化：codemod、兼容/迁移构建、lint 规则、版本固定头，还是没有；6) N-1 是否已对这些变更发出弃用警告，还是 N 冷启动就破坏；7) 是否有弃用 API 的使用遥测——谁受影响、多少人；8) 指南放在哪里、必须链接什么（changelog、release notes、支持渠道、状态页）；9) 相对发布必须何时发布——发布日期在版本内则排除过渡警告版本、强制单跳；10) 这是一次性重大版本，还是未来每个重大版本复用的形态——复用时保留兼容构建、RFC 门禁和稳定的逐变更锚点，一次性则三者都删；11) 迁移工具能投入多少工程小时、发布后谁维护——没有指定负责人就在成本核算前删掉兼容构建和 codemod。即使预期答案是否也要问第 7 题，遥测把「按影响面排序」从猜测变成测量，其缺失本身也值得写进指南计划。
5. 按项目已有条件重排路径形态与自动化优先级：已排期的过渡版本让分阶段路径免费；已有 codemod 语料让 codemod 免费；任一情况都把该选项提到默认顺序之前。
6. 工作流第 1 步——冻结范围：在工作笔记顶部写下版本对和表面列表并视为固定，悄悄扩到三个版本对的指南对任何一个都无益。
7. 工作流第 2 步——清点破坏项：从所有来源拉取，不只 changelog——两个 tag 之间的公共 API diff、changelog 的 Removed/Changed 条目、N-1 发出的弃用警告、你自己示例应用和内部消费方的迁移提交、早期采用者的支持工单；把每项分类为移除、重命名或签名变更、行为或默认值变更、要求下限、或线缆/格式变更。
8. 工作流第 3 步——估算影响面：用遥测、再依赖仓库搜索、再维护者估计，按多少读者会撞上排序；这个排序就是指南的顺序——绝不按字母、绝不按模块。
9. 工作流第 4 步——选择路径形态并在指南最前面说明。三种形态竞争，第四种是被强加的，按「为读者节省的小时数 / 你花在搭建跑道上的工程小时数」排序：分阶段（先升到 N-1 的最后一个 minor 让弃用警告在每个受影响调用点浮现，再跳；React v19 指南是参考措辞：先升 18.3，因为它除警告外与 18.2 相同；代价是一个过渡的仅警告版本，把每个读者的构建输出变成他们自己的清单；只要 N-1 还能发版就默认用它）；单跳（无跑道、你成本近零，全部破坏一次性落到读者头上；破坏集合一次坐得完，或 N-1 已冻结买不到分阶段路径时采用）；带兼容构建的增量（项目半迁移状态可上生产；常设工作：双行为路径、按特性开关和警告，直到兼容构建退役）；顺序桥接（不与其他三种排名，因为版本偏差政策强加而非你选择，如 Kubernetes 维护最近三个 minor 并约束组件偏差；适用时指南是 N→N+1 跳的链条，其他三种形态出局，在首屏说明；无政策适用时从菜单删除此形态而非列出）。价值与工程加维护成本：带兼容构建的增量 > 分阶段 > 单跳；效率：分阶段 > 单跳 > 带兼容构建的增量。该顺序会饿死兼容构建——它替读者省最多、你维护最贵；当消费方是无法把迁移分支停在移动 main 上的大型应用时把它提到默认之上（这就是框架建它而库不建的原因）；访谈中若发布后无人负责维护，直接删除而非列为选项，没人维护的兼容构建会让每个采用它的项目半迁移搁浅。
10. 工作流第 5 步——点名已知有问题的中间版本：若某个中间版本有回归，写明「跳过它，直接升到 X」并给原因，否则读者会按顺序规则升进你已知损坏的版本。
11. 工作流第 6 步——先写门槛：运行时和语言版本、peer 依赖、数据库或基础设施最低要求、构建工具要求；读者过不了门槛就永远到不了代码示例，把门槛埋在步骤 9 会浪费他们整个会话。
12. 工作流第 7 步——每个破坏性变更写一条，用下面的六段式块，按影响面排序往下写，让读者可以提前停下仍已处理最可能影响他们的变更。
13. 工作流第 8 步——以表格发布弃用时间线：现在弃用什么、发出什么警告级别、哪个版本移除；见 references/deprecation-timeline-patterns.md。
14. 工作流第 9 步——记录自动化及其边界：给出确切命令、「全部运行」配方，并明确说明它不覆盖什么；自动化仍需构建时按「为读者节省的小时数 / 工程小时数」排序：搜索模式和字面消息 > N-1 中的弃用警告 > lint 规则 > codemod > 兼容构建；默认发布搜索模式和字面消息（你写每条 affected-if 行时已写好，零额外成本，同时解锁人和编码 agent）；见 references/automated-migration-tooling.md 了解每一级买到什么、饿死什么。
15. 工作流第 10 步——加清理章节：升级成功后告诉读者什么已死——变成默认值的配置项、绕过用的开关和依赖解析覆盖、补丁、框架现在自带的包；没人会自己删这些，它们会成为下次升级的神秘故障。
16. 工作流第 11 步——加按错误文本索引的故障排查章节：读者是把错误粘进搜索框中途进来的，该章节必须匹配他们粘贴的字符串，而不是你对子系统的命名。
17. 工作流第 12 步——用冷启动升级运行按通过阈值验证，修复并重跑直到通过。
18. 工作流第 13 步——埋点并记录：定义采用和分流指标（见 KPI）；若环境有持久记忆，存下版本对、路径形态、弃用窗口和表面矩阵——下次重大版本四项全复用。
19. 每条破坏性变更按固定顺序给六部分：1) 动词前缀标题加稳定锚点（Removed:/Changed:/Renamed:/Deprecated:），锚点是永久标识符，因为 lint 规则、codemod 和支持回复链接到单个变更而非整页；2) affected-if 行——检测信号，给出在代码库中找到它的搜索模式以及读者会看到的确切警告或错误文本；3) 变了什么和为什么，最多三句，为什么赢得配合，第四句就失去它；4) 前后代码，标注 // Before 和 // After，完整到可粘贴；5) 修复方式：codemod 命令或编号手动步骤，绝不同时给命令和含糊的「或手动更新」；6) 逃生舱：恢复旧行为的兼容开关、配置，或明确写「没有」——说没有是信息，沉默不是。
20. 明确谁写以及强制它存在的门禁：做出破坏性变更的工程师拥有技术实质，写手或布道师拥有清晰度、结构和发布；指南在分工中消失是因为各自以为对方在起草；docs-as-code 项目里迁移说明与破坏同 PR 发布，使破坏 API 的人天然成为第一起草人；更强的修复是治理门禁要求文档先于代码落地——Ember 的 RFC 模板要求「How we teach this」章节且 Recommended 阶段要求特性先整合进指南；Rust RFC 1636 照搬该门禁：How We Teach This 要求未满足前不得稳定；Kubernetes KEP 要求 Upgrade/Downgrade Strategy 和 Version Skew Strategy 章节，不完整的 KEP 在增强冻结时从发布中移除；若项目有 RFC、KEP 或设计文档流程，提议加章节而非加指南，它把未来每个破坏自动变成指南；纸面门禁仍需执行——Rust internals 有帖子承认 RFC 1636 的 changelog 部分从未真正落实。
21. 按受众拆分（条目本身相同，三处变化）：开源/自助读者自选升级时机，指南要与「什么都不做」竞争——开头两行写升级买到什么，跑道用发布数而非日期表达，明确说哪个版本仍收安全修复、到何时；失败模式是假设读者已决定升级。商业/合同读者因日期被迫升级——先写截止日期和通知窗口，在指南内而非仅公告邮件里写明支持和升级路径，给回滚流程并说明供应商侧谁执行切换、客户切换前须做什么，给托管或企业部署自己的逃生舱及其结束日期，发布前走支持和法务/传播签核；失败模式是技术完美但无日期无负责人，企业读者无法据此排期。内部/被强制读者更需要归属图而非动机——写明哪个团队拥有每个受影响服务、跟踪 issue、以及旧版本不再可部署的冻结日期；写这类前重读 Churn Rule。
22. 独立版本化的表面：库升级是本地可选，托管 API 升级改变别人正在运行的生产系统行为，指南必须加库指南从不需要的协调——在任何默认值移动前按请求测试新版本的固定机制、跨服务端 SDK/浏览器包/移动 SDK/webhook 载荷的兼容矩阵、标识符或枚举变更的数据层后果、切换与回滚流程；发布必须一起移动的包族时加版本一致性检查：族内每个包同一版本，任何伴随库在其文档化的兼容版本上；半升级的包族产生的错误看起来像你的破坏性变更但不是。迁移任何部分跨越你控制的网络边界时读 references/api-version-migration.md。
23. 机器可读要求（假设编码 agent 不只人类会执行本指南，这个假设零成本且对人类也更好）：错误和警告字符串逐字引用含标点，agent 和搜索框都按字面匹配；给完整可运行片段及其 import，绝不给读者必须自己放对位置的片段；每个版本对保持一个规范 URL 和稳定的逐变更锚点，每次发布都移动的指南会破坏支持曾粘贴过的每个链接；版本门槛写成机器可检查的比较（Node >= 20.19）而非散文（「较新的 Node 版本」）；迁移路径保持在指南内，「上下文见发布博客」可以，「步骤见博客」会让程序化阅读的人搁浅；绝不把移动的补丁版本写进散文，固定指南覆盖的版本对，让 changelog 承载当前发布。
24. 调用示例：从零起草——「我们下月发布 Node 客户端 v3，14 个破坏性变更，还没有 codemod，写迁移指南」→ 跑访谈（问完 1-5 就停），产出：按变更类型分类的清单表、带证据来源的影响面排序、推荐路径形态、库大纲的完整指南草稿；把缺失的 codemod 标为决策而非要掩盖的缺口。审计现有指南——「这是我们 v2→v3 升级页，支持团队一直收到相关工单」→ 按六条通过阈值打分，列出每个缺检测信号或前后代码块的条目，指出排序缺陷，交回带优先级修复清单和前三条重写文本。弃用中途——「我们在 2.4 弃用了四个 API，想在 3.0 移除，现在该发布什么」→ 产出弃用时间线表加面向移除的页面（「3.0 中消失什么」），还不是迁移指南，并说明每项在过渡版本需要什么警告级别。
25. 每次预期输出形态：1) 假设和未决问题（你推断的、只有用户能答的）；2) 清单表：变更 | 类型 | 影响面 | 证据；3) 推荐路径形态，一行给理由；4) 指南本身，用 references/guide-outline-examples.md 的大纲；5) 验证计划：冷启动项目、谁跑、测什么；6) KPI 清单及每个数字的来源。破坏集合大或有争议时，先交 1-3 节供确认再写第 4 节；因排序错误重写十四条比一次往返更贵。
26. 通过阈值——用冷启动升级验证：拿一个真实项目在版本 N（示例应用、内部消费方或社区项目），只用指南升级，由没写指南的人操作键盘；六条全满足才发布（这六条是本技能自己的标准，非行业标准，绝对因为每个失败对作者静默、对读者昂贵）：1) 完整性——tag 间 diff 中每个被移除或行为改变的公共符号都有条目，把指南与 API diff 对照，别信 changelog 当清单；Hyrum's Law 意味着连 diff 都低估，所以加上支持已见到的破坏。2) 可检测性——每条都有搜索模式和确切的错误或警告文本。3) 充分性——升级完成且没有任何指南未描述的编辑；任何未文档化的编辑是缺陷，不是读者失败。4) 自动化诚实——声称的每个 codemod 都在测试项目上跑过，残留物在指南中写明；之后类型检查和测试套件通过。5) 路径有效性——若承诺多跳，至少最老的承诺版本跑过完整路径。6) 自包含——读者无需打开源码、changelog 或 issue tracker 就知道下一步做什么。生态支持可执行文档时把指南命令接入 CI（Rust 的 cargo test --doc 和 mdbook test 是参考实现），让停止编译的片段使构建失败而非悄悄腐烂；测量冷启动耗时并作为预期工作量发布，绝不声称未测量过的时长。完整性在大表面上失败时按模块拆分指南而非删条目，验证同样分片；Google 的 Rosie 平台是工业先例：沿所有权边界分片一个大变更，每片独立测试、评审和提交（《Software Engineering at Google》第 22 章）；部分指南会悄悄教读者指南不可信。
27. KPI 按此顺序埋点（按每接线小时的价值，而非报告顺序）：每千次升级中引用升级错误的工单数及哪个变更产生最多——免费，支持已在收集，该变更的条目就是要重写的；弃用警告遥测在移除版本前趋近零——分阶段路径已要求的管道上一小时聚合，若一个月后仍持平则移除日期错了或指南没触达；codemod 运行率对比手动迁移——工具报告时免费，不报告时不可得；指南行为：页内搜索错误字符串和跳转支持渠道，都是条目缺失或找不到的信号——一小时文档分析；采用曲线：30/60/90 天在 N+1 上的活跃安装或账户占比，对比上一个重大版本的曲线——唯一说明迁移奏效的指标，常设工作，需要跨九十天 join 安装或账户遥测；长尾正常，即使有强平台强制，把最后约 15% 规划为直接对接的具名账户而非文档问题；掉队者：截止后仍在 N 的具名账户或顶级依赖方——支持和成功团队处理的清单，不是百分比。采用曲线和掉队者清单工作量并列且一起买：同一次身份 join 产出两者，曲线是聚合、清单是尾部，join 不存在则两者都不存在。codemod 运行率和指南行为因另一原因并列：各是一小时阅读别人已运行的系统，各回答关于一个产物而非迁移的问题。该顺序饿死采用曲线——页面上价值最高的数字；当移除日期必须向客户或领导层辩护时把它提到最前，并在发布前开始 join：发布后才开始，头九十天已不可测。曲线明显走平后才开始硬执行（brownout、强制移除、关闭企业逃生舱）；此类公开迁移一贯需要数年而非数月才到那一步。
28. 避免常见失败模式：指南只是改了标题的 changelog→把每项重写成读者要做的动作，删掉对他们无改变的内容；按模块或字母排序→按影响面重排，人人撞上的放最前；「相应更新你的用法」无代码→加前后代码块，写不出说明变更没被理解到可发布；读者无法判断是否适用→加 affected-if 行含搜索模式和字面警告文本；弃用未经运行时警告就移除→在过渡版本升级警告级别，太晚就说明并延长旧版本支持；不支持多版本跳跃却未说明→写明支持的跳数，给旧版本的有序路径或引导顺序升级；每次发布原地重写指南→每个版本对一个规范页面，保持在线且锚点稳定；企业读者无日期可排期→发布截止日期、通知窗口和回滚方案；每步都点名供应商工具→描述能力，工具名放一个可单独更新的集成说明；未测量就发布工作量估计→跑冷启动升级并发布那个数字，否则不发布；schema 变更写成带片段的散文→重写为带每步回滚的 runbook；不支持的路径半支持→明确引导那些读者离开（「留在 2.x，原因如下」）而非留在主流程。
29. 参考文件：references/breaking-change-entry-template.md（逐变更块模板和好坏对照）、guide-outline-examples.md（库/SDK 和托管 API 的整页骨架加负面大纲）、deprecation-timeline-patterns.md（警告级别阶梯、发布数窗口和时间线表格式）、automated-migration-tooling.md（codemod 生态、兼容构建和覆盖边界措辞）、api-version-migration.md（托管 API 细节：固定、表面矩阵、webhook、切换和回滚）、guide-types-beyond-libraries.md（schema runbook、云/平台、移动和浏览器 API 迁移）、validation-and-adoption-metrics.md（可执行文档 CI、冷启动走查、codemod 语料测试和采用基准）、sources.md（每条主张背后的公开政策、数字和具名方法）。相关技能：developer-tutorial（读者需学新版本概念而非仅移植代码）、tech-press-relations（带破坏性变更的重大版本媒体处理）、developer-docs-structure-audit（指南在文档站中的位置）、api-versioning-policy（选择版本方案、弃用窗口和日落时间线）。

适用边界 · 注意事项

• 用户要的是逐版本「发布了什么」清单——应转 changelog 技能
• 用户还在决定版本方案、弃用窗口长度或日落政策——本技能只记录已决定的变更
• 用户想在自己代码库中执行升级——那是消费方任务，本技能写的是该任务遵循的文档
• 读者需要学习新版本的概念而非仅移植代码——应转 tutorial 技能
• 用户要按错误文本索引日常故障页——应转 developer-troubleshooting-docs 技能