drvoss Deprecation and Migration
When to Use
- API/함수를 제거하거나 교체할 때
- 라이브러리 또는 패턴을 마이그레이션할 때
- 레거시 코드를 점진적으로 제거할 때
- Breaking change를 포함한 메이저 버전 릴리즈 준비
코드는 자산이 아닌 부채다. 유지해야 할 코드가 많을수록 비용이 증가한다.
Prerequisites
- 현재 사용처 파악 (
grep -rn "deprecated_api") - 대체 API 또는 패턴 준비됨
- 영향 받는 팀/소비자 파악
Workflow
1. 사용처 파악 및 영향 분석
# 제거할 심볼의 모든 사용처 찾기
grep -rn "oldFunction\|OldClass\|OLD_CONSTANT" src/ --include="*.ts"
# 외부 소비자 확인 (공개 npm 패키지인 경우)
# npm 레지스트리에서 역의존성 확인
open https://www.npmjs.com/package/your-package-name?activeTab=dependents
# 또는 GitHub에서 usage 검색
gh search code "from 'your-package-name'" --limit 20
2. 3단계 Deprecation 프로세스
Phase 1: 경고 추가 (Soft Deprecation)
/** @deprecated Use `newFunction()` instead. Will be removed in v3.0. */
export function oldFunction() {
console.warn('[Deprecated] oldFunction() will be removed in v3.0. Use newFunction() instead.');
return newFunction();
}
Phase 2: 마이그레이션 가이드 작성
CHANGELOG와 문서에 기록:
## Migration Guide: v2 → v3
### `oldFunction()` → `newFunction()`
Before: `oldFunction(arg1, arg2)`
After: `newFunction({ param1: arg1, param2: arg2 })`
Phase 3: 제거 (Hard Removal)
메이저 버전 업에서만 제거. 제거 전 마지막 확인:
# 코드베이스 내 잔여 사용처 없는지 확인
grep -rn "oldFunction" src/ tests/
# 결과: 0건이어야 제거 가능
3. Strangler Fig 패턴 (점진적 마이그레이션)
전면 교체 대신 신구 코드가 공존하며 점진적으로 전환:
Old System ─┐
├─→ Router/Adapter ─→ New System (새 요청)
Old System ←┘ (기존 요청은 old로)
Copilot의 session-management 스킬로 마이그레이션 진행 상황 추적:
INSERT INTO todos (id, title, status) VALUES ('migrate-user-service', 'Migrate UserService to new auth', 'in_progress');
4. 완전 제거 체크리스트
# 1. 모든 사용처 제거 확인
grep -rn "oldPattern" . --include="*.{ts,js,py}"
# 2. 테스트 파일도 확인
grep -rn "oldPattern" tests/
# 3. 문서에서도 제거
grep -rn "oldPattern" docs/ README.md
# 4. 마이그레이션 완료 후 어댑터/wrapper 제거
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "혹시 모르니 deprecated 코드를 남겨두겠다" | 남겨둔 코드는 유지보수 대상이 된다. 제거하거나 명시적으로 tombstone 처리한다. |
| "사용처를 다 찾을 수 없어서 못 지운다" | grep과 IDE로 정확히 찾을 수 있다. 찾을 수 없다면 동적 호출이다 — 이것도 문서화해야 한다. |
| "한 번에 전부 바꾸겠다" | 큰 마이그레이션은 실패한다. Strangler Fig로 점진적으로 전환한다. |
| "하위 호환성을 영원히 유지해야 한다" | 하위 호환성에는 비용이 있다. Breaking change를 두려워하지 않는다. Semantic versioning이 있다. |
Red Flags
@deprecated주석만 있고 언제 제거하는지 없음- 제거 예정 코드가 수년간 남아있음
- 마이그레이션 가이드 없는 breaking change
- 제거 전
grep으로 잔여 사용처 확인 안 함
Verification
- 제거된 API의 모든 사용처가 마이그레이션됨
-
grep -rn "removed_symbol"결과 0건 - CHANGELOG에 breaking change 기록됨
- 마이그레이션 가이드가 문서에 포함됨
- 마이그레이션 후 전체 테스트 통과
Tips
refactor-clean스킬과 함께 사용: 제거 후 남은 dead code 정리add-to-changelog스킬로 마이그레이션 가이드를 CHANGELOG에 자동 추가- 공개 라이브러리라면 deprecation warning을 최소 1 메이저 버전 동안 유지한다