PPI 리팩터링 우선순위 · use-ai-session 분리 설계 · 코드 성장 원인 분석 P0설계

한 줄 판정

리팩터링 1순위는 게스트 세션 갓훅 2개(use-ai-session 5,514줄 · use-guest-page-session 3,861줄)이고, 그 전에 테스트 CI 게이트와 V1 사체 삭제를 끝내야 한다. 코드가 계속 커지는 이유는 "에이전트가 분리를 안 해서"가 아니라 이미 큰 파일을 건드릴 때 추출 대신 추가를 선택하게 만드는 지침 공백이다. 파일 크기 기준(300/500/1,000 래칫)과 리뷰 게이트 한 줄이 빠져 있다.

이전 감사 전체 코드 감사 (2026-07-02)가 V1 제거·보안·잠재버그를 다뤘고, 이 문서는 그 뒤 두 달 반 동안의 구조 부채와 성장 메커니즘만 본다.

1. 리팩터링 우선순위 — 코드 구조

2. 리팩터링 우선순위 — 컴포넌트·레이아웃·스타일

3. use-ai-session은 왜 5,514줄이 됐나

2026-01-15 생성 741줄 → 02월 853 → 04월 1,831 → 06월 2,618 → 07/13 3,222
→ 07/15 4,007 (+785, LiveKit self-hosted 도입) → 08월 4,362 → 09/01 5,206 → 09/18 5,514

8개월간 커밋 124개, 티켓 61개의 수정이 한 훅에 누적됐다. 원인은 네 가지다.

런타임 3종(realtime·tts·livekit) 때문인가 — 약 3분의 1만

• LiveKit 도입 직전(7/13)에 Realtime+TTS 2종만으로 이미 3,222줄이었다. 도입 자체는 +785, 도입 후 두 달 버그 수정·진단 로그가 +1,507.
• 런타임별 코드는 얇다. startSession 1,187줄 중 LiveKit 언급 80줄, Realtime PC/DC 67줄, TTS 37줄. 나머지 약 1,000줄은 마이크 획득·오디오 엘리먼트·generation 가드·로그로 세 런타임 공통.
• 이벤트 처리는 이미 통합돼 있다. lib/voice-agent/session-events.ts가 3 런타임을 18종 공통 이벤트로 정규화해서 1,150줄 핸들러 안의 런타임 분기는 44줄뿐.
• 런타임 무관 영역이 절반 이상: 응답 취소·게이트·끼어들기·듣기 의도(1056~2330행) 1,274줄, 상단 헬퍼 482, 전사·메타 241, 자동 시작/종료 191, 오디오 정리 124 = 약 2,300줄.

듣기·마이크 제어 비중 — 16%인데 변경 빈도 30%

• ref 21개가 듣기 상태를 나눠 든다 (전체 110개의 19%). isMicrophoneEnabledRef pendingConfiguredListeningRef listeningCommandSinceStartRef liveKitInputGateRef agentInputPolicyRef hostRelayMutedRef가 각각 "듣기 의도"의 일부다. readiness 재시도 후 듣기 ON 미인식이 이 이중소스에서 나왔다.
• 타이머 5종: micRestore, deferMicFallback, aecDelay, cancelledMicRestoreAecBlock, micDeferCancelled. 각각 별 이슈에서 추가됐다.
• 커밋 124개 중 37개(30%)가 듣기·마이크·VAD·헤드셋·AEC. PPI-1167 듣기 자동 ON과 PPI-962 헤드셋 모드는 리버트 후 재적용으로 두 번씩 들어왔다.

4. use-ai-session 분리 설계 승인 대기

프로젝트 brainstorming 스킬의 architectural 경로로 잡았다. 런타임 3종이 모두 살아 있어(lib/voice-agent/resolver.ts:11 VoiceRuntime = "realtime" | "tts" | "livekit") 삭제가 아닌 분리다. 승인 후 docs/superpowers/specs/ 스펙 → writing-plans → code-quality-guardian 순서.

목표 · 비목표

• 목표: 5,514줄 훅을 얇은 오케스트레이터(약 650줄)와 책임별 모듈 7개로 나누되 동작 · 소비자 인터페이스(props 49개, return 키 48개) · 로그 문자열은 그대로.
• 비목표: 런타임 제거, Zustand 전환, 로그 메시지 변경(운영 판별법이 로그 문구에 의존), 버그 수정 동반.

접근 비교

모듈 맵 (B) — apps/web/entities/guest-session/ 기준

