마이그레이션 시스템

Claude Code의 마이그레이션 시스템은 데이터베이스 스키마 마이그레이션이 아닙니다. 마이그레이션 테이블도, 롤백도, 프레임워크도 없습니다. 대신, 모든 마이그레이션 함수는 설계상 멱등이며, 단일 버전 번호로 보호됩니다.

5가지 마이그레이션 유형

• 설정 프로모션 — 기존 설정을 새로운 위치/형식으로 승격
• 모델 앨리어스 업그레이드 — 모델 식별자를 최신 버전으로 갱신
• 설정 키 이름변경 — 설정 키 이름을 변경하면서 값을 보존
• 원샷 리셋 — 특정 설정을 기본값으로 한 번 초기화
• 비동기 파일 마이그레이션 — 디스크 파일 변환 (비동기, fire-and-forget)

main.tsx에서 CURRENT_MIGRATION_VERSION = 11로 정의되며, 전체 동기 마이그레이션 블록을 게이팅합니다:

const CURRENT_MIGRATION_VERSION = 11;

function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings();
    migrateBypassPermissionsAcceptedToSettings();
    migrateEnableAllProjectMcpServersToSettings();
    resetProToOpusDefault();
    migrateSonnet1mToSonnet45();
    migrateLegacyOpusToCurrent();
    migrateSonnet45ToSonnet46();
    migrateOpusToOpus1m();
    migrateReplBridgeEnabledToRemoteControlAtStartup();
    // feature-gated migrations...
    saveGlobalConfig(prev => ({ ...prev, migrationVersion: CURRENT_MIGRATION_VERSION }));
  }
  migrateChangelogFromConfig().catch(() => {});
}

핵심 구조:

• 버전 게이트 — migrationVersion !== CURRENT_MIGRATION_VERSION일 때만 동기 블록 진입
• 순차 실행 — 모든 마이그레이션이 순서대로 실행된 후 버전 번호를 갱신
• 비동기 분리 — migrateChangelogFromConfig()는 게이트 밖에서 fire-and-forget으로 실행

11개 동기 마이그레이션 + 1개 비동기 마이그레이션의 전체 카탈로그:

패턴 A: GlobalConfig의 완료 플래그

데이터만 보고 "이미 완료되었는지" 판단할 수 없을 때 사용합니다. 마이그레이션 완료 후 GlobalConfig에 플래그를 기록합니다:

// 패턴 A — 완료 플래그로 멱등성 보장
function migrateAutoUpdatesToSettings(): void {
  const config = getGlobalConfig()
  if (config.migratedAutoUpdates) return  // 이미 완료 — 건너뜀

  const currentValue = config.autoUpdatesEnabled
  if (currentValue !== undefined) {
    saveUserSettings(prev => ({
      ...prev,
      autoUpdatesEnabled: currentValue,
    }))
  }

  // 환경 변수도 설정 — userSettings 쓰기는 다음 실행까지 효과 없으므로
  process.env.CLAUDE_AUTO_UPDATES = String(currentValue)

  saveGlobalConfig(prev => ({
    ...prev,
    migratedAutoUpdates: true,  // 완료 플래그 기록
  }))
}

패턴 B: 자기멱등 데이터 체크

현재 데이터 값 자체가 "마이그레이션이 필요한지" 직접 알려줄 때 사용합니다. 별도 플래그가 불필요합니다:

// 패턴 B — 데이터 값이 직접 조건이 됨
function migrateSonnet45ToSonnet46(): void {
  const settings = getUserSettings()
  const model = settings.preferredModel

  // 현재 값이 'sonnet-4.5'일 때만 마이그레이션 — 이미 '4.6'이면 건너뜀
  if (model === 'claude-sonnet-4-5-20250514') {
    saveUserSettings(prev => ({
      ...prev,
      preferredModel: 'claude-sonnet-4-6-20250715',
    }))
    // 인메모리 런타임 상태도 업데이트
    setCurrentModel('claude-sonnet-4-6-20250715')
  }
}

모든 모델 마이그레이션은 userSettings만 읽기/쓰기합니다. 병합된 설정은 절대 읽지 않습니다.

config.ts의 migrateConfigFields()는 디스크에서 설정을 읽을 때마다 실행됩니다. runMigrations()와는 별개로, 가장 오래된 스키마 변경을 처리하는 인메모리 변환 레이어입니다.

이 함수의 역할:

• 디스크의 설정 파일이 구 스키마일 때 메모리에서 즉시 변환
• 디스크 파일 자체는 수정하지 않음 — 읽기 전용 변환
• runMigrations()가 처리하지 않는 레거시 필드 호환성 유지

각 마이그레이션은 실행 시 분석 이벤트를 기록합니다:

이 이벤트들은 마이그레이션 도달률과 성공률을 모니터링하는 데 사용됩니다. 특정 마이그레이션이 예상보다 적게 실행되면 배포 문제나 다운그레이드를 의심할 수 있습니다.

7단계 체크리스트

1. 멱등성 패턴 선택 — 패턴 A(완료 플래그)와 패턴 B(자기멱등 데이터 체크) 중 선택
2. 마이그레이션 함수 작성 — userSettings만 읽기/쓰기, 병합 설정 사용 금지
3. runMigrations()에 함수 호출 추가 — saveGlobalConfig 호출 전에 배치
4. CURRENT_MIGRATION_VERSION 증가 — 필수: 버전을 올리지 않으면 기존 사용자에게 마이그레이션이 실행되지 않음
5. 분석 이벤트 추가 — 마이그레이션 실행 시 이벤트 기록
6. 인메모리 상태 업데이트 고려 — userSettings 쓰기는 다음 실행까지 효과 없으므로, 현재 프로세스에서 즉시 적용이 필요하면 인메모리 상태도 업데이트
7. 테스트 — 멱등성 검증 (2회 연속 실행 시 부작용 없음), 깨끗한 상태에서 실행, 이미 마이그레이션된 상태에서 실행

템플릿 코드

// 새 마이그레이션 템플릿 — 패턴 B (자기멱등 데이터 체크)
function migrateOldValueToNewValue(): void {
  const settings = getUserSettings()  // userSettings만 — 병합 설정 금지!

  if (settings.someKey === 'old-value') {
    logEvent('setting_migrated', {
      key: 'someKey',
      from: 'old-value',
      to: 'new-value',
    })

    saveUserSettings(prev => ({
      ...prev,
      someKey: 'new-value',
    }))

    // 필요시 인메모리 상태도 업데이트
    // setCurrentSomeKey('new-value')
  }
}