deprecation-and-migration
Skill1 starsChanged 10 days agoMITView on GitHub
Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.
63 other projects use a version of this, 50 of them edited.
Adopted by
Most recently taken up by
- JPeetz/agent-skillstheir own version, first seen Nov 15, 2026
- addyosmani/agent-skillsedited, first seen Nov 14, 2026
- ishandutta2007/Awesome-Agent-Skillsedited, first seen Nov 8, 2026
- TheAstroByte/astrobyte-agent-skillsedited, first seen Nov 8, 2026
- MMACABRE/SKILLSedited, first seen Nov 8, 2026
- celestialdust/achilles-skillstheir own version, first seen Nov 1, 2026
Used with
Projects with it also use playwright-cli, brainstorming and 6 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillplaywright-cli
Automate browser interactions, test web pages and work with Playwright tests.
Also in 3 projects that use this
OpenAISkillbrainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Also in 4 projects that use this
OpenAISkillverification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
Also in 3 projects that use this
MicrosoftSkillcaveman
Ultra-compressed response style that reduces output token count while preserving technical accuracy, with intensity levels and auto-clarity safety rules
Also in 3 projects that use this
VercelSkillvercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
Also in 3 projects that use this
GoogleSkillimprove-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Also in 3 projects that use this
- +1 more from microsoft
Other versions63 projects use a version of this.
Word for word · 0
None found.
Edited · 50
- addyosmani/agent-skills★ 118k22% same
- shashankswe2020-ux/whoop-mcp★ 18125% same
- vinvcn/addyosmani-agent-skills-zh★ 4697% same
- sampleXbro/agentsmesh★ 2725% same
- jaskirat1616/grok-skills★ 2219% same
- ishandutta2007/Awesome-Agent-Skills★ 2125% same
- HK-hub/AgentSkills★ 619% same
- lza6/claw-code-tingfeng★ 525% same
- ddddjaak/ae-skills★ 425% same
- dzevs/zynk★ 410% same
40 more not listed
Wrote their own version · 13
- drvoss/everything-copilot-cli★ 49same name
- jmxt3/gitscape.ai★ 33same name
- JPeetz/agent-skills★ 17same name
- codexskills/agent-forge★ 2same name
- GuillemRoca/agent-skills-android★ 2same name
- jacksonwilliamsva/kiro-skills-library★ 2same name
- NashEQify/forge★ 2same name
- Aleksandr-Litvinenko/agent-skills-ru★ 1same name
- celestialdust/achilles-skills★ 1same name
- Hello-Lain/skills★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/beads.mdcCursor rule
- beadsSkill
- api-and-interface-designSkill
- browser-testing-with-devtoolsSkill
- ci-cd-and-automationSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- constraint-driven-developmentSkill
- context-engineeringSkill
- debugging-and-error-recoverySkill
- documentation-and-adrsSkill
- doubt-driven-developmentSkill
- frontend-ui-engineeringSkill
- git-workflow-and-versioningSkill
- idea-refineSkill
- incremental-implementationSkill
- interview-meSkill
- observability-and-instrumentationSkill
- performance-optimizationSkill
- planning-and-task-breakdownSkill
- security-and-hardeningSkill
- shipping-and-launchSkill
- source-driven-developmentSkill
- spec-driven-developmentSkill
- test-driven-developmentSkill
- using-agent-skillsSkill
The file
Files
Deprecation and Migration
概览
代码是一种负债,而不是资产。每一行代码都有持续维护成本:需要修复 bug、更新依赖、应用安全补丁,并帮助新工程师理解它。弃用是一套移除不再值得维护的代码的纪律,迁移则是将用户安全地从旧系统转移到新系统的过程。
大多数工程组织都擅长构建东西,但很少擅长移除它们。这个 skill 就是为了弥补这个缺口。
何时使用
- 用新系统、API 或库替换旧系统、API 或库
- 下线不再需要的功能
- 合并重复实现
- 移除无人拥有但人人依赖的死代码
- 规划新系统的生命周期(弃用规划从设计阶段就开始)
- 判断是继续维护遗留系统,还是投入迁移
核心原则
代码是一种负债
每一行代码都有持续成本:它需要测试、文档、安全补丁、依赖更新,也会给附近工作的任何人带来理解成本。代码的价值在于它提供的功能,而不是代码本身。当同样的功能可以用更少的代码、更低的复杂度或更好的抽象来提供时,旧代码就应该离开。
Hyrum 定律让移除变得困难
只要用户足够多,每一种可观察行为都会被依赖,包括 bug、时序怪癖和未记录的副作用。这就是为什么弃用需要主动迁移,而不只是发公告。当用户依赖了替代方案没有复现的行为时,他们不能“直接切换”。
弃用规划从设计阶段开始
构建新东西时,要问:“三年后我们要如何移除它?”带有清晰接口、功能开关和最小表面积的系统,比到处泄漏实现细节的系统更容易弃用。
弃用决策
弃用任何东西之前,先回答这些问题:
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.强制弃用与建议弃用
| 类型 | 何时使用 | 机制 |
| Advisory | 迁移是可选的,旧系统稳定 | 警告、文档、提示。用户按自己的节奏迁移。 |
| Compulsory | 旧系统有安全问题、阻碍进展,或维护成本不可持续 | 明确截止日期。旧系统将在日期 X 被移除。提供迁移工具。 |
默认使用建议弃用。 只有当维护成本或风险足以证明强制迁移合理时,才使用强制弃用。强制弃用要求提供迁移工具、文档和支持,不能只是宣布一个截止日期。
迁移流程
步骤 1: 构建替代方案
没有可用替代方案时不要弃用。替代方案必须:
- 覆盖旧系统的所有关键用例
- 具备文档和迁移指南
- 在生产环境中被证明可行,而不只是“理论上更好”
步骤 2: 公告并记录
## 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`步骤 3: 增量迁移
一次迁移一个消费者,不要一次性全部迁移。对每个消费者:
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 regressionsThe Churn Rule: 如果你拥有正在弃用的基础设施,你就负责迁移你的用户,或者提供不需要迁移的向后兼容更新。不要宣布弃用后让用户自己摸索。
步骤 4: 移除旧系统
只有在所有消费者都完成迁移之后:
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 achievement迁移模式
Strangler Pattern(绞杀者模式)
并行运行新旧系统。将流量从旧系统逐步切到新系统。当旧系统承载 0% 流量时,移除它。
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 systemAdapter Pattern(适配器模式)
创建一个适配器,把旧接口调用转换到新实现。在迁移后端期间,消费者仍然使用旧接口。
// 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);
}
// Translate the new shape back into what old consumers expect
private toOldFormat(task: Task): OldTask {
return { id: Number(task.id), title: task.title, done: task.status === 'done' };
}
}Feature Flag Migration(功能开关迁移)
使用 feature flags 逐个将消费者从旧系统切换到新系统:
function getTaskService(userId: string): TaskService {
if (featureFlags.isEnabled('new-task-service', { userId })) {
return new NewTaskService();
}
return new OldTaskService();
}数据库 Schema 迁移(Expand/Contract)
Schema 变更是风险最高的迁移,因为数据是唯一一个无法靠回滚部署来恢复的东西。它的失败模式是把 schema 变更和代码变更耦合在一起:如果在开始使用新列名的同一个 release 里重命名列,那么在 rollout 窗口期内(新旧代码同时运行时),必然有一方在查询一个不存在的列。解法是永远不要原地修改列。按 additive 阶段迁移,让新旧代码在每一步都对 schema 有效。
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完整示例——把 name 重命名为 full_name:
- Expand。 以 nullable 方式添加
full_name列。部署。(旧代码忽略它,什么都不破坏。) - Dual-write(双写)。 应用在每次 insert/update 时同时写入
name和full_name。部署。 - Backfill(回填)。 分批把已有行的
name → full_name复制过去,避免锁表。 - Switch reads(切换读取)。 让应用改读
full_name,同时保持双写。部署并观察一段时间。 - Contract(收缩)。 停止写入
name,然后——在一个独立的、更晚的部署里——删除该列。
每一步都可独立部署、独立回滚:如果第 4 步出问题,回滚代码即可,full_name 仍在被填充。把每个阶段当作一条薄的垂直切片——参见 incremental-implementation skill。
规则:
- 先做 additive,destructive 最后且单独做。 新增(new nullable column、新表、新索引)在任何部署中都是安全的;drop 和 rename 要在没有任何代码引用旧结构之后,拥有自己的独立部署。
- 每个迁移都要有经过测试的 down path(回滚路径)。 一个无法逆转的迁移,就是一个无法回滚的部署。合并之前先写好并运行
down。 - Backfill 要分批、避开热路径。 对上百万行执行单条
UPDATE会锁表;分块并限流。 - 构建大索引时不要阻塞写入(例如 Postgres 的
CREATE INDEX CONCURRENTLY)。 - 当 cutover 风险高时,用 feature flag 与代码解耦,与上面 Feature Flag Migration 模式的做法完全一致。
Zombie Code(僵尸代码)
Zombie code 指无人拥有但人人依赖的代码。它没有被主动维护,没有明确 owner,并会累积安全漏洞和兼容性问题。迹象包括:
- 6 个月以上没有 commit,但仍有活跃消费者
- 没有指定维护者或团队
- 有失败测试但没人修复
- 依赖存在已知漏洞但没人更新
- 文档引用了已经不存在的系统
应对方式: 要么指定 owner 并妥善维护,要么用具体迁移计划弃用它。Zombie code 不能一直悬而未决,它要么获得投入,要么被移除。
常见合理化借口
| 合理化借口 | 现实 |
| “它还能用,为什么要移除?” | 无人维护的可用代码会累积安全债和复杂度。维护成本会悄悄增长。 |
| “以后可能有人会需要它” | 如果以后需要,可以重建。为了“以防万一”保留未使用代码,成本通常高于重建。 |
| “迁移太贵了” | 把迁移成本和未来 2-3 年的持续维护成本比较。长期看,迁移通常更便宜。 |
| “等新系统完成后再弃用它” | 弃用规划从设计阶段开始。等新系统完成时,你会有新的优先级。现在就规划。 |
| “用户会自己迁移” | 他们不会。提供工具、文档和激励,或者自己完成迁移(The Churn Rule)。 |
| “我们可以无限期维护两个系统” | 两个系统做同一件事,意味着维护、测试、文档和 onboarding 成本都翻倍。 |
| “只是重命名一列,就一行代码” | Rollout 期间新旧代码同时运行,必有一方在查询一个已不存在的列。Expand/contract,永远不要原地重命名。 |
| “我在同一个迁移里加新列并删掉旧列” | 这会把一个安全的 add 和一个 destructive 的 drop 耦合在一起。Drop 要有自己的独立部署,且发生在没有代码引用旧结构之后。 |
| “等需要时再写回滚” | 没有 down path 的迁移,就是一个无法逆转的部署。合并之前先写好并运行 down。 |
危险信号
- 已弃用系统没有可用替代方案
- 弃用公告没有迁移工具或文档
- “软性”弃用多年仍停留在建议阶段且没有进展
- Zombie code 没有 owner 但仍有活跃消费者
- 给已弃用系统添加新功能(应该投入替代方案)
- 未衡量当前使用情况就弃用
- 未验证没有活跃消费者就移除代码
- Schema 变更与依赖它的代码在同一个部署中发布
- 列被原地重命名或删除,而不是走 expand/contract
- 迁移已合并却没有经过测试的 down path,或 backfill 锁住了表
验证
完成一次弃用后:
- 替代方案已在生产环境中证明可行,并覆盖所有关键用例
- 迁移指南存在,且包含具体步骤和示例
- 所有活跃消费者都已迁移(通过指标/日志验证)
- 旧代码、测试、文档和配置已完全移除
- 代码库中不再引用已弃用系统
- 弃用通知已移除(它们已经完成使命)
完成一次数据库 schema 迁移后:
- 变更按 additive 阶段发布(expand → backfill → contract),而不是一次原地修改
- 在每一个部署步骤中,新旧代码对 schema 都有效
- 每个迁移都有经过测试的 down path;backfill 以限流批次运行
- Destructive 步骤(drop/rename)在没有代码引用旧结构之后,拥有自己的独立部署
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

