弃用与迁移：addyosmani/agent-skills: deprecation-and-migration，适用于工程实践、代码质量与开发流程优化。
弃用与迁移：addyosmani/agent-skills: deprecation-and-migration，适用于工程实践、代码质量与开发流程优化。
> 来源: addyosmani/agent-skills — Google Chrome 团队领袖 Addy Osmani
> 原文件: skills/deprecation-and-migration/SKILL.md
> 模型推荐: 看 skill 类型挑
Addy Osmani (Google Chrome 团队 Performance Lead,前端工程领域权威) 整理的 24 个工程方法论 skill 集合 — 覆盖 API 设计 / 浏览器测试 / CI/CD / 代码评审 / TDD / 安全 / 性能 / 部署 等。
michael 强调"skill 要有相应的指导功能,指导用户使用",所以加了下面两节让 Agent 和用户对接。
---
1. 接到任务后,先按这个 skill 的触发关键词跑
2. 跑 Checklist 一遍,标记红线步骤
3. 红线步骤必须先完成(往往是 ask user 确认)
4. 完工前用 verification step 自检
5. 跑完了告诉用户结果,不要自行提交
1. 告诉 Agent 你要做什么(一句话即可)
2. 如果 skill 要求 ask user 凭证 / OAuth / 部署密钥,按提示提供
3. 完工后让 Agent 跑自检再交回
4. 全程 Agent 自动化,你只需回答"是/否"类决策点
---
---
name: deprecation-and-migration
description: Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.
---
Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. 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. This skill addresses that gap.
Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.
When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.
Before deprecating anything, answer these questions:
1. Does this system still provide unique value?
→ If yes, maintain it. If no, proceed.
2. How many users/consumers depend on it?
→ Quantify the migration scope.
3. Does a replacement exist?
→ If no, build the replacement first. Don't deprecate without an alternative.
4. What's the migration cost for each consumer?
→ If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
5. What's the ongoing maintenance cost of NOT deprecating?
→ Security risk, engineer time, opportunity cost of complexity.| Type | When to Use | Mechanism |
|------|-------------|-----------|
| **Advisory** | Migration is optional, old system is stable | Warnings, documentation, nudges. Users migrate on their own timeline. |
| **Compulsory** | Old system has security issues, blocks progress, or maintenance cost is unsustainable | Hard deadline. Old system will be removed by date X. Provide migration tooling. |
**Default to advisory.** Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.
Don't deprecate without a working alternative. The replacement must:
## Deprecation Notice: OldService
**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
NewService handles both automatically.
### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`Migrate consumers one at a time, not all at once. For each consumer:
1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions**The Churn Rule:** If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.
Only after all consumers have migrated:
1. Verify zero active usage (metrics, logs, dependency analysis)
2. Remove the code
3. Remove associated tests, documentation, and configuration
4. Remove the deprecation notices
5. Celebrate — removing code is an achievementRun old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.
Phase 1: New system handles 0%, old handles 100%
Phase 2: New system handles 10% (canary)
Phase 3: New system handles 50%
Phase 4: New system handles 100%, old system idle
Phase 5: Remove old systemCreate an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.
// Adapter: old interface, new implementation
class LegacyTaskService implements OldTaskAPI {
constructor(private newService: NewTaskService) {}
// Old method signature, delegates to new implementation
getTask(id: number): OldTask {
const task = this.newService.findById(String(id));
return this.toOldFormat(task);
}
}Use feature flags to switch consumers from old to new system one at a time:
function getTaskService(userId: string): TaskService {
if (featureFlags.isEnabled('new-task-service', { userId })) {
return new NewTaskService();
}
return new LegacyTaskService();
}A schema change is the riskiest migration because the data is the one thing you cannot roll back by reverting a deploy. The failure mode is coupling the schema change to the code change: rename a column in the same release that starts using the new name, and during the rollout window — when old and new code run at once — one of them is querying a column that doesn't exist. The fix is to **never change a column in place**. Migrate in additive phases so old and new code are both valid at every step.
EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
add the new column, backfill existing rows, once no code reads the
nullable, alongside dual-write old+new from old column, drop it in
the old one the app a later, separate deploy**Worked example — renaming `name` to `full_name`:**
1. **Expand.** Add `full_name` as nullable. Deploy. (Old code ignores it; nothing breaks.)
2. **Dual-write.** App writes both `name` and `full_name` on every insert/update. Deploy.
3. **Backfill.** Copy `name → full_name` for existing rows, in batches, so you don't lock the table.
4. **Switch reads.** Point the app at `full_name`, keep writing both. Deploy and bake.
5. **Contract.** Stop writing `name`, then — in a *separate, later* deploy — drop the column.
Each step is independently deployable and reversible: if step 4 misbehaves, roll the code back and `full_name` is still being populated. Treat each phase as a thin vertical slice — see the `incremental-implementation` skill.
**Rules:**
Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:
**Response:** Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.
| Rationalization | Reality |
|---|---|
| "It still works, why remove it?" | Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently. |
| "Someone might need it later" | If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding. |
| "The migration is too expensive" | Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term. |
| "We'll deprecate it after we finish the new system" | Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now. |
| "Users will migrate on their own" | They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule). |
| "We can maintain both systems indefinitely" | Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost. |
| "Just rename the column, it's one line" | During the rollout, old and new code run together — one will query a column that no longer exists. Expand/contract, never rename in place. |
| "I'll add the column and drop the old one in the same migration" | That couples a safe add to a destructive drop. Drops get their own deploy, after no code references the old shape. |
| "We'll write the rollback if we need it" | A migration with no down path is a deploy you can't reverse. Write and run the `down` before merging. |
After completing a deprecation:
本 skill 专注于弃用与迁移，addyosmani/agent-skills: deprecation-and-migration。它将相关流程标准化，帮助用户更快拿到可靠结果，减少重复手工操作。
当你需要在弃用与迁移相关工作中获得稳定、可复用的产出时最适合——无论是单次任务还是纳入日常工作流，都能直接调用。
需要一个具体的项目或任务上下文，最好带有代码仓库或需求文档。
1. 告诉 Agent 你要做什么(一句话即可)
2. 如果 skill 要求 ask user 凭证 / OAuth / 部署密钥,按提示提供
3. 完工后让 Agent 跑自检再交回
4. 全程 Agent 自动化,你只需回答"是/否"类决策点
---
本 skill 专注于弃用与迁移，addyosmani/agent-skills: deprecation-and-migration。它将相关流程标准化，帮助用户更快拿到可靠结果，减少重复手工操作。
当你需要在弃用与迁移相关工作中获得稳定、可复用的产出时最适合——无论是单次任务还是纳入日常工作流，都能直接调用。
需要一个具体的项目或任务上下文，最好带有代码仓库或需求文档。