Portal by Spotify cut my Claude Code token usage by 90%

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Spotify의 Portal과 shunt 플러그인은 대용량 읽기와 반복 코드 생성을 작업 모델에 위임하며, Java 모노레포 실험에서 대량 읽기에 따른 Claude 토큰 소비를 평균 약 90% 줄였다.

📌 핵심 요약

• 글은 파일 읽기와 반복 코드 생성 같은 입출력 작업에 고성능 모델의 토큰을 쓰는 비용을 문제로 제시하고, 추론이 필요한 작업과 분리할 것을 제안한다.
• Portal의 AiKA Modes로 구성한 bulk-reader와 code-writer는 예시에서 Gemini 2.5 Flash를 사용하며, 각각 파일 분석 요약과 기존 패턴에 맞춘 코드 생성을 담당한다.
• Claude Code용 shunt는 훅·스크립트·스킬을 결합해 위임을 실행하며, 기본 350줄을 초과하는 파일의 전체 읽기를 차단하되 특정 구간 읽기는 허용한다.
• Java 모노레포의 네 가지 시나리오에서 대량 읽기의 Claude 토큰 절감률은 평균 약 90%였으며, 코드 생성은 결과를 디스크에 직접 기록해 Claude 문맥에 넣지 않는다.
• 편집에 필요한 구간 확인과 복잡한 추론은 Claude에 남기며, 위임 응답은 통상 10~30초가 걸리고 Portal의 단일 호출 제한은 30초다.

🧩 주요 포인트

1. 입출력과 추론의 분리 → bulk-reader와 code-writer로 반복 작업을 넘겨 고성능 모델의 토큰 사용 범위를 줄임.
2. shunt의 훅과 기본 350줄 기준 → 위임 규칙을 강제하면서 특정 구간 읽기를 허용해 편집에 필요한 접근을 유지함.
3. 대량 읽기 평균 약 90% 절감과 10~30초 지연 → 효과를 작업 유형별로 판단해야 하며, 복잡한 추론과 작은 읽기는 위임 대상에서 구분할 필요가 있음.

🧠 상세 정리

1. 추론보다 입출력에 소모되는 토큰

글쓴이는 코딩 에이전트가 수행하는 상당수 작업을 깊은 사고보다 입출력에 가까운 활동으로 설명한다. 한 메서드에 관한 질문에 답하려고 여러 파일을 읽거나, 주변 테스트와 같은 패턴의 파일을 생성하거나, 회의 이후 문서를 갱신하는 사례가 여기에 해당한다. 이런 작업에서도 수천 개의 토큰이 소비되므로 좌석 라이선스보다 토큰 비용이 부담이라는 것이 문제 제기의 출발점이다. 글은 2028년까지 AI 코딩 비용이 평균 개발자 급여를 넘어설 것이라는 전망과, 엔지니어링 리더의 4분의 1이 개발자당 매월 200~500달러를 토큰에 지출한다는 수치를 인용한다. 이에 반복 작업은 더 저렴한 모델에 맡기고, 고성능 모델은 실제 추론이 필요한 문제에 집중시키는 방식을 제안한다.

2. AiKA Modes로 정의하는 두 작업 모델

Portal의 AiKA Modes는 지침, 모델, 온도 같은 매개변수와 MCP 도구를 지정해 일시적인 실행 환경에서 동작하는 선언형 에이전트다. Portal이 실행을 처리하므로 별도 인프라나 API 키, 상시 서버를 관리하지 않고 CLI 또는 API로 호출할 수 있으며, 공개 또는 비공개 설정도 가능하다. 예시의 bulk-reader와 code-writer는 모두 Gemini 2.5 Flash와 온도 0.2를 사용하지만, Portal 인스턴스에 구성된 다른 모델도 선택할 수 있다. bulk-reader는 제공된 파일에서 질문에 해당하는 내용만 간결한 구조화 항목으로 반환하도록 지시한다. code-writer는 참조 파일의 패턴과 명명법, 스타일을 따르며 코드만 출력하도록 설정해 Claude가 설명문이나 마크다운 구분자를 추가로 처리하는 부담을 줄인다.