공통 정리: 콜백 동기화 effect 17개(onXRef.current = onX)는 useLatestRef 유틸 하나로. 도메인 간 공유 ref(liveKitSessionRef, peerConnectionRef 등 7개)는 오케스트레이터가 소유하는 transportHandleRef 하나로 묶어 서브훅에 주입한다. 서브훅은 트랜스포트를 소유하지 않는다.

분리 후 오케스트레이터 골격 (스케치)

export function useAiSession(props: UseAiSessionProps) {
  // 1) 콜백 props 17개 → useLatestRef 하나로 (effect 17개 제거)
  const callbacks = useLatestRef(props);
  // 2) useState 10개는 그대로 (소비자 인터페이스 불변)
  const [isActive, setIsActive] = useState(false);  /* … 9개 */
  // 3) 트랜스포트 핸들: pc / dataChannel / liveKitSession / ttsPlayer / generation / abort
  const transport = useRef(createTransportHandle());
  // 4) 서브훅: 자기 ref만 소유, 트랜스포트는 주입받아 읽기·명령만
  const audio      = useSessionAudio({ transport, audioOutputDeviceId: props.audioOutputDeviceId });
  const gate       = useResponseGate({ transport, callbacks });
  const listening  = useListeningControl({ transport, callbacks, setGuestMicStream, setIsUserTalking, externalMicStream: props.externalMicStream });
  const transcript = useTranscriptPipeline({ transport, callbacks, setCurrentTranscript });
  const auto       = useAutoStartFinish({ transport, callbacks, gate, transcript });

  // 5) 이벤트: 리듀서가 effects를 돌려주고, 여기서만 실행
  const handleVoiceSessionEvent = useCallback((event: VoiceSessionEvent) => {
    const effects = reduceVoiceSessionEvent(event, {
      gate: gate.snapshot(), listening: listening.snapshot(), transcript: transcript.snapshot(), auto: auto.snapshot(),
    });
    for (const fx of effects) {
      switch (fx.kind) {
        case "setPeerTalking":     setIsPeerTalking(fx.value); break;
        case "gate":               gate.apply(fx); break;
        case "listening":          listening.apply(fx); break;
        case "transcript":         transcript.apply(fx); break;
        case "auto":               auto.apply(fx); break;
        case "audio":              audio.apply(fx); break;
        case "callback":           callbacks.current[fx.name]?.(...fx.args); break;
        case "log":                logger[fx.level](fx.message, fx.fields); break;
      }
    }
  }, [gate, listening, transcript, auto, audio, callbacks]);

  // 6) 시작/종료: generation·abort 가드는 여기, 런타임별 연결은 커넥터 3개로
  const startSession = useCallback(async (params: StartSessionParams) => {
    const generation = transport.current.nextGeneration();
    const signal = transport.current.arm();
    const voiceSession = resolveVoiceSessionForProfile(params.profile);
    const mic = await listening.acquireMic(params.audioDeviceIdOrStream, signal);
    const audioEl = audio.prepareElement();
    if (!transport.current.isCurrent(generation, signal)) return;
    const connector = voiceSession.runtime === "livekit" ? connectLiveKit
                    : voiceSession.runtime === "tts"     ? connectTts : connectRealtime;   // 런타임 분기는 여기 한 곳
    const connected = await connector({ voiceSession, mic, audioEl, signal,
      onEvent: (e) => handleVoiceSessionEventRef.current(e), onRemoteStream: setAiAudioStream });
    if (!transport.current.isCurrent(generation, signal)) { connected.dispose(); return; }
    transport.current.attach(connected);
    listening.applyPendingAfterConnect();   // pendingVadSettings, configured 듣기 의도
    auto.sendStartMessageIfNeeded();
    setIsActive(true);
  }, [listening, audio, auto]);

  // 8) return: 키 48개 그대로, 구현만 서브훅으로 위임
  return { isSessionActive: isActive, isActive, isPeerTalking, /* … 상태 */
    handleStartSession, handleStopSession,
    ...gate.api, ...listening.api, ...transcript.api, ...auto.api, ...audio.api };
}

검증 전략 · 체크포인트

1. 하네스 — 리듀서 characterization 테스트(현재 동작을 그대로 기록, 케이스 16개) + useAiSession renderHook 스모크 1개. vitest jsdom 환경 존재. 이 저장소 관행("훅은 얇게, 로직은 순수 함수로 뽑아 테스트")과 일치.
2. 순수 함수·useLatestRef 추출 (무위험)
3. 이벤트 리듀서 추출 — 가장 먼저 테스트 효과가 나는 지점
4. 트랜스포트 커넥터 3개 추출
5. 서브훅 4개 순차 (listening → gate → transcript → auto)
6. 오케스트레이터 정리

