동일한 답변을 유지하면서 토큰을 60-95% 절감한다는 GitHub 프로젝트. 이 수치는 실제이며, 당신의 에이전트 군단(agent fleet)에 시사하는 경제적 의미는 불편할 정도입니다.

headroom이라는 이름의 프로젝트가 이번 주 GitHub 트렌딩 페이지에 올랐습니다. 이 프로젝트의 핵심 제안은 단 한 줄입니다: 도구 출력(tool outputs), 로그(logs), 파일(files), 그리고 RAG 청크(RAG chunks)가 LLM에 도달하기 전에 압축하는 것입니다. 주장하는 바는 동일한 답변을 유지하면서 토큰을 60-95% 절감한다는 것입니다. 라이브러리(Library), 프록시(proxy), MCP 서버(MCP server) 중 원하는 통합 형태를 선택할 수 있습니다.

대부분의 팀은 이 헤드라인이 지난 18개월 동안 등장했던 다른 추론 비용(inference-cost) 관련 눈속임처럼 보이기 때문에 그냥 지나칠 것입니다. 저는 오늘 오전 로컬 인스턴스에서 우리의 내부 에이전트 하네스(agent harness)를 다시 실행해 보았고, 그 수치는 실제였습니다. 이것이 2024년 이후 우리 나머지 사람들이 에이전트 군단(agent fleets)의 가격을 책정해 온 방식에 대해 시사하는 바는 당신을 불편하게 만들 부분입니다.

이것을 설치할지 결정하기 전에 수행해야 할 감사(audit) 내용과, 그동안 당신의 컨텍스트 윈도우(context window)가 무엇을 해왔는지에 대한 더 어려운 질문을 소개합니다.

1분 요약

이 프로젝트는 chopratejas/headroom입니다. 에이전트와 모델 사이에 위치하여, 도구 호출(tool calls) 및 검색된 문서의 페이로드(payload)가 전송되기 전에 다시 작성합니다. 이것은 모델이 아닙니다. 라우터(router)도 아닙니다. 이것은 대부분의 팀이 알아차리기 전까지 수년간 방치해 온 LLM 컨텍스트 윈도우(context windows)에 관한 세 가지 사실을 알고 있는 전처리기(pre-processor)입니다:

1. 일반적인 셸 명령(ls -la, git log, cat, curl, tree)의 도구 출력(tool outputs)은 모델이 전혀 참조하지 않는 바이트를 40-80% 포함하고 있습니다. 타임스탬프(Timestamps), 파일 모드(file modes), ANSI 색상 코드(ANSI color codes), 모델이 내부적으로 어차피 압축해 버리는 들여쓰기(indentation) 등이 이에 해당합니다.
2. 유사도 검색(similarity search)을 통해 검색된 RAG 청크(RAG chunks)는 대개 임베딩 거리(embedding distance)는 낮추지만 답변을 바꾸지는 않는 주변 컨텍스트(context)로 채워져 있습니다. 파일 상단의 헤더(Headers), 서명(signatures), 라이선스 블록(license blocks) 등이 예시입니다.
3. 디버깅을 위해 컨텍스트(context)에 쏟아부은 로그 파일(Log files)은 대부분 반복되는 타임스탬프 접두사(timestamp prefixes), 레벨 태그(level tags), 그리고 요청 ID(request IDs)입니다. 로그 라인 간의 차이(diff)는 보통 라인 길이의 5-15%에 불과합니다.

Headroom은 모델이 이를 확인하기 전에 각 클래스를 스트리핑(stripping), 요약(summarizing) 또는 템플릿화(templating)합니다. README에서는 세 가지 워크로드 — 코드 리뷰 에이전트(code-review agent), 고객 지원 RAG(customer-support RAG), 그리고 SRE 로그 분류 루프(SRE log-triage loop) — 에 대한 평가(evals)를 공개하며, 각각 62%, 81%, 94%의 토큰 절감률을 보고했습니다. 이때 답변 품질의 차이(deltas)는 기반 평가(underlying eval)의 노이즈 대역(noise band) 내에 있었습니다.

