📚 工程方法 全难度 📦 Google

deprecation-and-migration

代码即负债、强制/建议弃用、迁移模式、僵尸代码清理。

8 /10 ★★★★☆
📅 2026-06-15 · 🕒 5 分钟阅读 · 最后更新 2026-06-15 · 来源: Google · 分析测评
#Google#deprecation-and-migration
📄 相关文章

📊 评分明细

⚡ 功能完备度
8 核心功能齐全
🎯 易用性
7.7 安装即用
🔧 可扩展性
8.3 支持定制和 fork
🔗 生态协同
7.9 可链式调用
🛡️ 稳定性
8.6 CI 集成验证

🎯 适用场景

Googledeprecation-and-migration

deprecation-and-migration 快速入门

让 AI 像一个严谨的”代码管家”,主动标记废弃代码、规划迁移路径、清理没人用的僵尸文件。

这是什么?解决什么问题?

每个老项目都躲不开三件事:用旧 API 还能用但官方已弃用、新版本出了却没人做迁移、早年的工具函数早没人调用但还堆在仓库里。这些”代码债务”平时不爆,真到上线出问题时排查极其费劲。

deprecation-and-migration 是 Google Chrome 工程总监 Addy Osmani 维护的 agent-skills 仓库下的一个工程方法型 Skill。它的核心思路是:

  1. 代码即负债:在 AI 写代码时就提醒”这里用了 3 年前就被弃用的 API”;
  2. 强制/建议弃用分类:哪些必须立刻换(安全/性能),哪些可以缓一缓(仅命名变更);
  3. 迁移模式模板:重命名/包裹/双写/灰度切换,给出 4 套标准动作;
  4. 僵尸代码清理:基于引用图找出”没人 import、没人 require、没人动态调用”的死代码。

特别适合接手祖传代码、做大版本升级、做依赖换库(如 Vue 2 → Vue 3、Python 2 → 3、axios → fetch)的同学。

准备工作

  • 一个支持 SKILL.md 的 agent 客户端
  • 项目的 Git 仓库(以便做引用图谱)
  • Node.js ≥ 18(若项目是 JS/TS,用以跑引用扫描)
  • 一次”目标版本”明确,比如”我们要把 React 17 升到 React 18”

3 步快速上手

第 1 步:克隆与软链

git clone https://github.com/addyosmani/agent-skills.git
ln -sf "$(pwd)/agent-skills/skills/deprecation-and-migration" \
        ~/.claude/skills/deprecation-and-migration

OpenCode 用户把目标路径换为 ~/.config/opencode/skills/,Cursor 换为 ~/.cursor/skills/。

第 2 步:确认 SKILL.md 已加载

cat ~/.claude/skills/deprecation-and-migration/SKILL.md | head -40

可以看到它定义了”强制弃用清单”(如 componentWillMount、String.prototype.substr 无参用法等)、“迁移模式代号”(RENAME、WRAPPER、DUAL_WRITE、CANARY)等。重启客户端,/skills list 看到 deprecation-and-migration 即 OK。

第 3 步:跑首次扫描

进入项目目录(比如一个老 React 17 项目),在 agent 对话里说:

我要把当前仓库从 React 17 升级到 React 18。
请用 deprecation-and-migration Skill 做一次全仓扫描,
列出强制弃用项、建议弃用项,并给出每个文件的迁移动作(RENAME / WRAPPER / DUAL_WRITE / CANARY)。

AI 会先跑引用扫描(grep、AST),再读 SKILL.md 里的清单,最后输出一张迁移表(文件路径、行号、当前用法、推荐动作、影响面)。你审一遍,挑出第一周要做的部分,继续追问:

请把 src/legacy/Toast.jsx 用 WRAPPER 模式迁移,
保留旧 API 但内部转新实现,产出 diff。

常见踩坑

  1. 没指明目标版本:AI 不知道你要”升 React 18”还是”降到 16”,只能给出通用建议。先把版本号写在 prompt 开头。
  2. 强制/建议不分:让 AI 在产出里显式标红强制项,否则”建议”很容易被团队拖延,最终全部烂尾。
  3. 没留测试就开始迁移:deprecation-and-migration 推荐先跑全量测试,看到绿再动代码,顺序反了排查成本暴涨。
  4. 僵尸代码误判:动态 import、字符串反射、约定式路由里”看似没人引用”其实运行时会用。建议配合一个灰名单(如 import(@/)),告诉 AI 跳过。
  5. 跨仓依赖没扫:只扫了主仓,没扫 SDK/子包,上线时才发现下游也用旧 API。要明确说”扫描 monorepo 全部 package”。
  6. DUAL_WRITE 没设终止日期:双写是过渡手段,不是终点。在 SKILL.md 里加 kill_switch_date,否则双写会变成”长期态”。

初级用法

  • 季度”技术债清扫”:固定一个 sprint 用 Skill 扫一遍,沉淀债务清单到 GitHub Issue。
  • 新员工上手辅助:让新同事 clone 仓库后第一件事就是跑 deprecation-and-migration 扫描,迅速了解项目历史包袱。

