Entry/Exit
- Entry: Need to remove or replace existing features, API version upgrades, clean up deprecated code
- Exit: Migration plan + compatibility layer (if needed) + documentation + cleanup
- Points to: Return to the normal build process after migration is complete
- Preload: CANON.md
- Output path: verify-workflow-review
When not to use
- Only adding new features, not removing, replacing, or changing existing behavior
- The deprecation scope has no usage data, compatibility requirements, or migration window
- Only deleting temporary code newly created in this task that has not yet been released
Core principles
Code Is a Liability
Code is a liability, not an asset. Unused code still needs to be maintained, compiled, tested, and understood. Every line of code has an ongoing cost. Deleting code is an improvement.
Hyrum's Law makes deletion difficult
With enough users, every observable behavior is depended on by someone. Even undocumented implementation details, error message text, response field ordering—someone somewhere may have a consumer relying on them.
Deprecation planning starts at design time
Plan for future deprecation when designing APIs—use feature flags or versioned parameters so old behavior can be gradually phased out.
Deprecation decision
Before announcing deprecation, answer:
- Is there a replacement? Where do users migrate to? The replacement should be at least as good as the old solution.
- How many users are there? How many people depend on this API/feature? What is the actual usage?
- Is the migration cost covered? Who is responsible for the migration—the provider or the consumer? Do migration tools and documentation exist?
- Is the timeline reasonable? If the consumer team needs 6 months, don't give them 2 weeks.
- Is an emergency rollback possible? If the migration goes wrong, can the deprecated feature be restored immediately?
Forced vs. Mandatory Deprecation
| Type | Mechanism | Applicable |
|---|---|---|
| Forced deprecation | Feature removed after the deprecation date. Consumers must migrate. | Security fixes, legacy systems that cannot be maintained |
| Mandatory deprecation | Feature is available but documentation and warnings state it will be removed soon. Consumers have time to migrate. | Improvements but not urgent |
"Mandatory deprecation" is not permanent. If consumers do not migrate, "recommended" becomes "forced" with a date.
Migration patterns
Strangler Pattern (safest)
新系统逐步接管旧系统功能:
Phase 1: 新系统 + 旧系统并存(新代码走新路径)
Phase 2: 逐渐迁移旧路径到新系统
Phase 3: 旧系统仅剩 5% 流量
Phase 4: 旧系统完全关闭
不一次性替换。一条条路由/功能逐步迁移。
Adapter Pattern
// 消费者调用 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 转换
}
Feature Flag migration
// Flag 控制新旧代码路径
if (await featureFlag.isEnabled('use-new-task-service', userId)) {
return newTaskService.create(req); // 新路径
} else {
return oldTaskService.create(req); // 旧路径(逐步关闭 flag)
}
Migration decision flowchart
需要弃用?
├── 突发弃用(安全漏洞、合规要求)
│ └── 立即下线 + 紧急通知消费者
└── 渐进弃用
├── 多个消费者?
│ ├── YES → Strangler Pattern(逐个迁移)
│ └── NO → Adapter 或直接替换
├── 需要兼容期?
│ ├── YES → Feature Flag 控制新旧路径
│ └── NO → 直接替换 + 版本号大版本升级
└── 通知 → 设置过期 → 监控使用 → 移除旧代码
Anti-pattern fix table
| Anti-pattern | Problem | Fix |
|---|---|---|
Only write in comments @deprecated |
No one reads comments, consumers are unaware | Add console.warn / runtime warnings + usage monitoring |
| Deleting code without measuring | Someone may still be using it; deleting it would cause an incident | First add instrumentation to track usage, and delete only after confirming it is zero |
| New code still depends on the deprecated API | Deprecation is nominal and can never be cleaned up | CI rules prohibit new code from introducing deprecated API imports |
| Taking it offline without notifying consumers | Consumers suddenly crash, causing a production incident | A deprecation notice period of at least 2 versions |
| Migration stops midway (old and new coexist) | The two systems coexist permanently, doubling complexity | Set a hard deadline; if migration is not completed by then, the platform forces the switch |
| Deprecated but forgotten to clean up | Zombie code accumulates and drags down the system | Each deprecation has an owner + expiration date; after expiration, a cleanup PR is automatically created |
| The replacement is lower quality than the old solution | Consumers refuse to migrate, and the two systems coexist permanently | The replacement must be at least as good as the old solution. If it is not good enough, do not deprecate. |
| The deprecation notice has no migration guide | Consumers do not know how to change and can only delay | Each deprecation notice includes migration examples and documentation links |
Good/Bad Deprecation Notice Comparison
// 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);
};
Three elements of a good deprecation notice:
- Runtime warning — remind consumers on every call, not a silent comment
- Migration guidance — clearly tell consumers what to use instead, how to change, and where the docs are
- Deadline — give a specific removal time, not "someday in the future"
Zombie Code Definition
Code is zombie code when it:
- No one maintains it, but it is still running
- Has active consumers, but the owner has left/transferred teams
- Lacks documentation, but someone depends on its behavior
- Is technically deprecated, but the shutdown date is postponed indefinitely
Zombie code must be eliminated. Mark the owner, migrate consumers, and set a shutdown date.
Common Excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "Keep it for now, it might be useful later" | Keeping it = maintenance + testing + compilation + comprehension cost. YAGNI (You Aren't Gonna Need It). | Zombie code accumulates; each line costs at least 1h of maintenance per year, and team comprehension cost grows linearly with the amount of code |
| "Code no one uses doesn't need to be managed" | How do you know no one uses it? Add logs/metrics to verify before shutting it down. | Unverified deletion causes a production incident; repair time ≥ 2h + affects all unknown consumers |
| "Just delete it" | Hyrum's Law. Something somewhere depends on it. Always use the three-step process of deprecate → compatible → clean up. | Skipping the deprecation process and deleting directly causes dependents to suddenly crash; emergency rollback ≥ hotfix + full regression testing |
| "Deprecating is enough; consumers will migrate themselves" | Few consumers migrate proactively. You need a clear shutdown date + multiple communications + migration support. | Consumers not migrating causes dual systems to coexist permanently, doubling maintenance cost ≥ 2x |
| "No one uses that API" | Are you sure? Check monitoring data, don't guess. | Guessing instead of using data leads to mistaken deletion, and production incidents affect ≥ all services depending on that API |
| "The new API isn't ready yet, keep the old one for now" | That's not deprecation, that's dual-writing. Set a timeline. | Dual-writing without a timeline will coexist forever, and technical debt will accumulate ≥ N unclosed deprecation items |
| "Documentation updates can be done together when the code is deleted" | Documentation first. Consumers need a migration guide in order to migrate. | Without a migration guide, consumers cannot act, and the deprecation cycle is extended by ≥ 2-3 versions |
| "Deprecation is too troublesome, just change it directly" | A breaking change that does not go through the deprecation process = a production incident. | A breaking change that skips the process causes production incidents for downstream teams, affecting ≥ M consumers |
| "This API is only used internally by us" | Internal teams are consumers too. A broken internal dependency likewise causes production incidents. | A broken internal dependency affects ≥ N internal services, with investigation time ≥ 1 week of cross-team coordination |
| "Consumers haven't migrated yet, extend it a bit more" | One extension is fine, but two extensions mean your migration support is insufficient. Proactively offer assistance. | Repeated extensions reduce deprecation credibility, making subsequent deprecations harder to push forward, with a cycle ≥ N extensions |
Red flags — STOP
- The deprecation announcement does not specify a replacement
- The deprecation timeline gives consumers an unreasonably short time (< 1 iteration)
- Deprecated functionality continues to be called by new functionality ("deprecate it first, then we'll use it ourselves too")
- Comments-only deprecation ("// deprecated" but no logs, no alerts, no documentation)
- Old code is deleted directly — without any compatibility period
Handling validation failures
| Failure scenario | How to handle it |
|---|---|
| Consumers refuse to migrate | Assess the scope of impact. If the impact is small, it can be forcibly taken offline; if the impact is large, it must be escalated to management for a decision. |
| Migration introduces new bugs | Roll back to the old path, investigate the root cause, and migrate again after fixing. Do not continue while the old path has bugs. |
| Rollback fails (old code has already been deleted) | Restore the old code from git history as a hotfix, and re-evaluate the migration strategy. Keep the old code until the new path is confirmed stable. |
| The replacement itself also needs to be deprecated | Question the architectural direction. Pause the migration and re-evaluate the replacement. A deprecation chain indicates a design problem. |
| Chained dependency deprecation (A→B→C) | Migrate one by one starting from the leaf nodes; do not do it in parallel. Draw the dependency graph and execute in topological order. |
| Usage drops to zero but there are still call errors | Check whether monitoring coverage is complete. There may be callers not connected to monitoring. Add full-link tracing to confirm. |
Human partner signals
When the following phrases appear, it means your deprecation process has gaps:
- "When will this API be taken offline?" — You didn't set an expiration date. Every deprecation announcement must have a clear deadline.
- "Who else is using this?" — You didn't track usage. Monitoring must be added before deprecation; decisions must be data-driven.
- "Where is the migration guide?" — You didn't write the migration documentation. Documentation comes first; consumers need a guide before they can act.
- "Can we have a few more days?" — Your timeline is too tight. Reassess the consumer migration pace and adjust the deadline.
- "I used the new API but the behavior is different" — Your replacement does not fully cover the old API's behavior. Add test cases to align them.
- "Why is production still calling the old interface?" — Your monitoring doesn't cover all consumers, or the deprecation notice didn't reach them. Add runtime warnings.
All of this means: STOP. Go back to the deprecation decision and fill in the missing pieces.
Output Template
After deprecation and migration are complete, the following structure should be produced (recorded in an ADR or project documentation):
### 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 策略]
**已知限制**: [兼容层行为差异 / 监控覆盖缺口 / 未迁移消费者]
Verification Checklist
- The replacement is clear and available (consumers migrate to it)
- The deprecation timeline is reasonable (consumer migration pace was followed)
- Actual usage has been verified (logs/metrics—not just guesses)
- Consumers have been notified (documentation, announcements, direct contact)
- A rollback plan exists (if the migration goes wrong)
- Old code cleanup is complete (compat layer → removal → ADR marked as "deprecated")