Portal by Spotify로 Claude Code 토큰 사용량 90% 줄이기

Who Should Read

Claude Code 토큰 비용이 부담돼 단순 읽기·보일러플레이트 작업을 싼 모델로 넘기고 싶은 개발자

Core Mechanics

• 일은 생각보다 I/O가 많다
  • 파일 다섯 개를 읽고 메서드 하나를 답하거나, 옆 테스트 스무 개와 똑같은 패턴의 테스트를 만드는 데 토큰이 많이 든다.
  • 저자는 이런 작업에 추론은 거의 없는데 비싼 frontier 모델이 처리한다고 본다.
• 모드 두 개로 일을 나눴다
  • bulk-reader는 여러 큰 파일을 읽고 질문에 불릿으로 답한다.
  • code-writer는 스펙과 참조 파일을 받아 기존 패턴에 맞춘 코드만 출력한다.
  • 둘 다 예시에서는 Gemini 2.5 Flash, temperature 0.2를 쓴다.
• hook이 비싼 읽기를 강제로 막는다
  • CLAUDE.md에 라우팅 규칙을 적는 방식은 권고일 뿐이라 Claude가 무시할 수 있었다.
  • shunt 플러그인은 Read 호출 전에 훅을 걸어 350줄(기본값) 초과 파일 읽기를 막고 /bulk-reader 스킬로 돌린다.
  • 부분 읽기와 파이프 명령(cat file | grep)은 통과시킨다.
• 스크립트와 스킬이 호출을 감싼다
  • bulk-read와 code-write 두 bash 스크립트가 Portal CLI 호출, 에러 처리, 토큰 사용량 출력을 맡는다.
  • code-write는 생성 코드를 바로 디스크에 쓰므로 Claude가 그 코드를 보지 않는다.
  • 참조 파일이 필수다. 없으면 프로젝트에 안 맞는 코드가 나온다.

Community Reactions

• 정확도 수치가 없다는 지적
  • 정답률이나 작업 성공률 언급이 없고 크기만 보고 라우팅한다는 의견이 있었다.
  • DeepSWE 같은 벤치마크로 돌려 보라는 의견도 있었다.
  • 입력 토큰 90% 절감이 전체 토큰 90% 절감은 아니며 출력이 훨씬 비싸다는 의견도 있었다.
• 내 세션으로 측정하니 5~7%였다는 경험
  • 전체 LLM 요청·응답 데이터로 계산하니 토큰 절감이 약 5~7%로 추정됐다는 경험이다.
  • 주로 Opus 4.8을 쓰는데 고유 읽기 중 bulk-read 대상은 5.9%뿐이었다고 한다.
  • 읽기의 58%는 이미 부분 읽기였다고 한다.
• 계획 단계에서 이미 파일을 읽는다는 반론
  • 큰 모델이 플랜 모드에서 이미 관련 파일을 읽는다는 의견이다.
  • 작은 모델에 일을 나누려면 큰 모델이 분배와 리뷰까지 해야 해서 실제로 절약되는지 의문이라고 한다.
• 클라우드 없이 하는 대안들
  • 원격 호출 대신 로컬 서브에이전트, MCP 서버, 도구로 처리하면 되지 않느냐는 질문이 있었다.
  • 클라우드 의존 없는 Cursor용 shunt를 만들어 공유한 댓글이 있었다.
  • 소스 뼈대를 먼저 읽어 색인처럼 쓰는 treesitter-index도 소개됐다.

How to Apply

• 오늘 내 세션의 큰 읽기 비율 재보기
  • 최근 Claude Code 세션 로그에서 350줄 넘는 전체 파일 Read가 몇 건인지 센다.
  • 부분 읽기 비율도 같이 센다.
  • 대상이 적으면 도입 효과가 작다는 신호다.
• shunt 설치해 다중 파일 질문 시험
  • claude plugin marketplace add spotify/portal-ai-plugins 후 portal과 shunt를 설치한다.
  • 새 세션에서 /portal:setup을 실행한다.
  • 여러 파일에 걸친 질문을 하고 토큰을 비교한다.
• SHUNT_MIN_LINES 임계값 조정
  • .claude/settings.json의 env에 SHUNT_MIN_LINES를 넣는다.
  • 지연이 거슬리면 500처럼 올려서 작은 파일 위임을 줄인다.
• 위임 범위를 읽기·보일러플레이트로 제한
  • 디버깅, 아키텍처 결정, 안전이 중요한 코드는 위임하지 않는다.
  • 편집이 필요하면 offset/limit으로 해당 구간만 직접 읽게 한다.

Try It

# 원문 방법의 간이 버전: Portal 없이 Claude Code에 붙여넣어 큰 파일 읽기를 서브에이전트에 위임하는 프롬프트

다음 규칙을 이번 세션에서 따라 줘.
- 350줄이 넘는 파일 전체를 직접 Read하지 말고, 서브에이전트에게 읽혀서 요약만 받아.
- 서브에이전트 지시: "정확한 이름·타입·줄 번호로 시작하는 불릿으로만 답해. 인사와 서론은 쓰지 마. 묻지 않은 건 생략해."
- 편집이 필요하면 해당 구간만 offset/limit으로 직접 읽어.
- 디버깅과 설계 판단은 위임하지 말고 네가 직접 해.

질문: {{질문}}
대상 파일: {{파일 경로들}}

이어서 해 볼 것: 같은 질문을 위임 없이 한 번 더 물어 토큰 사용량과 답변 품질을 비교해 봐.

Terminology

관련 논문

• Mercury 3: 규모를 키운 diffusion LLM, 초당 1,000토큰 이상

  Diffusion LLM을 40배 키웠더니 속도 4~8배, 품질은 속도 특화 모델 수준

• Timestral: Mistral의 시계열 파운데이션 모델

  209M 파라미터 시계열 모델이 3대 벤치마크 1위, CPU에서도 돌아간다

• DeepSeek V4.1 Flash 1017 (Max) 성능·속도·가격 분석

  DeepSeek V4.1 Flash 1017 Max는 지능 지수 45에 211 tok/s, 입력 $0.30

• LLM 프록시를 직접 안 돌리면 무슨 일이 벌어지는지 어떻게 아나

  자체 LLM 프록시를 세웠더니 키·모델·캐시 미스를 직접 볼 수 있다

• DeepSeek V4.1 Flash 1017: 싼 가격에 1M 컨텍스트를 주는 에이전트용 모델

  DeepSeek V4.1 Flash 1017은 입력 $0.05/M, 1M 컨텍스트의 에이전트용 모델

• DeepSeek-V4.1-Flash-1017 공개: 더 짧게 생각하고 더 빠르게 일하는 에이전트용 모델

  DeepSeek V4.1 Flash 마이너 업데이트로 코딩·에이전트 벤치 점수↑, 실행 시간·출력 길이↓

• Llmspeed: 로컬 LLM 속도를 하드웨어 구매 전에 체감해 보는 시뮬레이터

  GPU·모델을 고르면 로컬 LLM 속도를 미리 체감하게 해 주는 시뮬레이터

Related Resources

• https://engineering.atspotify.com/2026/9/portal-by-spotify-cut-my-claude-code-token-usage-by-90
• https://github.com/JuliusBrussee/caveman/
• https://github.com/ninjaxtools/treesitter-index
• https://github.com/dominicletz/cursor-shunt/