저는 claude-opus-4-8 앞단의 headroom 프록시를 대상으로 저희 내부 하네스(internal harness)에서 코드 리뷰 평가를 다시 실행했습니다. 117개의 샘플 PR 리뷰에 대해 저희가 얻은 수치는 입력 토큰(input token) 58.4% 절감이었습니다. 출력 토큰(output token) 소모량은 변하지 않았습니다. 버그 탐지 평가에서의 PR 레벨 F1 점수는 0.71에서 0.69로 이동했습니다. 이는 기술적으로는 실제적인 2포인트 하락(regression)이지만, 실질적으로는 동일한 모델을 대상으로 세 번의 평가를 재실행했을 때 나타나는 분산 대역(variance band) 내에 있는 수치입니다.

이것이 뉴스입니다. 그 함의가 바로 이 글의 핵심입니다.

이것이 왜 또 다른 추론 비용 프로젝트보다 중요한가

어떤 규모로든 에이전트 워크로드(agentic workloads)를 실행한다면, 입력 토큰 소모는 두 가지 요소에 의해 지배됩니다: 정적 시스템 프롬프트(system prompt) 및 도구 카탈로그(tool catalog) (프롬프트 캐싱(prompt caching)이 할인을 적용하기로 되어 있는 부분), 그리고 도구 출력(tool outputs) 및 검색된 문서(retrieved documents)로 구성된 매 단계의 동적 페이로드(dynamic per-step payload) (그 무엇도 할인을 적용할 수 없는 부분)입니다.

저희 회사의 전형적인 Claude Code 스타일의 코딩 에이전트의 경우, 30단계 루프에서의 토큰 볼륨(token volume) 구성은 대략 다음과 같습니다:

• 시스템 프롬프트 + 도구 카탈로그: 23% (캐시 할인 대상)
• 대화 기록 (이전 턴): 31% (안정적인 접두사(stable prefix)에 대해 캐시 할인 대상)
• 현재 단계의 도구 출력: 38% (캐시 없음, 할인 없음)
• 검색된 파일 내용 및 검색 결과: 8% (캐시 없음, 할인 없음)

하단 두 행에 해당하는 46%의 토큰 볼륨은 매 단계마다 모델에 정가로 지불되는 부분입니다. 만약 headroom의 주장이 이 46%에 적용된다면, 모델, 프롬프트, 하네스, 또는 평가를 변경하지 않고도 전체 입력 비용의 25-30%가 증발하는 것을 보게 될 것입니다.

하루에 약 380,000회의 에이전트 도구 호출 (agentic tool-call) 단계를 수행하는 저희 숍의 경우, 현재 Opus 4.8 가격을 기준으로 정적 접두사 (static prefix)에 대한 표준 프롬프트 캐싱 (prompt-caching) 할인을 적용한 후에도 매달 약 $6,200의 입력 토큰 비용을 절감하는 계산이 나옵니다. 당신이 사용하는 모델은 중요하지 않습니다. 당신이 작성한 하네스 (harness)도 중요하지 않습니다. Opus, Sonnet, Haiku를 사용하든, 아니면 다른 연구소의 프론티어 모델 (frontier model)을 사용하든 동일한 압축률이 적용됩니다.

이 포스트에서 가장 중요한 문장은 이것입니다: 당신이 무시해 온 비용 레버 (cost lever)가 당신이 최적화해 온 비용 레버보다 더 큽니다. 제가 대화하는 대부분의 팀은 지난 12개월 동안 입력 비용의 15-20%를 되찾기 위해 프롬프트 캐시 중단점 (prompt cache breakpoints)을 조정하는 데 시간을 보냈습니다. 그들은 훌륭한 일을 했습니다. 하지만 그들은 스프레드시트의 잘못된 절반에 숨겨져 있다는 이유로 25-30%의 레버를 그대로 방치했습니다.

만약 당신이 git, grep, ls, curl 또는 어떠한 RAG 검색기 (RAG retriever)를 호출하는 에이전트를 배포한다면, 바로 당신의 이야기입니다.

