deprecation-and-migration

技能简介

本技能用于管理代码弃用与迁移（Deprecation and Migration）流程。它帮助你在移除旧系统、API 或特性时，制定清晰的迁移路径，同时解决"该维护还是该淘汰"的决策难题。核心思想是：代码是负债而非资产，懂得淘汰与迁移代码，比只会新增功能更重要。

使用场景

• 用新系统、API 或库替换旧版本
• 取消不再需要的功能特性
• 合并多个重复的实现方案
• 移除无人维护但仍有依赖的遗留代码
• 评估旧系统是继续维护还是投入资源进行迁移

使用方法

本技能是一套操作框架，按以下步骤执行：

第一步：判断弃用决策。回答五个关键问题：是否仍有独特价值、有多少用户依赖、是否有替代品、迁移成本多高、不弃用的维护成本有多大。

第二步：构建替代品。弃用前必须有可用的替代方案，并且该方案需经过生产环境验证。

第三步：发布公告并逐步迁移。发布弃用通知，说明替代方案、移除日期和迁移步骤。逐一迁移用户，每迁移一个验证一次。示例公告格式：

## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet

### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Run the migration verification script: `npx migrate-check`

第四步：移除旧系统。确认零活跃使用后，删除代码及相关测试、文档和配置。

注意事项

• 默认采用建议性弃用（Advisory），让用户按自己的节奏迁移；只有在安全风险或维护成本不可持续时才使用强制性弃用（Compulsory）。
• 遵循"Churn Rule"：谁负责弃用基础设施，谁就有责任提供迁移工具或向后兼容的更新，不能只发公告就撒手不管。
• 常见的迁移模式包括：Strangler Pattern（新旧系统并行，逐步切换流量）和 Adapter Pattern（适配器桥接旧接口与新实现）。