deprecation-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<br>
ln -sf "$(pwd)/agent-skills/skills/deprecation-and-migration" \<br>
~/.claude/skills/deprecation-and-migration<br>
```<br>
OpenCode 用户把目标路径换为 `~/.config/opencode/skills/`,Cursor 换为 `~/.cursor/skills/`。<br>
### 第 2 步:确认 SKILL.md 已加载<br>
```bash<br>
cat ~/.claude/skills/deprecation-and-migration/SKILL.md | head -40<br>
```<br>
可以看到它定义了"强制弃用清单"(如 `componentWillMount`、`String.prototype.substr` 无参用法等)、"迁移模式代号"(`RENAME`、`WRAPPER`、`DUAL_WRITE`、`CANARY`)等。重启客户端,`/skills list` 看到 `deprecation-and-migration` 即 OK。<br>
### 第 3 步:跑首次扫描<br>
进入项目目录(比如一个老 React 17 项目),在 agent 对话里说:<br>
```<br>
我要把当前仓库从 React 17 升级到 React 18。<br>
请用 deprecation-and-migration Skill 做一次全仓扫描,<br>
列出强制弃用项、建议弃用项,并给出每个文件的迁移动作(RENAME / WRAPPER / DUAL_WRITE / CANARY)。<br>
```<br>
AI 会先跑引用扫描(grep、AST),再读 SKILL.md 里的清单,最后输出一张迁移表(文件路径、行号、当前用法、推荐动作、影响面)。你审一遍,挑出第一周要做的部分,继续追问:<br>
```<br>
请把 src/legacy/Toast.jsx 用 WRAPPER 模式迁移,<br>
保留旧 API 但内部转新实现,产出 diff。<br>
```<br>
## 常见踩坑<br>
1. **没指明目标版本**:AI 不知道你要"升 React 18"还是"降到 16",只能给出通用建议。先把版本号写在 prompt 开头。<br>
2. **强制/建议不分**:让 AI 在产出里**显式标红**强制项,否则"建议"很容易被团队拖延,最终全部烂尾。<br>
3. **没留测试就开始迁移**:deprecation-and-migration 推荐先跑全量测试,看到绿再动代码,顺序反了排查成本暴涨。<br>
4. **僵尸代码误判**:动态 import、字符串反射、约定式路由里"看似没人引用"其实运行时会用。建议配合一个灰名单(如 `import(`@/`)`),告诉 AI 跳过。<br>
5. **跨仓依赖没扫**:只扫了主仓,没扫 SDK/子包,上线时才发现下游也用旧 API。要明确说"扫描 monorepo 全部 package"。<br>
6. **DUAL_WRITE 没设终止日期**:双写是过渡手段,不是终点。在 SKILL.md 里加 `kill_switch_date`,否则双写会变成"长期态"。<br>
## 初级用法<br>
- **季度"技术债清扫"**:固定一个 sprint 用 Skill 扫一遍,沉淀债务清单到 GitHub Issue。<br>
- **新员工上手辅助**:让新同事 clone 仓库后第一件事就是跑 `deprecation-and-migration` 扫描,迅速了解项目历史包袱。<br>
## 高级玩法<br>
- **接 CI 自动化**:在 CI 里跑 Skill 的扫描子集,PR 阶段就阻断新增弃用 API,等于"债务守门员"。<br>
- **多仓批量扫描**:用 shell 循环遍历 20 个仓库,各自生成迁移报告,统一汇总到 Notion,适合中大公司基线治理。<br>
- **配合 ast-grep/ripgrep**:自定义 grep 规则补充 SKILL.md 没列到的企业内部弃用 API,Skill 当总指挥,grep 当士兵。<br>
## 小技巧<br>
- 迁移动作表里加一列"测试覆盖",无测试的强弃用项优先补测试,再换代码。<br>
- 把"建议弃用"和"强制弃用"分两个 PR,PR 数量可控,review 也更聚焦。<br>
- 定期 `git blame` 看弃用代码的提交人,主动沟通,避免"为什么又是我们组的事"。<br>
- 跨大版本升级时先在 feature 分支做"双写 + 影子调用"两周,稳定后再切主流量。<br>
- 迁移报告产出后存档,未来回看"我们当时为什么改这个 API"很值钱。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 deprecation-and-migration 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: deprecation-and-migration 来自 Google,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

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

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

**Q5: 这个 Skill 有许可证吗?能商用吗?**<br>
## 参考链接
- [仓库主页](https://github.com/addyosmani/agent-skills)<br>
- [deprecation-and-migration 目录](https://github.com/addyosmani/agent-skills/tree/main/skills/deprecation-and-migration)<br>
- [ast-grep](https://ast-grep.github.io/)<br>
- [ripgrep](https://github.com/BurntSushi/ripgrep)<br>
- [Addy Osmani 个人站](https://addyosmani.com/)<br>
- 相关 Skill:strategic-compact、tdd