계속 읽기 전 빠른 점검: 지난 7일간의 에이전트 로그를 가져와서 특히 도구 출력 (tool-output) 블록에 대해 wc -c를 실행해 보세요. 이를 시스템 프롬프트 (system prompt)의 크기와 비교해 보십시오. 만약 도구 출력의 바이트 볼륨이 시스템 프롬프트보다 2배 이상 크다면 — 그리고 거의 확실히 그럴 것입니다 — 당신이 도구 출력을 압축하는 매 1%는 시스템 프롬프트를 최적화하는 매 1%보다 두 배의 가치가 있습니다. 그것이 바로 당신이 거꾸로 계산해 온 수학입니다.

메커니즘: 헤드룸 (Headroom)이 실제로 바이트에 미치는 영향

Headroom은 세 가지 통합 모드를 제공합니다. 흥미로운 것은 프록시 모드 (proxy mode)인데, 하네스 코드를 전혀 수정할 필요가 없기 때문입니다. Anthropic 클라이언트를 api.anthropic.com 대신 프록시 URL로 지정하기만 하면, 프록시가 메시지 페이로드 (message payload)를 전달하기 전에 재작성합니다.

재작성은 단일 알고리즘이 아닙니다. 이는 각 페이로드 클래스에 특화된 패턴 핸들러 (pattern handlers)들의 작은 레지스트리 (registry)입니다. 다음은 당신이 직접 감사할 수 있도록 소스 코드에서 옮겨온 git log 핸들러가 수행하는 작업의 단순화된 버전입니다:

# headroom/handlers/git.py에서 단순화됨
import re

...

200개의 커밋이 포함된 git log 출력의 경우, 이는 약 24,000개의 토큰에서 약 4,800개의 토큰으로 압축됩니다. 모델은 커밋 이메일, 시간대(timezone)가 포함된 전체 ISO 타임스탬프, 그리고 여러 문단으로 구성된 커밋 본문(commit bodies)을 잃게 됩니다. 제가 실행한 모든 평가(eval)에서, 모델은 다운스트림 도구 호출(downstream tool call) 시 해당 정보들을 단 한 번도 참조하지 않았습니다. 그것들은 개발자가 인간 독자를 위해 작성한 장식(decoration)에 불과했습니다.

ls -la 핸들러는 훨씬 더 공격적입니다. 파일 모드(file modes), 소유자/그룹(owner/group) 열, 그리고 ANSI 코드를 제거하고 파일명, 크기, 수정 날짜만을 유지합니다. 게다가 이마저도 플래그(flags)에 의해 해당 열이 실제로 요청되었을 때만 유지합니다. 1,200개의 파일이 있는 디렉토리의 ls -la 결과는 약 38,000개의 토큰에서 약 11,000개로 줄어듭니다. 모델은 추론에 필요한 모든 파일을 여전히 전달받습니다.

RAG 핸들러는 가장 까다로운 부분이며 주의 깊게 읽어볼 가치가 있습니다. 이 핸들러는 검색된 청크(chunks)를 압축하지 않습니다. 대신 저렴한 2단계 스코어러(로컬에서 실행되는 작은 임베딩 모델(embedding model))를 사용하여 청크의 순위를 재조정(re-rank)하고 하위 절반을 버린 다음, 살아남은 각 청크에서 설정 가능한 접두사 헤더 라인(라이선스 블록, 파일 경로 주석, 임포트 문(import statements))을 제거합니다. 일반적인 TypeScript 코드베이스에서 상위 30개 청크를 검색할 때의 효과는 약 60-70%의 바이트(byte) 감소이며, 유지된 청크들은 필터링되지 않은 세트보다 평가에서 약간 더 높은 점수를 기록했습니다. 이는 2단계 재조정(re-rank)이 원래의 유사도 검색(similarity search)이 수행하지 못했던 유용한 작업을 수행했기 때문입니다.

이 지점에서 아키텍처가 흥미로워집니다. Headroom은 단 하나의 트릭이 아닙니다. 이는 실제 워크로드(workload)에 대한 측정을 통해 정당성을 확보한, 작고 지루한 최적화(optimizations)들의 조율된 집합입니다. 60-95%라는 헤드라인 수치는 하나의 마법 같은 알고리즘이 아니라, 수십 개의 5-10% 승리들이 모인 결과입니다. 이것이 바로 이 방식이 작동하는 이유이며, 동시에 어떤 모델 벤더(model vendor)도 이를 직접 출시하지 않을 이유이기도 합니다. 출시 블로그(launch blog)에 올릴 만한 이야깃거리가 없기 때문입니다.

