ULTRAPLAN: 30분 원격 계획

ULTRAPLAN은 복잡한 계획 작업을 클라우드의 Opus 모델에 위임하여 최대 30분간 실행하는 원격 계획 시스템입니다. 사용자가 /ultraplan 슬래시 커맨드를 입력하거나 특정 키워드 패턴이 감지되면 자동으로 트리거됩니다.

ULTRAPLAN은 4단계 파이프라인으로 동작합니다:

• 1단계 — 트리거 감지: 슬래시 커맨드 또는 키워드 스캐너가 계획 요청을 식별
• 2단계 — CCR 세션 실행: 클라우드에서 Opus 원격 세션을 시작
• 3단계 — 롱폴: 커서 기반 폴링으로 진행 상황을 모니터링
• 4단계 — 플랜 전달: 완성된 계획을 로컬 세션에 전달

ULTRAPLAN은 명시적 /ultraplan 커맨드 외에도, 사용자 입력의 자연어 패턴을 분석하여 계획 요청을 자동으로 감지합니다. 다만, 오탐을 방지하기 위해 여러 필터가 적용됩니다.

// ultraplan/trigger.ts — 키워드 스캐너 & 필터
function shouldTriggerUltraplan(input: string): boolean {
  // 필터 1: 인용문 내부의 텍스트는 무시
  const unquoted = stripQuotedStrings(input)

  // 필터 2: 파일 경로 패턴 제외
  if (containsFilePath(unquoted)) return false

  // 필터 3: 슬래시 커맨드 패턴 제외 (/ultraplan 자체는 별도 처리)
  if (isSlashCommand(unquoted)) return false

  // 필터 4: 물음표로 끝나는 단순 질문 제외
  if (isSimpleQuestion(unquoted)) return false

  // 키워드 매칭
  return PLAN_KEYWORDS.some(kw => unquoted.includes(kw))
}

const PLAN_KEYWORDS = [
  'plan', 'architect', 'design',
  'strategy', 'roadmap', 'blueprint',
]

ULTRAPLAN이 트리거되면 "detached" 패턴으로 원격 세션을 실행합니다. 로컬 클라이언트는 세션 시작 후 즉시 제어를 반환받고, 원격 세션은 독립적으로 실행됩니다.

// ultraplan/session.ts — "detached" 패턴 실행
let ultraplanLaunching = false  // 동기 플래그: 중복 실행 방지

async function launchUltraplan(prompt: string): Promise<UltraplanSession> {
  // 동기 가드: 이미 실행 중이면 중복 방지
  if (ultraplanLaunching) {
    throw new Error('ULTRAPLAN session already launching')
  }
  ultraplanLaunching = true

  try {
    // 1. 원격 CCR 세션 생성 (Opus 모델 지정)
    const session = await createRemoteSession({
      model: 'opus',
      maxDuration: 30 * 60 * 1000,  // 30분
      prompt: buildUltraplanPrompt(prompt),
    })

    // 2. 폴링 엔진 시작
    startPolling(session.id)

    return session
  } finally {
    ultraplanLaunching = false
  }
}

ultraplanLaunching 동기 플래그

ultraplanLaunching 플래그는 ULTRAPLAN 세션의 중복 실행을 방지하는 동기식 가드입니다. 비동기 락이 아닌 단순 boolean을 사용하는 이유는, JavaScript의 단일 스레드 특성상 동기 코드 실행 중에는 다른 비동기 콜백이 개입할 수 없기 때문입니다.

원격 세션이 시작되면 로컬 클라이언트는 커서 기반 폴링으로 진행 상황을 모니터링합니다. 각 폴 요청은 마지막으로 받은 커서 위치 이후의 새로운 이벤트만 반환합니다.

// ultraplan/poller.ts — 커서 기반 폴링 엔진
async function pollSession(sessionId: string): Promise<void> {
  let cursor: string | undefined

  while (true) {
    const response = await fetchEvents(sessionId, { cursor })

    for (const event of response.events) {
      // ExitPlanModeScanner: 완료 신호 감지
      if (isExitSignal(event)) {
        await deliverPlan(sessionId)
        return
      }
      // 중간 진행 상황 UI 업데이트
      updateProgressUI(event)
    }

    // 커서 전진 — 다음 폴은 여기서부터
    cursor = response.nextCursor

    // 백오프: 이벤트가 없으면 대기 시간 증가
    await sleep(response.events.length > 0 ? 1000 : 3000)
  }
}

ExitPlanModeScanner

ExitPlanModeScanner는 원격 세션의 이벤트 스트림에서 계획 완료 신호를 감지하는 스캐너입니다. 원격 Opus가 계획 작성을 완료하고 특정 마커를 출력하면, 이 스캐너가 이를 포착하여 폴링 루프를 종료하고 계획 전달 단계로 전환합니다.

완성된 계획은 두 가지 경로 중 하나로 로컬 세션에 전달됩니다:

경로 1: 원격 실행 (Remote Execution)

계획이 단순한 텍스트가 아니라 실행 가능한 단계들을 포함하는 경우, 원격 세션이 직접 각 단계를 실행하고 결과를 로컬에 전달합니다.

// ultraplan/delivery.ts — 원격 실행 경로
async function deliverViaRemoteExecution(
  session: UltraplanSession
): Promise<PlanResult> {
  const plan = await fetchCompletedPlan(session.id)

  return {
    type: 'remote-execution',
    steps: plan.steps,
    artifacts: plan.artifacts,
    summary: plan.summary,
  }
}

경로 2: 텔레포트 (Teleport)

계획이 로컬 환경에서 실행되어야 하는 경우, 원격 세션의 전체 컨텍스트가 로컬 세션으로 "텔레포트"됩니다. 이는 원격에서 구축한 이해를 로컬 Claude에 이식하는 것과 같습니다.

// ultraplan/delivery.ts — 텔레포트 경로
async function deliverViaTeleport(
  session: UltraplanSession
): Promise<PlanResult> {
  const context = await fetchSessionContext(session.id)

  // 원격 컨텍스트를 로컬 메시지 히스토리에 주입
  injectIntoLocalHistory(context.messages)

  return {
    type: 'teleport',
    injectedMessages: context.messages.length,
    summary: context.summary,
  }
}

ULTRAPLAN 세션이 완료되거나 타임아웃되면, 원격 리소스를 정리하고 로컬 상태를 복원해야 합니다.

// 세션 정리 — 완료/타임아웃/에러 모든 경우 처리
async function cleanupSession(sessionId: string): Promise<void> {
  // 1. 원격 세션 종료 요청
  await terminateRemoteSession(sessionId)

  // 2. 폴링 루프 중단
  stopPolling(sessionId)

  // 3. 로컬 진행 상황 UI 제거
  clearProgressUI()

  // 4. 비용 추적에 원격 세션 토큰 사용량 합산
  const usage = await fetchSessionUsage(sessionId)
  addToLocalCostTracker(usage)

  // 5. 분석 이벤트 기록
  logEvent('ultraplan_completed', {
    sessionId,
    duration: usage.durationMs,
    tokensUsed: usage.totalTokens,
  })
}