메시지 처리 파이프라인

사용자가 Enter를 누르면 텍스트가 Claude API에 도달하기까지 4단계 파이프라인을 통과합니다. 각 단계에서 입력이 분류, 확장, 변환되며, 최종적으로 API가 이해할 수 있는 정규화된 메시지 배열로 변환됩니다.

4단계 파이프라인:

• 1단계 — Submit & Route: 큐 가드, 붙여넣기 참조 확장, 초기 라우팅
• 2단계 — Input Classification: 이미지 전처리, 3방향 라우팅, ultraplan 키워드 감지
• 3단계 — Message Construction: 프롬프트 처리, 사용자 메시지 생성, 합성 메시지
• 4단계 — API Normalization: 다중 패스 정규화, 메시지 분류, 쿼리 프로파일링

handlePromptSubmit은 사용자 입력을 처리하는 최초 진입점입니다. 큐 가드로 동시 제출을 방지하고, 붙여넣기된 참조를 확장합니다.

// messages/handlePromptSubmit.ts — 큐 가드 & 참조 확장
let isProcessing = false

async function handlePromptSubmit(rawInput: string): Promise<void> {
  // 큐 가드: 이전 요청이 처리 중이면 무시
  if (isProcessing) {
    showWarning('이전 요청을 처리 중입니다...')
    return
  }
  isProcessing = true

  try {
    // 붙여넣기 참조 확장: @파일경로 → 파일 내용 인라인
    const expanded = expandPasteReferences(rawInput)

    // 입력 분류로 전달
    await processUserInput(expanded)
  } finally {
    isProcessing = false
  }
}

붙여넣기 참조 확장

사용자가 @src/main.ts 형태로 파일을 참조하면, 해당 파일의 내용이 인라인으로 확장됩니다. 이는 Claude에게 파일 전체를 보여주고 싶을 때 수동으로 복사-붙여넣기하는 수고를 덜어줍니다.

processUserInput은 확장된 입력을 분석하여 3방향 라우팅을 수행합니다. 이미지 전처리, ultraplan 키워드 감지도 이 단계에서 처리됩니다.

// messages/processUserInput.ts — 3방향 라우팅
async function processUserInput(input: ExpandedInput): Promise<void> {
  // 이미지 전처리: 붙여넣기된 이미지를 base64로 변환
  const processed = await preprocessImages(input)

  // 라우팅 1: 슬래시 커맨드
  if (processed.text.startsWith('/')) {
    return handleSlashCommand(processed)
  }

  // 라우팅 2: ULTRAPLAN 키워드 감지
  if (shouldTriggerUltraplan(processed.text)) {
    return launchUltraplan(processed)
  }

  // 라우팅 3: 일반 메시지 → 메시지 구성으로
  await processTextPrompt(processed)
}

이미지 전처리

사용자가 이미지를 터미널에 붙여넣으면 자동으로 감지되어 base64로 인코딩됩니다. 지원 형식(PNG, JPEG, GIF, WebP)이 확인되고, 크기 제한(20MB)이 적용됩니다.

3방향 라우팅

입력은 세 가지 경로 중 하나로 분기됩니다:

• 슬래시 커맨드: /로 시작하는 입력은 커맨드 핸들러로 전달됩니다
• ULTRAPLAN: 복잡한 계획 키워드가 감지되면 원격 Opus 세션으로 위임됩니다
• 일반 메시지: 나머지 모든 입력은 메시지 구성 단계로 진행됩니다

메시지 구성 단계에서는 사용자 입력을 Claude API가 이해하는 메시지 구조로 변환합니다. processTextPrompt이 텍스트를 처리하고, createUserMessage가 최종 메시지 객체를 생성합니다.

