Hook (도입부)

지난달, 스프린트 중간에 제 Claude 구독 서비스가 휴가를 떠나기로 결정했습니다. 배포해야 할 기능이 있는 상황에서 3일 동안 "Service Unavailable (서비스를 사용할 수 없음)" 상태가 지속되었습니다. 그때 결심했습니다. 내 AI 스택에 더 이상 단일 장애점 (Single Point of Failure)은 없어야 한다고 말이죠.

Background: 왜 Claude Code만으로는 충분하지 않은가

Claude Code는 훌륭합니다. 컨텍스트 윈도우 (Context Window), 추론 (Reasoning), 도구 사용 (Tool Use) 능력까지 말이죠. 하지만 이는 자체적인 제한이 있는 구독 서비스입니다. 속도 제한 (Rate Caps), 가용 시간대, 그리고 현재 필요한 것을 사용자의 플랜이 충족하지 못하는 짜증 나는 순간들이 존재합니다.

MiniMax는 확실한 대안을 제공하지만, 그들의 API는 다르게 동작합니다. 엔드포인트 (Endpoints)가 다르고, 파라미터 (Parameters)가 다르며, 특이한 점들도 다릅니다. 이들 사이를 수동으로 전환하는 것은 워크플로우를 망치는 주범입니다.

저는 두 서비스 앞에 위치하여, 제가 무엇을 하고 있는지에 따라 지능적으로 경로를 지정(Route)하고, 무언가 고장 났을 때 자동으로 장애 조치 (Failover)를 수행할 수 있는 프록시 (Proxy)가 필요했습니다.

What I Built: 네 가지 라우팅 모드

이 라우터는 네 가지 별개의 모드로 작동합니다:

1. Forced Claude (Claude 강제) - 모든 요청이 Claude로 전송됩니다. 최대의 추론 능력이 필요할 때 사용합니다.
2. Forced MiniMax (MiniMax 강제) - 모든 요청이 MiniMax로 전송됩니다. 더 저렴한 작업이나 대량 처리 (Bulk Processing)에 적합합니다.
3. Automatic (자동) - 프록시가 작업 복잡도에 따라 결정합니다. 단순한 쿼리는 MiniMax로, 복잡한 쿼리는 Claude로 보냅니다.
4. Interactive (Smart Mode) (대화형 - 스마트 모드) - 프록시가 실시간으로 작업을 분류하고 그에 따라 경로를 지정하며, 수동 오버라이드 (Manual Override)도 가능합니다.

대화형 모드는 매우 흥미로운 부분입니다. 저는 다음과 같이 구분하는 경량 분류기 (Classifier)를 구축했습니다:

• T0/T1 작업: 빠른 편집, 단일 파일 변경, 문서 업데이트
• T2 작업: 다중 파일 리팩터링 (Refactors), 아키텍처 결정, 복잡한 디버깅 (Debugging)

Architecture: 세 가지 서비스 + 하나의 프록시

시스템은 다음과 같이 실행됩니다:

ai-router-proxy.py    # HTTP 프록시 (port 8080)
ai-router-switcher.sh # 서비스 스위처 (Service switcher) 스크립트
ai-health-checker.sh  # 상태 모니터링 (Health monitoring) 데몬

각각은 다음과 같이 systemd 서비스로 실행됩니다:

~/.config/systemd/user/ai-router-proxy.service
~/.config/systemd/user/ai-router-switcher.service
~/.config/user/ai-router-health-checker.service

프록시 (Proxy)는 로컬에서 요청을 대기하며, 활성화된 백엔드(Backend)로 요청을 전달하고 API 형식 간의 변환을 처리합니다.

Smart Mode: 작업 분류 방식

라우팅 로직은 들어오는 요청을 검사하여 복잡도를 결정합니다:

• 요청 길이 및 구조
• 코드 패턴의 존재 여부 (import, 함수 정의, 클래스 선언 등)
• 요청 내의 명시적인 모드 힌트
• 토큰 수 (Token count) 추정치

컨텍스트가 최소화된 단순한 프롬프트 (Prompt)는 MiniMax로 전송됩니다. 전체 리팩토링 (Refactor)이나 복잡한 추론 (Reasoning) 작업과 유사한 모든 것은 Claude로 라우팅됩니다.

Triple Defense: 서비스 회복 탄력성 (Resilience)