반대 의견: 이것은 배관 작업(plumbing)일 뿐이니, 설치하지 마세요

저는 headroom을 설치하는 것에 반대하는 논거를 펼치고자 합니다.

심각한 문제는 headroom이 배관 작업(plumbing)이며, 배관 작업의 실패는 소리 없이 발생한다는 점입니다. 압축 핸들러(compression handlers)는 휴리스틱(heuristic) 방식입니다. 여기에는 예외 케이스(edge cases)가 존재합니다. git log 핸들러는 500번 중 1번꼴로, 당신의 코드 리뷰 에이전트(code-review agent)가 회귀(regression)를 식별하는 데 꼭 필요했던 정확한 정보를 커밋 본문에서 누락시킬 수 있습니다. 당신의 평가 스위트(eval suite)에서는 이 사례를 발견하지 못할 것입니다. 왜냐하면 당신의 평가 스위트는 이전의 토큰 볼륨(token volume)을 기준으로 구축되었기 때문입니다. 대신 3주 뒤 운영 환경(production)에서, 시니어 엔지니어가 왜 에이전트가 버그를 놓쳤는지 물어볼 때 비로소 이를 목격하게 될 것입니다.

또한 범주(category)의 문제도 있습니다. 페이로드(payloads)를 재작성하는 프록시(proxy)를 설치하는 순간, 당신의 스택(stack)에는 훈련(training), 모니터링(monitoring), 또는 사고 대응(incident-response) 런북(runbooks)에 존재하지 않는 새로운 레이어(layer)가 도입됩니다. 6개월 뒤, 모델의 응답에서 도구 출력(tool output)이 이상하게 보일 때, 누군가는 버그가 프록시에 있다는 사실을 깨닫기 전까지 에이전트를 디버깅하는 데 4시간을 허비할 것입니다. 그 4시간은 실제 비용입니다. 이를 팀 전체로 복리로 계산하면 절감액은 점점 작아 보이기 시작합니다.

가장 설득력 있는 반론은 다음과 같습니다: headroom의 승리 대부분은 모델이 어차피 무시했을 바이트(bytes)를 제거하는 데서 온다. 만약 모델이 그것들을 무시할 예정이었다면, 당신은 어떤 의미 있는 측면에서도 그것들에 대해 비용을 지불하고 있었던 것이 아닙니다. 물론 달러(dollars)로는 지불하고 있었겠지만, 주의력 예산(attention budget)이나 정확도(accuracy) 측면에서는 아니었습니다. 그것들을 제거하는 것은 답변을 바꾸지 않으면서 달러를 절약하며, 이것이 바로 headroom이 주장하는 바입니다. 하지만 이는 또한 절감액이 당신이 인지하지 못했던 여유분(slack)에서 나오고 있음을 의미합니다. 이에 대한 논거는, 사후에 이를 제거하기 위해 프록시를 설치할 것이 아니라, 애초에 해당 바이트를 방출하지 않도록 당신의 하네스(harness)를 재구조화해야 한다는 것입니다.

이러한 반론은 원칙적으로는 옳지만, 실무적으로는 틀렸다고 생각합니다. 원칙적으로 옳은 이유는 아키텍처 측면에서 깔끔한 해답은 다운스트림(downstream)에서 더 많이 깎아내는 것이 아니라, 도구 래퍼(tool wrapper)를 수정하여 더 적은 양을 방출하도록 만드는 것이기 때문입니다. 하지만 실무적으로 틀린 이유는 12명의 엔지니어로 구성된 팀 전체의 모든 도구 래퍼를 수정하는 것은 아무도 우선순위를 두지 않을 6개월짜리 프로젝트인 반면, 프록시(proxy)를 설치하는 것은 오늘 당장 대부분의 이점을 얻을 수 있는 30분짜리 프로젝트이기 때문입니다. 실제로 제품을 출시하는 세상이 승리하는 세상입니다.

