Claude Code 멀티모델 오케스트레이션

Claude Code에서 외부 에이전트(Gemini, GPT 등)를 서브에이전트로 활용하는 구성 메모.

## 동기

Claude Code 서브에이전트는 컨텍스트 파이프가 네이티브로 연결되어 편리하지만, 모델이 Claude로 고정됨.

역할별 최적 모델이 다름:
- 백엔드 로직 설계 → Claude Opus, GPT 5.5
- 프론트 디자인/UI → Gemini
- 코드리뷰 → GPT (삐딱하게 트집잡는 특성이 오히려 버그 잡는 데 유리)

## 구조

```
Claude Code (메인 오케스트레이터)
    ↓ HTTP 툴 호출
Cloudflare Workers (Agents SDK + AI Gateway)
    ├─ AI Gateway → Gemini (프론트 디자인)
    ├─ AI Gateway → GPT 5.5 (코드리뷰 / 복잡한 설계)
    └─ 결과 반환
```

## 콜백 문제 해결

외부 에이전트 결과를 Claude Code 컨텍스트로 다시 주입하는 게 핵심 난관.

폴링이나 블로킹 대기는 구조적으로 어색함. **Claude Managed Agent 웹훅**으로 해결 가능.

- 외부 시스템 → `routines.fire` 엔드포인트로 Claude Code 루틴 트리거
- Claude Code 세션 상태 변화(완료, 유휴 등) → 웹훅으로 외부 시스템에 콜백
- Codex PR 리뷰와 동일한 웹훅 패턴

```
Claude Code 루틴 시작
    ↓
Workers에 Gemini 태스크 트리거
    ↓ (작업 완료)
Workers → routines.fire 콜백
    ↓
결과물 컨텍스트 주입 → Claude Code 계속 진행
```

## Workers AI Gateway 구성

AI Gateway가 멀티 프로바이더(Anthropic, Google Gemini, OpenAI)를 단일 엔드포인트로 라우팅.
스트리밍 버퍼링, 토큰 비용 추적, 레이트리밋, 캐싱 포함.

Agents SDK에서 provider 스왑이 가능하므로 모델 교체가 용이함.

## 참고

- [Claude Managed Agent 웹훅 공식 문서](https://platform.claude.com/docs/en/managed-agents/webhooks)
- [Claude Code Routines 가이드](https://code.claude.com/docs/en/fast-mode)
- [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/)
- [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/)