ULTRAPLAN과 비용 분석

ULTRAPLAN이란?

ULTRAPLAN은 소스 코드에서 확인된 복잡한 다단계 작업을 위한 고급 계획 기능 입니다. 원격으로 Opus 4.6 모델 을 사용하여 계획을 수립하며, 3초 간격 폴링 과 브라우저 승인 흐름 을 포함합니다. 빌드 플래그 ULTRAPLAN으로 게이팅되어 있으며, 피처 게이트 tengu_ultraplan_model로 점진적 롤아웃됩니다.

일반 실행:
  요청 → 즉시 실행 → 결과

ULTRAPLAN 실행:
  요청 → [계획 수립 단계]
              │
              ├── 요구사항 분석
              ├── 단계 분해
              ├── 의존성 파악
              ├── 위험 요소 식별
              └── 실행 계획 확정
              │
          [실행 단계]
              │
              ├── 단계 1 실행 → 검증
              ├── 단계 2 실행 → 검증
              └── 단계 N 실행 → 최종 검증

계획 수립과 실행 분리

ULTRAPLAN의 핵심 원칙은 **“먼저 생각하고, 그 다음 행동한다”**입니다.

단계	활동	결과물
계획 수립	요구사항 분석, 전략 결정	실행 계획 문서
검토	사용자 승인 또는 자동 진행	승인된 계획
실행	단계별 구현	실제 코드/변경
검증	각 단계 완료 확인	검증 보고서

// ULTRAPLAN 활성화 예시 (추정 API)
for await (const message of query({
  prompt: '결제 시스템을 마이크로서비스로 분리해 주세요',
  options: {
    ultraplan: true,
    planReviewMode: 'auto',  // 또는 'manual'
    maxPlanSteps: 20
  }
})) {
  if (message.type === 'plan') {
    console.log('계획 수립 완료:', message.plan.steps.length, '단계');
  }
}

비용 분석 시스템

Claude Code는 모든 세션의 토큰 사용량과 비용을 자동으로 추적합니다.

// result 메시지 전체 구조
{
  "type": "result",
  "subtype": "success",
  "session_id": "abc-123",
  "cost_usd": 0.1284,
  "duration_ms": 28500,
  "duration_api_ms": 23100,
  "is_error": false,
  "num_turns": 12,
  "usage": {
    "input_tokens": 45200,
    "output_tokens": 8900,
    "cache_read_input_tokens": 38000,
    "cache_creation_input_tokens": 5200
  }
}

캐시 히트율 계산:

캐시 히트율 = cache_read_input_tokens / input_tokens × 100
예시: 38000 / 45200 × 100 = 84.1%

캐시 히트율이 높을수록 비용이 크게 절감됩니다.

get_context_usage 세분화 분석

const usage = await sendControlRequest({
  type: 'control',
  subtype: 'get_context_usage'
});

// 상세 분류 응답
{
  "total_tokens": 200000,      // 최대 컨텍스트 윈도우
  "used_tokens": 67430,        // 현재 사용량
  "available_tokens": 132570,  // 잔여 용량
  "usage_percent": 33.7,       // 사용률 (%)
  "breakdown": {
    "system_prompt": 12400,    // 시스템 프롬프트
    "tool_definitions": 8200,  // 도구 정의
    "conversation": 38500,     // 대화 히스토리
    "tool_results": 6100,      // 도구 실행 결과
    "pending": 2230            // 처리 중인 내용
  }
}

비용 최적화 전략

전략	구현 방법	절감 효과
시스템 프롬프트 캐싱	고정 시스템 프롬프트 사용	입력 비용 최대 90%
컨텍스트 압축	/compact 명령어 주기적 실행	20-40%
모델 다운그레이드	단순 작업에 Haiku 활용	95% (Opus 대비)
배치 처리	여러 파일을 한 번에 처리	오버헤드 감소
결과 재사용	동일 분석 반복 요청 방지	중복 비용 제거

비용 데이터를 지속적으로 수집하면 팀의 AI 사용 패턴을 파악하고 예산을 효율적으로 관리할 수 있습니다.