하나의 서비스가 실패하더라도 워크플로우가 중단되어서는 안 됩니다. 회복 탄력성 스택은 다음과 같습니다:

1. systemd 재시작 정책 (restart policies) - 각 서비스는 실패 시 지수 백오프 (backoff)를 적용하여 자동으로 재시작됩니다.
2. cron 상태 확인 (health checks) - 5분마다 스크립트가 두 백엔드 모두를 확인하고 필요 시 전환합니다.
3. 요청 전 훅 (pre-request hooks) - 프록시는 각 요청 전에 백엔드의 상태를 확인합니다.

Claude가 다운되면 시스템은 5분 이내 (cron 간격) 또는 즉시 (hook) 이를 감지합니다. MiniMax가 실패해도 마찬가지입니다. 당신은 작업을 계속할 수 있습니다.

핵심 프록시 로직

다음은 ai-router-proxy.py의 핵심 라우팅 함수입니다:

def handle_request(req_data, mode):
    if mode == "claude":
        return forward(req_data, CLAUDE_ENDPOINT)
...

네 가지 모드를 처리하는 단 10줄의 코드이며, 복잡도 분류기 (complexity classifier)가 진정한 지능의 핵심입니다.

대안들과의 비교

실제 사용 사례 (Real-World Use Cases)

1. 문서 작성 (Documentation writing) - 대부분은 MiniMax가 처리합니다. 아키텍처 결정 사항을 설명해야 할 때는 Claude가 업무를 넘겨받습니다.
2. 버그 탐색 (Bug hunting) - 자동 모드 (Automatic mode)가 복잡성을 감지하고, 고난도 작업을 위해 Claude로 라우팅합니다.
3. 코드 리뷰 (Code review) - 대화형 모드 (Interactive mode)가 리뷰 패턴을 식별하고 그에 따라 라우팅합니다.
4. 대량 리팩토링 (Bulk refactoring) - 속도만 필요한 반복적인 변경 작업에는 MiniMax 모드를 강제합니다.

성능 및 결과 (Performance and Results)

한 달간 매일 사용한 결과:

• 백엔드 장애 시 전환 시간 (Switchover time): 10초 미만
• 자동 모드에서의 라우팅 정확도 (Routing accuracy): 약 85% (수동 오버라이드 기준)
• 단순 작업에 대한 MiniMax 사용으로 인한 비용 절감: Claude만 사용할 때보다 약 40%
• 백엔드 문제로 인한 워크플로 중단 횟수: 31일째 중단 없음

배운 점 (What I Learned)

회복 탄력성이 있는 AI 프록시 (AI proxy)를 구축하며 세 가지를 배웠습니다:

1. 장애 조치 (Failover)는 쉽지만, 복구 (Failback)는 어렵다 - 서비스가 다시 정상화되었음을 감지하고 다시 전환하는 데에는 세심한 상태 관리 (State management)가 필요합니다.
2. 분류 (Classification)가 가장 어려운 부분이다 - 라우팅 로직 자체는 간단합니다. 언제 라우팅할지를 아는 것이 실제 문제입니다.
3. 로컬 프록시 (Local proxies)는 과소평가되어 있다 - 단순한 HTTP 프록시가 복잡한 서비스 메시 (Service mesh)가 필요할 것이라고 생각했던 문제를 해결했습니다.

링크 및 참여 유도 (Links and Call to Action)

전체 프로젝트는 오픈 소스로 공개되어 있습니다:

• 저장소 (Repository): https://github.com/eroslifestyle/ai-router-switch
• 문서 (Documentation): https://eroslifestyle.github.io/ai-router-switch/
• 배너/에셋 (Banner/Assets): https://github.com/eroslifestyle/ai-router-switch/tree/main/assets
• 토론 (Discussion): https://github.com/eroslifestyle/ai-router-switch/discussions/2

AI 서비스의 다운타임 (downtime)으로 인해 피해를 입었거나, 성능을 희생하지 않으면서 비용을 최적화하고 싶다면, 저장소 (repo)를 클론 (clone)하여 설치 프로그램을 실행하세요. 설정 스크립트가 systemd 유닛 (units), 프록시 설정 (proxy configuration), 그리고 상태 확인 (health checks)을 처리합니다.

질문, 기여, 그리고 기능 요청은 토론 (discussions)에서 언제든 환영합니다.