Claude Code 토큰 90% 절감한 모델 라우팅 전략 — 삽질 없이 적용하는 법

들어가며 — AI 코딩 비용, 진짜 문제는 어디에 있나

요즘 팀 단위로 Claude Code나 Cursor를 도입해보신 분들이라면 공감하실 텐데요. 좌석 라이선스 비용보다 토큰 비용이 훨씬 무섭습니다. 2028년이면 AI 코딩 비용이 평균 개발자 연봉을 넘어설 거라는 전망도 나오고 있어요.

문제는 이 토큰의 상당 부분이 **"생각"이 아니라 "I/O"**라는 점입니다. 예를 들어볼게요.

• 메서드 하나 설명 들으려고 파일 5개를 통째로 읽기
• 옆에 있는 테스트 파일 20개랑 똑같은 패턴으로 새 테스트 파일 하나 생성하기
• 회의 끝나고 문서 업데이트하기

이런 작업에 수천 토큰이 날아가는데, 실제 추론(reasoning)은 거의 없어요. 그런데 이걸 다 최전선(frontier) 모델에 태우고 있는 겁니다. 과하게 좋은 모델을 단순 반복 작업에 쓰고 있는 셈이죠.

이 글에서는 고성능 모델은 진짜 추론이 필요한 곳에만 쓰고, 잡일은 저렴한 워커 모델로 위임하는 모델 라우팅 패턴을 다뤄요. 근거자료는 Spotify Engineering 블로그입니다.

국내 SI 환경에서는 특히 이 부분이 중요해요. 프로젝트마다 레거시 코드베이스가 다르고, 매번 컨텍스트를 새로 읽어야 하는 상황이 많거든요. 여기서 토큰이 녹아내리는 걸 막지 못하면 월말 청구서 보고 놀라게 됩니다 😅

핵심 구조 — 두 개의 모드로 라우팅하기

핵심 아이디어는 단순해요. 에페메랄 런타임(ephemeral runtime) 위에서 돌아가는 선언적 에이전트(declarative agent) 두 개를 만들고, 무거운 I/O와 보일러플레이트 작업을 위임합니다.

워커 모델 설정 (예: Gemini 2.5 Flash)

# Mode 1: 대용량 파일 읽기 전용 워커
name: bulk-reader
description: 코드 분석용 대용량 파일 리더 - Claude Code의 I/O를 위임받음
instructions: |
  당신은 정밀한 코드 분석가입니다. 제공된 파일을 읽고 질문에 간결하게 답하세요.
  구조화된 불릿만 출력하세요. 인사말, 서술, 서두는 금지합니다.
  각 불릿은 정확한 이름, 타입, 라인 번호로 시작하세요.
  세부사항은 중첩 불릿을 사용하세요. 요청하지 않은 내용은 생략하세요.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

# Mode 2: 보일러플레이트 코드 생성 워커
name: code-writer
description: 보일러플레이트 코드 생성기 - Claude Code의 출력 부하 작업을 위임받음
instructions: |
  당신은 스펙과 참조 파일을 기반으로 코드 파일을 생성합니다.
  기존 패턴, 컨벤션, 네이밍, 스타일을 정확히 따르세요.
  코드만 출력하세요. 설명이나 마크다운 펜스는 요청받지 않는 한 금지합니다.
  스펙이 모호하면 참조 코드의 패턴에 맞게 합리적으로 선택하세요.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

"코드만 출력하세요" 지시가 은근히 중요해요. 이게 없으면 모델이 마크다운 펜스랑 설명 문장을 다 붙여서 Claude가 그걸 다시 파싱해야 하는 낭비가 생깁니다.

라우팅 레이어 (3단계)

1. Hooks 레이어 — PreToolUse 훅으로 모든 도구 호출 전에 개입합니다. 파일이 임계값(기본 350줄)을 넘으면 읽기를 차단하고 워커로 리다이렉트하죠.
2. Scripts 레이어 — Portal CLI를 감싼 bash 스크립트가 요청 구성, 에러 언랩핑, 토큰 사용량 stderr 보고까지 처리합니다.
3. Skills 레이어 — Claude에게 언제 어떻게 스크립트를 호출할지 알려주는 마크다운 스킬 파일입니다.

이 레이어 구조의 장점은 **우아하게 성능이 저하된다(degrades gracefully)**는 점이에요. Claude가 스킬 설명을 안 읽어도 훅이 비싼 읽기를 차단합니다.

# 단일 파일 대신 여러 파일을 한 번에 위임
bulk-read --question "이 서비스가 하는 일은?" \
  --paths src/Service.java src/Handler.java

# 참조 파일 기반으로 테스트 코드 생성
code-write --spec "UserService 테스트 작성" \
  --reference tests/OrderTest.java \
  --target tests/UserTest.java

벤치마크 결과

