상태 관리

Claude Code의 상태 관리는 외부 라이브러리 없이 3개 레이어로 구성됩니다:

• 레이어 1 — Primitive: createStore<T> — 35줄의 커스텀 스토어. 구독, 업데이트, 사이드 이펙트를 처리하는 최소 단위
• 레이어 2 — Domain: AppState + AppStateStore — 약 400개 필드를 가진 애플리케이션 전체 상태와 그 스토어
• 레이어 3 — React: AppStateProvider + hooks — React 컴포넌트가 상태를 구독하고 업데이트하는 인터페이스

이 구조를 보완하는 두 가지 핵심 메커니즘:

• 사이드 이펙트: onChangeAppState — 모든 상태 전환에서 실행되는 단일 관찰자
• 파생 상태: selectors.ts — 스토어에서 필요한 값을 도출하는 순수 함수 모음

전체 상태 관리의 기반이 되는 createStore<T>는 놀라울 정도로 간결합니다:

// createStore — 35줄 커스텀 스토어 (간소화)
function createStore<T>(
  initialState: T,
  onChange?: (prev: T, next: T) => void
) {
  let state = initialState
  const listeners = new Set<() => void>()

  return {
    getState(): T { return state },

    setState(updater: (prev: T) => T) {
      const next = updater(state)
      if (Object.is(state, next)) return  // 조기 반환!
      const prev = state
      state = next
      onChange?.(prev, next)
      listeners.forEach(l => l())
    },

    subscribe(listener: () => void) {
      listeners.add(listener)
      return () => listeners.delete(listener)
    }
  }
}

핵심 설계 결정:

• Object.is 동등성 체크: updater가 같은 참조를 반환하면 업데이트, 사이드 이펙트, 리스너 통지 모두 건너뜁니다. 불필요한 재렌더를 원천 차단합니다.
• updater 함수 패턴: setState가 부분 객체가 아닌 (prev) => next 형태의 업데이터 함수를 받습니다. 이전 상태를 기반으로 안전하게 업데이트할 수 있으며, 동시 업데이트 시 경쟁 조건을 방지합니다.
• 자체 구현 이유: Zustand/Jotai 같은 라이브러리는 리액트 외부 소비자(Node.js 백엔드 로직) 지원, 번들 크기, 세밀한 제어 요구 사항에서 오버헤드가 됩니다. 35줄로 필요한 모든 것을 제공합니다.

AppState는 약 400개 필드를 가진 거대한 타입으로, 6개 논리 범주로 구성됩니다:

• 세션 코어: 세션 ID, 모델 설정, 대화 히스토리, 사용량 카운터
• UI 상태: 입력 모드, 확장 뷰, 테마, 사이드바 상태
• 권한: 권한 모드, 승인된 도구 목록, 보안 정책
• 에이전트 & 태스크: 에이전트 모드, 작업 큐, 팀메이트 상태
• 원격 & 브릿지: 원격 연결 상태, 브릿지 모드 설정
• 하위 시스템: MCP 서버 상태, 훅 설정, 분석 구성

// AppState 타입 패턴 (간소화)
type AppState = DeepImmutable<{
  // 세션 코어
  sessionId: SessionId
  model: ModelId
  messages: Message[]
  totalCostUSD: number

  // UI 상태
  expandedView: boolean
  verbose: boolean
  inputMode: InputMode

  // 권한
  permissionMode: PermissionMode
  approvedTools: Set<string>
  // ... 약 390개 추가 필드
}> & {
  // 가변 필드 — DeepImmutable에서 제외
  mutableMessages: MutableMessage[]
}

DeepImmutable<...> & { 가변필드 } 패턴은 대부분의 상태를 불변으로 보호하면서, 성능상 가변성이 필요한 필드(예: 대화 히스토리의 스트리밍 업데이트)를 명시적으로 허용합니다.

onChangeAppState는 createStore의 onChange 콜백으로 등록되어 모든 상태 전환에서 실행되는 단일 관찰자입니다.

처리하는 사이드 이펙트:

• 권한 모드 CCR 동기화: 권한 모드 변경 시 CCR(Claude Code Runtime)에 동기화
• 모델 설정 영속화: 모델 변경 시 디스크에 저장
• expandedView/verbose 저장: UI 설정 변경 시 사용자 설정에 영속화

React 컴포넌트가 AppState에 접근하는 세 가지 훅:

• useAppState(selector): 선택자 함수로 필요한 상태만 구독. Object.is로 비교하여 선택된 값이 변하지 않으면 재렌더하지 않음
• useSetAppState(): 상태 업데이트 함수 반환. setState와 동일한 updater 패턴
• useAppStateStore(): 스토어 인스턴스 자체를 반환. 렌더링 외부에서 getState()로 현재 값을 읽어야 할 때 사용

AppStateProvider는 이 스토어를 React 트리에 주입하는 얇은 브리지입니다. 동시에 notification, voice, mailbox, speculation 같은 React 전용 provider들은 따로 감싸며, 이런 상태를 전부 AppState로 밀어 넣지 않습니다. 즉 Provider 레이어는 "공용 도메인 상태"와 "UI 전용 보조 상태"를 나누는 경계 역할도 합니다.

// 위험! 매번 새 객체 생성 → Object.is 항상 false → 스토어 변경마다 재렌더
useAppState(s => ({ a: s.a, b: s.b }))