• 매 체크포인트: tsc + vitest + 소비자 2곳(use-guest-page-session.ts:864, use-toggle-headset-mode.ts) 인터페이스 diff 0.
• 실기기 3런타임(특히 iPad livekit) 확인은 사람 몫. 커밋은 검증 후 사용자가, 에이전트는 워킹트리까지.
• 체크포인트별 PR 5~6개 권장 — 실기기 검증을 단계마다 끼울 수 있다. 단일 PR과의 선택은 사용자 결정 대기.

5. 최근 한 달, 왜 코드가 계속 늘었나

결론 — 총량 증가의 주범은 기능 볼륨이고, 지침 부재가 만든 문제는 "핫파일에 덧붙이기" 한 패턴에 국한된다. 분리 지침은 실제로 없다. 다만 그것이 전체 증가의 원인은 아니다.

[한 달 순증 +5.2만 줄, 런타임 ts/tsx · 2026-08-18~09-18 · 커밋 103개]
  ├─ 신규 파일 +3.7만 (261개)          ← 기능 추가. 에이전트는 새 모듈을 잘 만듦
  ├─ 300줄 미만 파일 +1.1만              ← 정상 성장
  ├─ 1000~3000줄 파일 −0.4만             ← 레거시 제거(−5,608)·MFCC 제거(−3,586)가 상쇄
  └─ 3000줄+ 파일 +0.3만                ← 문제 구간. 파일 4개에 집중
        use-ai-session +954 / use-guest-page-session +715 / db-queries +1,379 / livekit-client-session +2,159

[핫파일 덧붙이기 메커니즘]
  이슈 티켓(PPI-1219 재응답 차단, 1252 후속발화 차단, 1102 듣기 복원 …)
  → brainstorming "bounded" 경로 = "기존 흐름을 수정" 으로 분류
  → 가드 ref + effect를 기존 훅 안에 추가 (+20~140줄/커밋, use-ai-session 11커밋 중 9개가 순증)
  → 검토 게이트에 파일 크기·책임 분리 기준 없음 → 통과
  → 5,514줄

근거

• 추정 에이전트 작업 비중: 머지 PR 100개 중 86개가 Claude Code 기본 템플릿(Summary/Test plan) 사용. Co-Authored-By 서명은 squash 과정에서 대부분 사라져 13개만 남았다. 사실상 거의 전부 에이전트 작업.
• 사실 분리 지침 부재: CLAUDE.md, .claude/CLAUDE.md, AGENTS.md에 파일 크기·책임 분리·새 모듈 배치 규칙 0건. ESLint에 max-lines·complexity 룰 없음. 8/25 도입된 code-quality-guardian은 "복잡도 회귀 방지"를 표방하지만 실제 12단계는 동작 보존·하네스·리뷰이고 크기 기준은 없다. code-review-expert의 SOLID 체크리스트에도 크기·추출 항목이 없다.
• 사실 그러나 에이전트는 새 모듈을 만든다: 신규 파일 261개, lib/voice-agent에만 27개. 순증의 70%가 신규 파일. "분리 자체를 안 한다"는 가설은 기각.
• 사실 문제는 기존 핫파일 수정 방식: use-ai-session 한 달 추가 1,453줄 중 ref 관련 219줄(15%), 로그 85줄. 커밋당 +20~140줄이 훅 안에 들어가고, 뺀 커밋은 MFCC 제거(−60) 하나. livekit-client-session.ts는 4,131줄이 됐는데 export function 40개가 한 파일에 계속 추가됐다.
• 사실 guardian 도입(8/25) 이후에도 패턴 그대로: 도입 후 1,000줄+ 파일에 순증한 커밋 상위 12개 중 outlier 제외 11개가 평균 +200줄씩 덧붙였다.