高级玩法

  • 接 CI 自动化:在 CI 里跑 Skill 的扫描子集,PR 阶段就阻断新增弃用 API,等于”债务守门员”。
  • 多仓批量扫描:用 shell 循环遍历 20 个仓库,各自生成迁移报告,统一汇总到 Notion,适合中大公司基线治理。
  • 配合 ast-grep/ripgrep:自定义 grep 规则补充 SKILL.md 没列到的企业内部弃用 API,Skill 当总指挥,grep 当士兵。

小技巧

  • 迁移动作表里加一列”测试覆盖”,无测试的强弃用项优先补测试,再换代码。
  • 把”建议弃用”和”强制弃用”分两个 PR,PR 数量可控,review 也更聚焦。
  • 定期 git blame 看弃用代码的提交人,主动沟通,避免”为什么又是我们组的事”。
  • 跨大版本升级时先在 feature 分支做”双写 + 影子调用”两周,稳定后再切主流量。
  • 迁移报告产出后存档,未来回看”我们当时为什么改这个 API”很值钱。

常见问题 FAQ

Q1: 这个 Skill 跟 deprecation-and-migration 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: deprecation-and-migration 来自 Google,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 deprecation-and-migration 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 deprecation-and-migration,建议按以下路径学习:

第 1 周:熟练使用

  • 完成 3 步快速上手,跑通第一个任务
  • 试 2-3 个不同场景的真实任务
  • 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

  • 阅读 Skill 的官方文档(README、SKILL.md)
  • 了解 Skill 的”触发关键词”和”输出格式”
  • 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

  • 跟其他 Skill 组合(比如代码审查 + 性能优化)
  • 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
  • 沉淀团队/个人的 Skill 库

长期:贡献社区

  • 把自定义的 Skill 开源到 GitHub
  • 提 PR 改进现有 Skill
  • 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

避免的坑:

  • 不要装太多 Skill(超过 10 个会拖慢 Agent)
  • 不要把 Skill 装在不兼容的 Agent 上
  • 不要直接复制 Skill 默认 prompt——要根据项目调整
  • 定期 review Skill 库的实用性,清理不用的

参考链接

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。

deprecation-and-migration Skill 多维度简评

类别：工程方法 来源：addyosmani/agent-skills 定位：API 弃用和迁移策略——codemod、双版本期、灰度切换、文档通知。

一、核心定位与价值

deprecation-and-migration 是 addyosmani/agent-skills 项目中的技能之一。该项目由 Addy Osmani 维护，将生产级工程流程编码为 AI 编码代理可遵循的结构化工作流，在 GitHub 上拥有超过 59,000 个 Star。

从 skillsmp.com 对该 Skill 的解析来看，其核心理念是：“Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new. Most engineering organizations are good at building things. Few are good at removing them.”

二、核心能力清单

能力说明
codemod 脚本自动生成代码转换脚本（如 jscodeshift），批量迁移旧 API 调用
双版本共存期规划新旧版本并行运行的时间窗口，确保平滑过渡
@deprecated 标记在代码中标记已弃用的 API，配合文档和编译警告
迁移指南生成自动生成迁移文档，包含步骤说明和代码示例
灰度发布策略制定分阶段推送方案，逐步将用户从旧版迁移至新版

三、工作原理

典型迁移流程

1. 弃用声明 → 在代码中添加 @deprecated 注解，发布版本说明
2. 双版本期 → 新旧 API 同时可用，给下游用户预留迁移时间
3. codemod 辅助 → 提供自动化脚本帮助用户批量替换旧 API
4. 灰度切换 → 逐步将流量从旧版切至新版，监控异常
5. 完全移除 → 在充分通知后移除旧代码

与 agent-skills 生态的关系

该 Skill 属于 agent-skills 项目中”工程化”阶段的技能，与 git-workflow-and-versioning、ci-cd-and-automation 并列。项目使用 7 个斜杠命令（/spec、/plan、/build、/test、/review、/ship）映射完整的开发生命周期。

四、安装与配置

# 方式 1：通过 npx
npx skills add addyosmani/agent-skills --skill deprecation-and-migration

# 方式 2：git clone
git clone https://github.com/addyosmani/agent-skills

五、适用场景

  • 大版本升级：如 React 18 → 19、Angular 版本迁移
  • API 弃用管理：公共库/框架中废弃旧 API
  • 内部工具替换：从旧工具链迁移到新工具链
  • 架构演进：从单体架构逐步迁移到微服务

六、注意事项

  • codemod 脚本不能完全替代人工审查——复杂逻辑迁移仍需人工介入
  • 双版本期需要额外维护成本，应与团队协商合理的共存时间窗口
  • 本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测

参考资料

📦 快速安装

1 Git Clone 
git clone https://github.com/addyosmani/agent-skills.git
ln -sf "$(pwd)/agent-skills/skills/deprecation-and-migration" \
        ~/.claude/skills/deprecation-and-migration