Java 모노레포에서 4개 시나리오로 테스트했을 때, 평균 약 90% 토큰 절감이 나왔습니다. 특히 code-write 시나리오는 토큰 측정 자체가 어려운데, 위임 없이는 Claude가 참조 파일을 읽고 출력 토큰으로 코드를 생성해야 하지만, 위임 후에는 코드가 디스크로 바로 들어가서 Claude가 아예 못 보기 때문이에요.

주의사항 — 위임하면 안 되는 것들

이 패턴이 만능은 아닙니다. 실무에서 반드시 지켜야 할 경계가 있어요.

❌ 편집(Editing)은 위임 불가

워커 모델의 요약에는 신뢰할 만한 라인 번호가 없어요. Claude가 분석 결과를 바탕으로 편집해야 한다면, 해당 섹션은 직접 읽어야 합니다. 그래서 훅이 offset/limit을 통한 타겟 읽기는 허용하도록 설계되어 있어요.

❌ 추론(Reasoning)은 위임 불가

테스트 중에 워커 모델이 표면적 패턴은 잘 찾았지만, 미묘한 스레드 안전성(thread-safety) 버그는 놓쳤습니다. Claude는 정확한 컨텍스트를 주니까 몇 초 만에 찾아냈죠. 그래서 라우팅 규칙에서 디버깅, 아키텍처 결정, 안전 크리티컬 코드는 명시적으로 제외합니다.

⚠️ 지연 시간(Latency) 누적

위임 한 번은 네트워크 왕복입니다. Claude Code → Portal 백엔드 → 워커 모델 → 되돌아오기. 보통 10~30초 걸리고, 단일 호출은 30초에서 캡이 걸려요. 큰 읽기에는 괜찮지만 작은 읽기에는 오히려 역효과입니다. 라인 임계값이 존재하는 이유가 바로 이거예요.

📊 비용 vs. 이득 판단 기준

🇰🇷 한국 개발 생태계에서의 적용 맥락

국내 SI/외주 환경에서는 프로젝트별 코드 컨벤션이 제각각이라 워커 모델의 참조 파일 매칭이 특히 중요합니다. code-write를 쓸 때 반드시 해당 프로젝트의 기존 파일을 reference로 지정하세요. 안 그러면 프로젝트에 안 맞는 코드가 나옵니다.

또한 사내망 환경이라면 Portal 인스턴스를 자체 호스팅해야 하고, 외부 모델 API 호출이 막혀 있을 수 있으니 로컬 LLM(Ollama 등)을 워커로 쓰는 구성도 고려해보세요. Gemini Flash 대신 Qwen이나 Llama 계열을 붙이면 비용은 0에 가까워집니다.

AI 코딩 도구의 인프라 레벨 이해가 필요하다면 VS Code에서 Google Cloud ML 개발 끝내기 Workbench 확장 프로그램 완벽 가이드도 함께 보시면 좋아요. 개발 환경 자체를 클라우드로 올리는 관점에서 연결되는 내용입니다.

마무리 — 라우팅은 설정 문제지, 인프라 문제가 아니다

이 패턴의 진짜 가치는 모델 라우팅을 시스템 엔지니어링 문제에서 설정 문제로 바꿔놓는다는 점이에요. 인프라를 짓지 않습니다. 원하는 걸 서술하고 이름만 붙이면 돼요.

모드의 재사용성/공유성/조합성을 정리하면:

• 재사용 가능 — 같은 bulk-reader와 code-writer 모드가 모든 프로젝트에서 동작
• 공유 가능 — 팀 전체가 같은 모드를 씀
• 조합 가능 — doc-writer, reviewer, translator 모드 추가 가능
• 결정과 워커의 분리 — 플러그인은 언제 위임할지, 모드는 어떻게 응답할지 결정

다음 단계 학습 방향

1. 모델 라우팅 패턴을 팀 컨벤션으로 문서화하세요. 어떤 작업을 어디로 보낼지 명시적 규칙이 있어야 일관성이 생깁니다.
2. 토큰 사용량 계측을 먼저 하세요. 절감 효과를 측정 못 하면 최적화도 없습니다.
3. 워커 모델 교체 실험을 해보세요. Gemini Flash → Claude Haiku → 로컬 Llama 순으로 비용/품질 트레이드오프를 비교하면 우리 팀에 맞는 지점을 찾을 수 있어요.

결국 이 이야기는 **"GPU 위에서 벌어지는 추론 최적화"**와 같은 맥락입니다. NVIDIA, MLPerf Inference v6.0에서 291회 우승…Blackwell Ultra GPU로 추론 성능 독주 같은 하드웨어 레벨 최적화 뉴스와 함께 보면, 소프트웨어 라우팅과 하드웨어 성능이 어떻게 맞물리는지 감이 잡힐 거예요.

토큰 아끼는 건 결국 **"어디에 어떤 모델을 붙일지"**의 문제입니다. 인프라 팀 없이도 오늘 당장 시작할 수 있어요 🚀