// messages/processTextPrompt.ts — 메시지 구성
async function processTextPrompt(input: ProcessedInput): Promise<void> {
  // 사용자 메시지 생성
  const userMsg = createUserMessage({
    text: input.text,
    images: input.images,       // base64 인코딩된 이미지
    files: input.fileContents,  // @참조로 확장된 파일 내용
  })

  // 합성 메시지: 컨텍스트 강화를 위한 추가 메시지
  const syntheticMsgs = buildSyntheticMessages({
    systemMemory: getSessionMemory(),
    recentFiles: getRecentlyEditedFiles(),
    gitStatus: getGitStatus(),
  })

  // 메시지 배열 구성
  const messages = [...syntheticMsgs, userMsg]

  // API 정규화로 전달
  await sendToAPI(normalizeMessagesForAPI(messages))
}

합성 메시지

합성(synthetic) 메시지는 사용자가 직접 입력하지 않았지만, 컨텍스트를 강화하기 위해 자동으로 생성되는 메시지입니다. 세션 메모리, 최근 편집 파일, git 상태 등이 합성 메시지로 주입됩니다.

normalizeMessagesForAPI는 내부 메시지 배열을 Claude API가 요구하는 형식으로 정규화합니다. 다중 패스로 처리됩니다.

// messages/normalizeMessagesForAPI.ts — 다중 패스 정규화
function normalizeMessagesForAPI(messages: InternalMessage[]): APIMessage[] {
  let result = messages

  // 패스 1: 연속된 같은 역할의 메시지를 병합
  // API 제약: user/assistant가 교대로 와야 함
  result = mergeConsecutiveSameRole(result)

  // 패스 2: 빈 텍스트 블록 제거
  result = removeEmptyTextBlocks(result)

  // 패스 3: 도구 사용 결과를 올바른 위치에 배치
  result = reorderToolResults(result)

  // 패스 4: 컨텍스트 윈도우 초과 시 오래된 메시지 압축
  result = compressIfOverLimit(result, contextWindowSize)

  // 패스 5: 최종 API 형식 변환
  return result.map(toAPIFormat)
}

내부적으로 메시지는 6가지 타입으로 분류됩니다. 각 타입은 파이프라인에서 다르게 처리됩니다.

// 6가지 메시지 타입
type MessageType =
  | 'user_text'        // 사용자가 직접 입력한 텍스트
  | 'user_image'       // 사용자가 붙여넣기한 이미지
  | 'assistant_text'   // Claude의 텍스트 응답
  | 'tool_use'         // Claude의 도구 사용 요청
  | 'tool_result'      // 도구 실행 결과
  | 'synthetic'        // 시스템이 자동 생성한 컨텍스트 메시지

각 타입의 정규화 처리:

• user_text / user_image: 그대로 API 형식으로 변환
• assistant_text: 이전 응답으로, 대화 히스토리에 포함
• tool_use / tool_result: 반드시 쌍을 이루어야 하며, 순서가 보장됨
• synthetic: 사용자가 보지 못하는 시스템 컨텍스트, 컨텍스트 부족 시 우선 압축 대상

메시지 처리 파이프라인은 각 쿼리의 특성을 프로파일링하여 최적의 처리 전략을 결정합니다.

// 쿼리 프로파일링 — 입력 특성 분석
interface QueryProfile {
  tokenCount: number         // 입력 토큰 수 추정
  hasImages: boolean          // 이미지 포함 여부
  hasFileRefs: boolean        // @파일 참조 포함 여부
  estimatedComplexity: 'simple' | 'moderate' | 'complex'
  suggestedEffort: EffortLevel // 권장 노력 수준
}

function profileQuery(messages: InternalMessage[]): QueryProfile {
  const totalTokens = estimateTokens(messages)
  const hasImages = messages.some(m => m.type === 'user_image')

  return {
    tokenCount: totalTokens,
    hasImages,
    hasFileRefs: messages.some(m => m.fileRefs?.length > 0),
    estimatedComplexity: totalTokens > 50_000 ? 'complex'
      : totalTokens > 10_000 ? 'moderate' : 'simple',
    suggestedEffort: inferEffort(totalTokens, hasImages),
  }
}