6. VP 통합 커밋(b7db1a7c, #1041) 해부 — 부당한 순증인가

한 달 순증의 절반 이상을 차지하는 커밋이다. "VP 모드"가 3만 줄이 아니고, 154개 커밋을 하나로 squash한 통합 PR이 16.6만 줄이다.

b7db1a7c (#1041) 633 files, +166,076 / −8,046   PR 생성→머지 57초, PR #1006(PPI-1176) 통합
  ├─ apps/livekit-agent/vendor/*  +86.8k  ← LiveKit Agents 1.7.1 파이썬 런타임 vendoring (작성 코드 아님)
  ├─ 테스트                        +37.2k  ← socket 19.9k, agent 9.3k, web 8k
  ├─ 런타임 ts/tsx                 +31.3k  ← 기능 4개 묶음 (신규 438파일 +13.3만 / 기존 192파일 +2.5만 전체 기준)
  └─ 설정·문서·기타                 +2.7k

런타임 3.1만의 구성 (PR 본문 4개 섹션 ↔ 디렉터리 순증 대조)
  SFU 인증·재연결 + 음성 제어 전달(Redis)  약 13k   avatar-handlers +2,430 · voice-control-delivery-store +1,720(신규) · sfu-socket +9.4k · redis +3.6k
  LiveKit VP 대화 처리(클라이언트)          약  9k   livekit-client-session +1,802 · lib/voice-agent 신규 다수
  모니터·게스트 UI 상태 복구                약  6k   use-guest-page-session +2,500 · features/monitor +2,505 · host-socket +1,430
  관측성·API·공유 타입                      약  3k   lib/api +1,720 · shared/lib +1,403

"안정화" 13k의 실체 — 소켓 런타임이 2배가 됐다 (13,573 → 27,812)

socket 런타임 +14,239
  ├─ 기존 핸들러에 추가  +7.5k   avatar-handlers +2,430 · connection-handlers +1,386 · monitoring-handlers +851
  │                              pending-disconnect-tracker +826 · session-relay +636 · room-store +585
  └─ 신규 모듈          +6.7k   voice-control-delivery-store 1,720 · livekit-input-diagnostics 575
                                 voice-control-transition-store 467 · monitor-recipient-auth 355 · monitor-control-auth 266
                                 credential-refresh/lifecycle 318 · admission·principal·claim 스토어 6개

• 사실 avatar-handlers.ts 추가 2,411줄 중 generation/fence/lease 311줄, voiceControl 219줄, 함수 선언 158개, 로그 30줄. 디버그 로그가 아니라 음성 제어 명령의 전달 보장(ACK·재전달·generation fence·소유권 lease) 로직이다.
• 사실 voice-control-delivery-store.ts 1,720줄은 export 23개, Redis multi/eval 52곳. Redis 기반 전달 상태 머신.

7. 코드 분할 기준 제안 — 300 / 500 / 1,000 래칫

런타임 ts/tsx 1,184개, 총 23.5만 줄 · 중앙값 82 · p75 197 · p90 433 · p95 693
  >300줄  188개(16%)  → 전체 코드의 64%
  >500줄  100개( 8%)  → 49%
  >1000줄  30개(2.5%) → 29%

훅(use-*) 147개 · 중앙값 130 · p75 245 · p90 535 · 300 초과 28개(19%) · eslint max-lines/complexity 룰 없음

• 추정 래칫으로 잡는 이유: 절대 상한(500 초과 금지)은 지금 100개 파일을 한 번에 위반 상태로 만들어 무시된다. 래칫은 "지금보다 커지지 않게"만 요구하므로 첫날부터 실효성이 있다. 지난달 1,000줄+ 파일에 붙은 커밋 11개(평균 +200줄) 대부분이 500줄 래칫이 있었다면 추출을 요구받았을 변경이다.
• 보조 기준 — 훅: useRef 20개 또는 useEffect 10개 초과 시 서브훅 분리 (use-ai-session 110/32, use-guest-page-session 62/41). 소켓 핸들러: socket.on 하나당 평균 100줄 초과 시 서비스 함수 추출 (avatar-handlers 240). 함수: 100줄 초과 시 분리 (handleVoiceSessionEvent 1,150, startSession 1,187).
• 적용 위치 세 곳 — ESLint max-lines: 300(신규만) · guardian 1단계 bounded 분류 조건에 "대상 파일 500줄 초과 시 추출 체크포인트 필수" · code-review-expert 게이트에 "파일 줄 수 delta 보고". 지침 두 줄과 lint 룰 하나로 끝난다.

8. 확정 / 추정 경계

관련 문서

• 전체 코드 감사 — 기술부채·레거시·잠재버그 우선순위 (2026-07-02) — V1 제거 플랜·보안·잠재버그. 이 문서는 그 이후의 구조 부채만 다룬다
• readiness 타임아웃 자동재시도 후 듣기 ON 미인식 — §3 듣기 의도 이중소스가 실제 버그로 나타난 사례
• LiveKit 에이전트 모드 — 세션 연결 전체 구조 — §4 커넥터 3개 중 livekit 경로의 현재 동작
• LiveKit 음성 에이전트 흐름 — 두 SFU 구조 코드레벨 시각화 — §6 VP 통합 커밋이 만든 구조