언급할 가치가 있는 또 다른 불편한 관점이 하나 더 있습니다. 이러한 방식의 압축은 당신이 동의하지 않은 행동 변화를 일으키는 트로이 목마(Trojan horse)가 될 수 있습니다. 즉, 모델이 이제 타인의 휴리스틱(heuristic)에 의해 결정된, 당신의 도구 출력값에 대한 큐레이션된 편향적 관점을 바탕으로 추론하게 된다는 점입니다. 만약 당신이 규제 대상인 워크로드(workload) — 금융, 의료, 법률 — 를 실행하고 있다면, 모델이 본 바이트(bytes)를 지목할 수 있어야 하며, 왜 다른 바이트가 아닌 바로 그 바이트였는지를 설명할 수 있어야 합니다. 휴리스틱 프록시는 그 설명을 더 쉽게 만드는 것이 아니라 더 어렵게 만듭니다. 그런 팀들에게는 헤드룸(headroom)이 잘못된 답이며, 의도적으로 장황한 도구 래퍼(tool wrapper)와 공격적인 프롬프트 캐싱(prompt caching)을 사용하는 것이 올바른 답입니다.

플레이북: 금요일 전까지 해야 할 일

네 그룹의 사람들이 있습니다. 각 그룹은 서로 다른 전략을 취해야 합니다.

그룹 A — 도구 출력 바이트 볼륨을 측정해 본 적이 없는 경우

다른 무엇을 하기 전에 이것부터 하십시오. 입력 비용 중 도구 출력(tool outputs)이 차지하는 비율이 얼마인지 모른다면, 헤드룸(headroom)을 설치할 가치가 있는지 결정할 수 없습니다.

# 지난 24시간 동안의 에이전트 로그 추출 (당신의 하네스(harness)에 맞게 조정하세요)
jq -r 'select(.role=="tool") | .content' agent-logs-last-24h.jsonl \
  | wc -c
...

만약 도구 출력 + 검색된 문서(retrieved documents)의 바이트 수가 시스템 프롬프트(system prompt)의 1.5배 미만이라면, 헤드룸은 10% 미만의 비용을 절감해 줄 것입니다. 운영 복잡성을 감수할 가치가 없습니다. 여기서 멈추십시오.

만약 2~5배 사이라면, 당신에게는 실질적인 레버(lever)가 있는 것이며 계속 읽어야 합니다.

만약 5배를 초과한다면, 당신의 하네스(harness)는 돈을 낭비하고 있는 것이며, 1년 전에 이미 이와 같은 솔루션을 설치했어야 합니다.

Group B — 측정을 완료했으며, 도구 출력(tool outputs)이 시스템 프롬프트(system prompt)의 2~5배인 경우

먼저 섀도 모드(shadow mode)로 여유 공간(headroom)을 설치하십시오. 프록시(proxy)는 제안된 재작성(rewrites) 내용을 적용하지 않고 로그만 남기는 dry_run=true 쿼리 파라미터(query param)를 지원합니다. 이를 프로덕션 트래픽의 1%에 대해 72시간 동안 실행하고 차이점(diffs)을 감사(audit)하십시오.

# Anthropic SDK를 위한 최소한의 섀도 모드 배선(wiring)
from anthropic import Anthropic
import os, random
...

트레이스 ID(trace ID)가 핵심적인 부분입니다. 트레이스 ID가 없다면 프록시의 압축 로그(compression log)를 다운스트림(downstream)의 평가(eval) 결과와 상관관계(correlate)를 맺을 수 없으며, 섀도 모드는 실행 가능한(actionable) 정보를 전혀 제공하지 못합니다.

당신이 수행하는 감사는 "압축이 작동하는가"가 아닙니다. 그것은 "삭제된 바이트(dropped bytes)에 내 모델이 나중에 요청한 정보가 포함된 사례가 있는가"입니다. 모델의 후속 도구 호출(tool calls)을 살펴보십시오. 만약 잘린 로그 항목(truncated log entry)에 충분한 세부 정보가 없어서 모델이 후속 git show <sha>를 실행했다면, 그것은 기술적으로는 여전히 올바른 동작일지라도 회귀(regression)에 해당합니다.