Deprecation And Migration

Deprecation & Migration — 코드 부채 정리 + 안전한 마이그레이션

코드는 자산이 아니라 부채다. 유지보수할 코드가 적을수록 팀은 빠르게 움직인다. 삭제하지 못하는 코드는 미래의 버그이고, 마이그레이션하지 않는 레거시는 기술 부채의 이자다.

Quick Start

/deprecate                          # 대화형 폐기/마이그레이션 계획 수립
/deprecate scan                     # 프로젝트 내 폐기 대상 스캔
/deprecate plan "jQuery → vanilla"  # 특정 마이그레이션 계획 생성
/deprecate api v1 → v2              # API 버전 전환 계획
/deprecate audit                    # 기술 부채 감사

공식 호출명: /deprecate (별칭: 마이그레이션, 레거시 정리, 코드 부채)

적용 시점

CRITICAL: First Actions

1. Print Intro

Deprecation & Migration — 코드 부채 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
순서: Audit → Plan → Deprecate → Migrate → Verify → Cleanup

2. 현재 상태 스캔

# 1. @deprecated 어노테이션/주석 찾기
echo "=== @deprecated ==="
grep -rn "@deprecated\|@Deprecated\|# deprecated\|// deprecated\|DEPRECATED" \
  --include="*.{ts,tsx,js,jsx,py,java,go,rb,cs,kt,rs}" . 2>/dev/null | head -30

# 2. TODO/FIXME/HACK 찾기
echo "=== TODO/FIXME/HACK ==="
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" \
  --include="*.{ts,tsx,js,jsx,py,java,go,rb,cs,kt,rs}" . 2>/dev/null | wc -l

# 3. 오래된 의존성 확인
echo "=== Outdated Dependencies ==="
npm outdated 2>/dev/null || pip list --outdated 2>/dev/null || \
  go list -m -u all 2>/dev/null | grep '\[' | head -20

# 4. Dead code 후보 (export되지만 import 안 되는 것)
echo "=== Unused Exports (sample) ==="
grep -rn "^export " --include="*.{ts,tsx,js,jsx}" . 2>/dev/null | head -10

Step 1: 기술 부채 감사 (Audit)

부채 분류 매트릭스

감사 보고서 템플릿

# Tech Debt Audit Report

**Date**: {YYYY-MM-DD}
**Scope**: {프로젝트/모듈}

## Summary
- 총 부채 항목: {N}개
- Critical: {N} | High: {N} | Medium: {N} | Low: {N}

## Critical Items
| # | 항목 | 위치 | 리스크 | 예상 작업량 |
|---|------|------|--------|-----------|
| 1 | {항목} | {파일:라인} | {리스크} | {시간/일} |

## Recommended Migration Order
1. {가장 먼저 해야 할 것} — 이유: {왜}
2. {두 번째} — 이유: {왜}

Step 2: 폐기 계획 (Deprecation Plan)

2.1 API 폐기 패턴

# API Deprecation Plan: {API 이름} v{old} → v{new}

## Timeline
| 단계 | 날짜 | 조치 |
|------|------|------|
| Announce | {D-day} | 폐기 공지 + v{new} 제공 |
| Sunset Warning | {+30일} | 응답 헤더에 Sunset 추가 |
| Usage Drop Gate | {+60일} | v{old} 사용률 < 5% 확인 |
| Soft Removal | {+90일} | v{old} 410 Gone 반환 |
| Hard Removal | {+120일} | v{old} 코드 삭제 |

## API Response Headers (Sunset 기간)
```http
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/v2/docs>; rel="successor-version"

Migration Guide for Consumers

### 2.2 라이브러리 마이그레이션 패턴

```markdown
# Migration Plan: {old-lib} → {new-lib}

## Compatibility Layer (Strangler Fig 패턴)
1. new-lib를 설치하고 old-lib과 공존
2. 새 코드는 new-lib으로 작성
3. 기존 코드를 모듈 단위로 전환
4. old-lib 사용처가 0이 되면 제거

## File-by-File Migration Tracker
| 파일 | 상태 | old-lib 사용 | 비고 |
|------|------|-------------|------|
| src/components/Button.tsx | migrated | 0 | |
| src/utils/api.ts | pending | 3 | 복잡도 높음 |
| src/pages/Home.tsx | pending | 1 | |