3. 권고형 지침에서 훅 기반 강제로 전환

초기 구현은 CLAUDE.md에 라우팅 규칙을 적어 Claude가 스스로 Portal에 위임하도록 하는 방식이었다. 그러나 규칙을 무시할 수 있고 프로젝트마다 같은 지침을 복사해야 하는 문제가 있어, 현재 구현은 shunt라는 Claude Code 플러그인으로 바뀌었다. shunt는 Portal CLI의 액션 레지스트리를 통해 위임하며, AiKA 플러그인이 활성화된 Portal 인스턴스에서 작동한다. check-file-size 훅은 Read 호출 전에 파일 크기를 검사해 기본 350줄을 초과하는 전체 읽기를 차단하고 /bulk-reader 스킬 사용을 안내하지만, 특정 구간을 지정한 읽기는 허용한다. check-bash-read 훅은 큰 파일에 대한 cat, head, tail, less, more도 검사하되 파이프를 사용하는 명령은 통과시키며, 줄 수 기준은 SHUNT_MIN_LINES로 조정할 수 있다.

4. 스크립트와 스킬을 통한 위임 실행

두 개의 배시 스크립트는 Claude가 전달한 이름 있는 인수를 받아 요청 구성, Portal 액션 호출, 오류 처리와 표준 오류 스트림으로의 토큰 사용량 보고를 담당한다. bulk-read는 파일 경계를 XML 태그로 표시하고 질문과 함께 bulk-reader에 보내며, 후속 질문에서도 같은 파일을 다시 전달하는 단발 호출 방식으로 작동한다. 호출 내용은 서버에 저장되지 않고 원본 파일은 작업 모델에만 전달되므로, 다시 보낸 파일 전체가 Claude 문맥에 들어가지는 않는다. code-write는 작업 명세와 필수 참조 파일을 보내고 결과의 마크다운 구분자를 제거하며, 생성 코드를 디스크에 직접 기록할 수 있다. 모드는 이름의 대소문자를 구분하지 않고 개인·팀·공개 순으로 우선 해석되므로 개인화한 모드가 자동으로 선택된다. 두 스킬 파일은 호출 시점과 문법을 알려주며, Claude가 스킬 설명을 읽지 않더라도 훅이 큰 파일 읽기를 차단하는 구조를 유지한다.

5. 벤치마크 결과와 측정 범위

벤치마크는 Java 모노레포의 네 가지 시나리오에서 직접 파일을 읽는 경우와 bulk-reader의 요약을 소비하거나 code-writer로 코드를 생성하는 경우를 비교했다. 대량 읽기에서 측정한 Claude 토큰 절감률은 평균 약 90%였으며, 이는 원본 파일 대신 필요한 분석 요약을 전달한 결과다. 코드 생성은 위임하지 않을 때 Claude가 참조 파일을 읽는 입력 토큰과 코드를 만드는 고가의 출력 토큰을 모두 사용하므로 같은 방식으로 수치화하기가 더 어렵다고 설명한다. 위임한 경우 생성 코드는 디스크로 바로 전달되어 Claude가 그 내용을 보지 않는다. 따라서 제시된 90%는 대량 읽기의 평균 Claude 토큰 절감 결과로 이해해야 하며, 글은 작업 모델 비용까지 합친 전체 비용 절감률이나 코드 생성의 별도 절감률을 제시하지 않는다.

6. 편집과 복잡한 추론은 직접 처리

글은 분석을 위임하더라도 편집 자체까지 맡길 수는 없다는 한계를 명시한다. 작업 모델의 요약에는 신뢰할 수 있는 줄 번호가 포함되지 않으므로, Claude가 실제 변경을 수행하려면 필요한 코드 구간을 다시 직접 읽어야 한다. 훅이 offset과 limit를 이용한 특정 구간 읽기를 허용하는 이유도 이 편집 흐름을 지원하기 위해서다. 추론에서도 작업 모델은 표면적인 패턴을 찾았지만 테스트 중 미묘한 스레드 안전성 버그를 놓쳤고, Claude는 적절한 문맥을 받은 뒤 수초 만에 이를 발견했다. 이 경험을 바탕으로 라우팅은 디버깅, 아키텍처 결정, 안전이 중요한 코드를 명시적으로 제외하며, 토큰 절감의 적용 범위를 코드 이해를 위한 읽기와 예측 가능한 생성 작업으로 제한한다.

