메뉴
弃用与迁移——管理代码生命周期。当需要移除、替换或迁移已有功能/API，或提到"弃用""迁移""deprecation""breaking change"
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/ZeroZ-lab/unified-skills --skill maintain-team-deprecation-migration명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | maintain-team-deprecation-migration |
| description | 弃用与迁移——管理代码生命周期。当需要移除、替换或迁移已有功能/API，或提到"弃用""迁移""deprecation""breaking change" |
代码是负债，不是资产。 未使用的代码仍然需要维护、编译、测试、理解。每行代码都有持续成本。删除代码是改善。
有足够用户时，每个可观察到的行为都有人依赖。 即使是未文档化的实现细节、错误消息文本、响应字段排序——某处可能有消费者依赖它。
设计 API 时就为未来弃用规划——使用 Feature Flag 或版本化参数，使旧行为可逐步下线。
在宣布弃用之前回答：
| 类型 | 机制 | 适用 |
|---|---|---|
| 强制弃用 | 弃用日期后功能移除。消费者必须迁移。 | 安全修复、无法维护的旧系统 |
| 必须弃用 | 功能可用但文档化和告警说明即将移除。消费者有时间迁移。 | 改进但不紧急 |
"必须弃用"不是永久的。 如果消费者不迁移，"建议"变为"强制"带日期。
新系统逐步接管旧系统功能:
Phase 1: 新系统 + 旧系统并存（新代码走新路径）
Phase 2: 逐渐迁移旧路径到新系统
Phase 3: 旧系统仅剩 5% 流量
Phase 4: 旧系统完全关闭
不一次性替换。一条条路由/功能逐步迁移。
// 消费者调用 v2 API → v2 handler（当前版本）
// 旧消费者仍调用 v1 API → v1 adapter → 转换请求 → 委托给 v2 handler
// 所有 v1 消费者迁移后 → 删除 v1 adapter
async function v1CreateTaskHandler(req: V1Request): Promise<V1Response> {
const v2Request = toV2Request(req); // v1 → v2 转换
const v2Response = await v2Handler(v2Request);
return toV1Response(v2Response); // v2 → v1 转换
}
// Flag 控制新旧代码路径
if (await featureFlag.isEnabled('use-new-task-service', userId)) {
return newTaskService.create(req); // 新路径
} else {
return oldTaskService.create(req); // 旧路径（逐步关闭 flag）
}
需要弃用？
├── 突发弃用（安全漏洞、合规要求）
│ └── 立即下线 + 紧急通知消费者
└── 渐进弃用
├── 多个消费者？
│ ├── YES → Strangler Pattern（逐个迁移）
│ └── NO → Adapter 或直接替换
├── 需要兼容期？
│ ├── YES → Feature Flag 控制新旧路径
│ └── NO → 直接替换 + 版本号大版本升级
└── 通知 → 设置过期 → 监控使用 → 移除旧代码
| 反模式 | 问题 | 修复 |
|---|---|---|
只在注释里写 @deprecated | 没人看注释，消费者无感知 | 加上 console.warn / 运行时警告 + 使用量监控 |
| 没有度量就删除代码 | 可能还有人在用，删除即事故 | 先加埋点追踪使用量，确认为零后再删 |
| 新代码还在依赖废弃 API | 弃用形同虚设，永远无法清理 | CI 规则禁止新代码引入废弃 API import |
| 没有通知消费者就下线 | 消费者突然崩溃，生产事故 | 最少 2 个版本的弃用公告期 |
| 迁移中途停止（旧新并存） | 两套系统永久并存，复杂度翻倍 | 设死线，到期未迁的由平台强制切换 |
| 废弃了但忘了清理 | 僵尸代码堆积，拖累系统 | 每个废弃有 owner + 过期日期，过期后自动创建清理 PR |
| 替代方案质量低于旧方案 | 消费者拒绝迁移，两套永久并存 | 替代至少和旧方案一样好。不够好就不废弃。 |
| 弃用公告没有迁移指南 | 消费者不知道怎么改，只能拖着 | 每条弃用公告附带迁移示例和文档链接 |
// Bad: 仅注释——无人感知
// @deprecated use newUserService instead
export const oldGetUser = ...
// Good: 运行时警告 + 迁移指引 + 截止日期
export const oldGetUser = (id: string) => {
console.warn(
'[DEPRECATED] oldGetUser will be removed in v3.0 (2026-06-01). ' +
'Migrate to: userService.getUser(id) — see docs/migration/v2-to-v3.md'
);
trackDeprecatedUsage('oldGetUser');
return userService.getUser(id);
};
好弃用公告三要素：
代码是僵尸代码当它：
僵尸代码必须消灭。 标注 owner、迁移消费者、设定关闭日期。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "先留着吧，以后可能有用" | 留着 = 维护+测试+编译+理解成本。YAGNI（你不会需要它）。 | 僵尸代码堆积，每行年维护成本 ≥ 1h，团队理解成本随代码量线性增长 |
| "没人用的代码不用管" | 你怎么知道没人用？在关闭前加日志/指标验证。 | 未验证删除导致生产事故，修复时间 ≥ 2h + 影响所有未知消费者 |
| "直接删就行" | Hyrum 法则。某处有东西依赖它。总是用弃用→兼容→清理的三步过程。 | 跳过弃用流程直接删除，依赖方突然崩溃，紧急回滚 ≥ hotfix + 全量回归测试 |
| "必须弃用就够，消费者会自己迁移" | 很少消费者主动迁移。需要明确关闭日期 + 多次通信 + 迁移支持。 | 消费者不迁移导致双系统永久并存，维护成本翻倍 ≥ 2x |
| "没人用那个 API" | 你确定？查监控数据，不猜。 | 猜测代替数据导致误删，生产故障影响 ≥ 所有依赖该 API 的服务 |
| "新 API 还没准备好，先保留旧的" | 那不叫废弃，叫双写。设时间线。 | 无时间线的双写永远并存，技术债务累积 ≥ N 个未关闭的弃用项 |
| "文档更新等删代码时一起做" | 文档先行。消费者需要迁移指南才能迁移。 | 无迁移指南消费者无法行动，弃用周期延长 ≥ 2-3 个版本 |
| "废弃太麻烦了，直接改" | Breaking change 不走废弃流程 = 生产事故。 | 未走流程的 breaking change 导致下游团队生产故障，影响 ≥ M 个消费方 |
| "这个 API 只有我们内部用" | 内部团队也是消费者。内部依赖断裂同样导致生产故障。 | 内部依赖断裂影响 ≥ N 个内部服务，排查时间 ≥ 跨团队协调 1 周 |
| "消费者还没迁移，再延长一下" | 延期一次可以，延期两次说明你的迁移支持不够。主动提供协助。 | 反复延期导致弃用信誉下降，后续弃用更难推进，周期 ≥ 延期 N 次 |
| 失败场景 | 处理方式 |
|---|---|
| 消费者拒绝迁移 | 评估影响范围。如影响小可强制下线；如影响大需升级到管理层决策。 |
| 迁移引入新 bug | 回滚到旧路径，调查根因，修复后重新迁移。不要在旧路径有 bug 时继续。 |
| 回滚失败（旧代码已删除） | 从 git 历史恢复旧代码作为 hotfix，重新评估迁移策略。保留旧代码直到确认新路径稳定。 |
| 替代方案本身也需要废弃 | 质疑架构方向。暂停迁移，重新评估替代方案。废弃链说明设计有问题。 |
| 依赖链式废弃（A→B→C） | 从叶子节点开始逐个迁移，不要并行。画出依赖图，按拓扑排序执行。 |
| 使用量降为零但仍有调用报错 | 检查监控覆盖是否完整。可能有未接入监控的调用方。加全链路追踪确认。 |
以下话语出现时，说明你的弃用流程有缺口：
全部意味着：STOP。回到弃用决策，补齐缺失环节。
弃用与迁移完成后应产出以下结构（记录于 ADR 或项目文档中）：
### Deprecation & Migration 记录
**弃用目标**: [API / 功能 / 模块名]
**替代方案**: [新 API / 新功能名 + 迁移路径]
**弃用类型**: [强制 / 必须]
**截止日期**: [YYYY-MM-DD]
**消费者影响评估**:
| 消费者 | 当前调用量 | 迁移状态 | 迁移支持 |
|--------|-----------|----------|----------|
| [团队/服务1] | [N 次/天] | [已迁移 / 未迁移 / 迁移中] | [迁移指南 / 工具 / 无] |
**迁移时间线**:
- Phase 1: [YYYY-MM-DD] — 新旧并存，运行时警告上线
- Phase 2: [YYYY-MM-DD] — 使用量监控确认下降
- Phase 3: [YYYY-MM-DD] — 旧代码关闭/删除
**回退计划**: [hotfix 路径 / feature flag 回退 / git revert 策略]
**已知限制**: [兼容层行为差异 / 监控覆盖缺口 / 未迁移消费者]