2.3 코드 폐기 마킹

언어별 폐기 어노테이션:

// TypeScript/JavaScript
/** @deprecated Use `newFunction()` instead. Will be removed in v3.0. */
export function oldFunction(): void { ... }

# Python
import warnings
def old_function():
    """Deprecated: Use new_function() instead. Removed in v3.0."""
    warnings.warn("old_function is deprecated, use new_function", DeprecationWarning, stacklevel=2)
    return new_function()

// Java
@Deprecated(since = "2.0", forRemoval = true)
public void oldMethod() { ... }

// C#
[Obsolete("Use NewMethod() instead. Will be removed in v3.0.", false)]
public void OldMethod() { ... }

Step 3: 마이그레이션 실행

3.1 Strangler Fig 패턴 (점진적 교체)

Phase 1: 공존 — old + new 모두 동작
  └─ new-lib 설치, adapter/bridge 작성
  └─ 새 코드는 무조건 new 사용

Phase 2: 전환 — 모듈 단위로 old → new 교체
  └─ 리스크 낮은 모듈부터 시작
  └─ 각 모듈 전환 후 테스트

Phase 3: 정리 — old 제거
  └─ old-lib 사용처 0 확인
  └─ old-lib 의존성 제거
  └─ adapter/bridge 코드 제거

3.2 Feature Flag 기반 전환

// 피처 플래그로 old/new 전환
if (featureFlags.isEnabled('use-new-auth')) {
  return newAuthService.login(credentials);
} else {
  return legacyAuthService.login(credentials);  // @deprecated
}

3.3 마이그레이션 스크립트 (자동화 가능한 경우)

# codemod 예시 (jscodeshift)
npx jscodeshift -t transforms/old-to-new.ts src/**/*.tsx

# AST 기반 변환 (Python)
python -m libcst.tool codemod old_to_new.OldToNewTransform .

# sed 기반 단순 치환 (최후 수단)
find src -name "*.ts" -exec sed -i 's/oldImport/newImport/g' {} +

Step 4: 검증

마이그레이션 완료 검증 체크리스트

회귀 테스트 전략

# 전체 테스트 실행
npm test -- --coverage    # JS/TS
pytest --cov=src          # Python
go test -cover ./...      # Go

# 마이그레이션 전후 스냅샷 비교 (API 응답)
diff <(curl -s localhost:3000/api/v1/users) <(curl -s localhost:3000/api/v2/users)

Step 5: 정리 + 문서화

마이그레이션 후 Dead Code 정리

마이그레이션 완료 후 old 코드 잔재물 정리는 /hestia(헤스티아)를 사용합니다:

/hestia scan    # 미사용 export, 의존성, 파일 스캔
/hestia clean   # 스캔 + 자동 삭제

마이그레이션 ADR 작성

마이그레이션 결정은 반드시 ADR로 기록:

/adr "jQuery를 제거하고 vanilla JS로 전환"

출력 형식

마이그레이션 계획 생성 완료
━━━━━━━━━━━━━━━━━━━━━━━━━━
  대상: moment.js → date-fns
  전략: Strangler Fig (점진적 교체)
  
  현재 상태:
    moment.js 사용처: 47개 파일
    예상 작업량: 3-5일
  
  생성된 산출물:
    - docs/migration-moment-to-datefns.md  (마이그레이션 계획)
    - docs/adr/0008-replace-moment.md      (ADR)
  
  권장 순서:
    1. date-fns 설치 + adapter 작성
    2. utils/ 모듈 먼저 전환 (리스크 낮음)
    3. components/ 전환
    4. moment.js 제거 + 테스트

다음 단계:
  - /adr로 결정 기록 (자동 생성됨)
  - 모듈별 PR 분리 권장
  - /launch로 배포 전 체크

Red Flags — 위험한 마이그레이션 패턴

파이프라인 위치

/deprecate audit → /deprecate plan → /agent-team (구현) → /code-reviewer → /launch
  부채 감사        마이그레이션 계획    병렬 구현          리뷰           출시

독립 실행 가능 — scan, audit, plan 각각 단독 사용 가능.

Related Files