7. 네트워크 지연과 호출 시간 제한

각 위임은 Claude Code에서 Portal 백엔드와 작업 모델을 거쳐 응답이 돌아오는 네트워크 왕복을 추가한다. 글에서 설명하는 일반적인 응답 시간은 10~30초이며, Portal은 단일 호출을 30초로 제한하므로 매우 큰 생성 작업은 더 작은 호출로 나누어야 한다. 이런 지연은 큰 파일을 읽을 때는 수용할 수 있지만 작은 읽기에서는 절감 효과보다 위임 오버헤드가 커져 오히려 불리할 수 있다. 파일 줄 수 임계값은 이 차이를 반영해 작은 작업까지 무조건 위임하지 않도록 두는 장치다. 따라서 토큰 절감만으로 모든 호출의 효율이 개선된다고 볼 수는 없으며, 글은 읽기 규모와 생성량에 따라 위임의 이점과 대기 시간을 함께 고려해야 하는 구조를 설명한다.

8. 모드 재사용과 설치를 통한 적용

글은 shunt가 Claude Code용 구현이지만, 핵심인 AiKA 모드는 Portal CLI를 실행할 수 있는 여러 프로젝트와 도구에서 재사용할 수 있다고 설명한다. 공개된 bulk-reader와 code-writer를 공유할 수 있고, 문서 작성이나 코드 리뷰 요약, 국제화 번역을 위한 모드를 추가하는 구성 가능성도 제시한다. 플러그인은 위임 시점을 결정하고 모드는 응답 방식을 결정하므로, 작업 모델이나 시스템 지침, MCP 도구를 바꾸더라도 플러그인을 수정할 필요가 없다. 적용 절차는 spotify/portal-ai-plugins 마켓플레이스를 추가하고 portal과 shunt 플러그인을 설치한 뒤, 새 Claude Code 세션에서 /portal:setup으로 Portal 인스턴스 연결과 인증을 수행하는 것이다. 기존 공개 모드를 바로 사용할 수 있으며, 이를 복제해 개인화하면 자신의 버전이 자동으로 우선 적용되어 라우팅을 구성 중심으로 관리할 수 있다.

🧾 핵심 주장 / 시사점

• 핵심 절감 방식은 파일 원문과 생성 결과가 Claude 문맥을 통과하는 양을 줄이는 데 있다.
• 훅이 위임을 강제하고 스킬이 실행 방법을 안내하는 분리는 모델이 지침을 자발적으로 따르는 데 대한 의존을 줄인다.
• 위임 시점과 응답 방식을 분리하면 플러그인을 유지하면서 작업 모델과 지침을 교체하고 모드를 여러 프로젝트에서 재사용할 수 있다.

✅ 액션 아이템

• bulk-reader와 code-writer의 적용 범위를 대용량 읽기와 기존 패턴에 맞춘 반복 코드 생성으로 구분.
• shunt의 기본 350줄 기준과 10~30초 지연을 함께 고려해 위임할 읽기 규모 검토.
• 편집에 필요한 구간 확인과 복잡한 추론은 Claude에 유지하고, 큰 생성 작업은 Portal의 단일 호출 제한 30초를 고려해 분할.

❓ 열린 질문

• Java 모노레포에서 나타난 평균 약 90%의 대량 읽기 토큰 절감은 다른 작업에서도 재현되는가?
• 기본 350줄 기준은 10~30초의 위임 지연을 고려할 때 적용할 작업에 적절한가?
• bulk-reader와 code-writer에 맡길 작업과 Claude에 남길 복잡한 추론을 어떤 기준으로 구분할 것인가?