// 안전한 대안 1: 개별 값 구독
const a = useAppState(s => s.a)
const b = useAppState(s => s.b)

// 안전한 대안 2: selectors.ts의 순수 selector 재사용

selectors.ts는 Pick<AppState, ...>를 받는 순수 함수 모음입니다. 전체 AppState가 아닌 필요한 필드만 받기 때문에:

• 테스트에서 전체 상태를 모킹할 필요 없음
• 어떤 필드에 의존하는지 타입 수준에서 명시
• React 외부(Node.js 백엔드)에서도 동일하게 사용 가능

여기서 중요한 실무 규칙은, selector가 "새 구조를 조립하는 곳"이 아니라 "이미 있는 상태에서 읽어내는 곳"에 가깝다는 점입니다. 새 객체를 만들어야 한다면 호출부 인라인보다 별도 selector 함수로 빼서 의존 필드를 명확히 드러내는 편이 낫습니다.

teammateViewHelpers.ts는 팀메이트 에이전트의 유지/퇴거 생명주기를 관리하는 전환 헬퍼입니다. 팀메이트의 존재 여부와 상태 전이는 React 화면만의 문제가 아니라 작업 큐, 에이전트 상태, 비React 소비자도 함께 읽어야 하는 도메인 정보이므로, 단순 UI Context가 아니라 상태 전환 헬퍼 쪽에 가깝게 배치됩니다.

상태 관리의 전체 데이터 흐름을 하나의 다이어그램으로 정리합니다. 사용자 인터랙션 또는 API 응답이 스토어를 업데이트하고, 사이드 이펙트를 거쳐 UI에 반영되기까지의 과정입니다.

핵심 포인트: setState는 항상 Object.is로 변경 여부를 판단한 후에만 onChangeAppState와 리스너 통지를 수행합니다. 이 체크가 불필요한 사이드 이펙트와 재렌더를 원천 차단하는 게이트키퍼 역할을 합니다.

• store.setState(updater) — updater 함수가 이전 상태를 받아 다음 상태를 반환
• onChangeAppState — 상태 전환 시 실행되는 단일 관찰자. CCR 동기화, 설정 영속화 등 모든 사이드 이펙트를 중앙 집중 처리
• listeners — React의 useSyncExternalStore가 등록한 구독자. 상태 변경 시 선택자 기반으로 필요한 컴포넌트만 재렌더

Claude Code에서 모든 공유 데이터가 AppState에 사는 것은 아닙니다. React Context에 배치되는 데이터와 AppState에 배치되는 데이터의 경계를 이해하는 것이 중요합니다.

React Context에 사는 데이터

아래 데이터는 AppState가 아닌 전용 React Context에 배치됩니다:

• modalContext — 모달 다이얼로그의 표시 여부와 콘텐츠. 일시적이고 UI 전용인 상태
• overlayContext — 오버레이 레이어의 표시/숨김 제어
• promptOverlayContext — 프롬프트 오버레이(권한 요청 등)의 표시 상태
• notifications — 토스트 알림 큐. 표시 후 자동 제거되고, 타이머와 dismiss 콜백을 동반하는 UI 전용 상태
• fpsMetrics — 프레임 레이트 모니터링 데이터. 디버깅 전용
• mailbox — 컴포넌트 간 비동기 메시지 전달 채널
• voice — 음성 입력 상태와 설정
• speculation — 응답 중간 표시나 예측 렌더링에 가까운 임시 UI 상태
• QueuedMessage — 전송 대기 중인 메시지 큐

경계 판단 기준

AppState에 배치되는 데이터와 Context에 배치되는 데이터의 경계는 다음 기준으로 결정됩니다:

• 영속성: 세션 간에 저장/복원이 필요한 데이터 → AppState. 일시적으로 표시되고 사라지는 데이터 → Context
• 소비자 범위: React 외부(Node.js 백엔드, 테스트)에서도 접근이 필요한 데이터 → AppState. 순수 UI 컴포넌트에서만 소비되는 데이터 → Context
• 사이드 이펙트: 변경 시 CCR 동기화, 디스크 저장 등 사이드 이펙트가 필요한 데이터 → AppState (onChangeAppState가 처리). UI 내부에서만 소비되는 타이머, dismiss, overlay 제어 같은 값 → Context

정리하면, notification이나 speculation은 "앱 전체가 알아야 하는 도메인 상태"라기보다 특정 Provider가 소유한 UI 협조 상태입니다. 반대로 permissionMode, model, teammate 상태 같은 값은 React 밖에서도 읽히고, 선택자와 전환 헬퍼의 대상이 되므로 AppState에 남습니다.

// AppState — 영속적, React 외부 접근, 사이드 이펙트 필요
type AppState = {
  sessionId: SessionId           // 세션 코어 — 영속
  permissionMode: PermissionMode // 권한 — CCR 동기화 필요
  model: ModelId                 // 설정 — 디스크 저장 필요
  messages: Message[]            // 대화 히스토리 — 백엔드 소비
}

// React Context — 일시적, UI 전용, 사이드 이펙트 불필요
const ModalContext = createContext<ModalState>(...)
const NotificationContext = createContext<Notification[]>(...)
const VoiceContext = createContext<VoiceState>(...)