Claude Code 비용 줄이는 법: Headroom으로 입력 토큰 압축하기

AI 비용을 줄이고 싶을 때 많은 사람이 먼저 프롬프트를 고칩니다.

"더 짧게 써야 하나?" "질문을 더 정확하게 해야 하나?" "모델을 낮춰야 하나?"

물론 전부 도움이 됩니다. 그런데 Claude Code 같은 AI 코딩 에이전트를 쓰다 보면 진짜 토큰을 많이 쓰는 곳은 따로 있습니다.

바로 AI가 읽는 입력입니다.

코드 파일, 터미널 로그, 에러 메시지, JSON 응답, 검색 결과, 이전 대화 맥락, RAG 검색 조각. 우리는 별생각 없이 "이거 봐줘"라고 던지지만, AI는 그 안의 맥락을 처리합니다.

문제는 그 안에 필요한 정보만 있는 게 아니라는 점입니다.

반복되는 로그, 장황한 JSON, 이미 알고 있는 코드, 문제 해결과 상관없는 출력까지 함께 들어갑니다. 결국 우리는 문제 해결에 필요한 지능보다, 불필요한 맥락을 읽히는 데 더 많은 비용을 쓰게 됩니다.

왜 비용이 새나요?

Claude Code를 쓸 때 우리는 보통 이렇게 일합니다.

이 에러 고쳐줘.
이 파일 전체 봐줘.
이 로그 보고 원인 찾아줘.
이 코드베이스 구조 파악해줘.

그러면 AI 에이전트는 파일을 열고, 검색하고, 로그를 읽고, 관련 코드를 따라갑니다. 이 과정 자체는 강력합니다. 사람이 놓친 단서를 AI가 찾아줄 수 있으니까요.

하지만 비용 관점에서는 조심해야 합니다.

예를 들어 에러 원인은 로그의 마지막 30줄에 있는데, AI에게는 5,000줄짜리 로그를 그대로 넣는 경우가 많습니다. 필요한 설정은 JSON의 일부 필드뿐인데, 전체 응답을 통째로 읽히기도 합니다.

이때 토큰 비용은 "내가 입력한 질문"보다 "AI가 실제로 처리한 전체 맥락"에서 커질 수 있습니다.

그래서 질문을 바꿔야 합니다.

어떻게 더 좋은 프롬프트를 쓸까?

보다 먼저,

AI에게 읽히기 전에 무엇을 줄일 수 있을까?

를 물어야 합니다.

먼저 무엇을 줄일지 정하세요

Headroom 같은 도구를 붙이기 전에 먼저 해야 할 일이 있습니다.

내가 AI에게 어떤 맥락을 계속 읽히고 있는지 점검하는 것입니다.

많은 사람은 AI를 실행 도구로만 씁니다.

요약해줘.
작성해줘.
고쳐줘.
만들어줘.

이런 요청은 결과물을 빠르게 만들어 줍니다. 하지만 내 판단 기준이 그대로라면, AI 사용량이 늘어도 일하는 방식은 크게 바뀌지 않습니다.

더 강력한 사용법은 AI에게 내 사용 방식을 점검시키는 것입니다.

내가 반복해서 낭비하는 판단은 뭐지?
내가 AI에게 맡겨도 되는 일과 맡기면 안 되는 일은 뭐지?
내가 읽히는 맥락 중 무엇이 매번 불필요하게 반복되지?

이 과정을 먼저 해야 Headroom도 제대로 쓸 수 있습니다. 압축 도구는 입력을 줄여주지만, 무엇을 줄여도 되는지는 사람이 기준을 세워야 하기 때문입니다.

Headroom은 무엇인가요?

Headroom은 AI 에이전트가 읽는 Tool Output, 로그, 파일, RAG 검색 조각, 대화 맥락 등을 LLM에 도달하기 전에 압축해 주는 도구입니다.

쉽게 말하면 AI 앞에 붙는 맥락 압축 계층입니다.

기존 흐름
파일 / 로그 / JSON / 검색 결과
→ 그대로 Claude Code에 전달
→ 많은 입력 토큰 사용

개선 흐름
파일 / 로그 / JSON / 검색 결과
→ Headroom이 먼저 압축하고 정리
→ Claude Code가 필요한 맥락 중심으로 읽음
→ 입력 토큰 절감

공식 README 기준으로 Headroom은 JSON 데이터에서 60-95%, 코딩 에이전트 작업에서 15-20% 수준의 토큰 절감을 목표로 설명됩니다. 실제 절감률은 입력 종류와 작업 방식에 따라 달라집니다.

또한 Headroom은 로컬에서 실행되는 구조를 내세우고, 원문을 필요할 때 다시 가져올 수 있는 방식도 제공합니다. 그래서 핵심은 단순합니다.

AI가 읽기 전에 먼저 줄인다.

언제 잘 맞나요?

Headroom 같은 압축 계층은 아래 상황에서 특히 유용합니다.

긴 로그를 자주 붙이는 경우

테스트 실패 로그, 서버 로그, 배포 로그, 에러 스택을 자주 다룬다면 효과를 기대할 수 있습니다.

같은 패턴이 반복되는 로그는 원문 전체보다 핵심 단서가 중요합니다.

JSON 응답이 큰 경우

API 응답, 설정 덤프, 분석 결과, 검색 결과처럼 구조화된 데이터는 사람이 봐도 대부분이 반복 필드입니다.

AI에게 필요한 것은 전체 원문이 아니라 문제 해결에 필요한 키와 중첩 구조인 경우가 많습니다.

코드베이스 탐색이 잦은 경우

AI 에이전트가 매번 여러 파일을 열고, 검색하고, 전체 맥락을 파악하는 프로젝트라면 입력 토큰이 빠르게 늘어납니다.

이때 압축 계층은 불필요한 반복 읽기를 줄이는 데 도움을 줄 수 있습니다.

RAG 검색 결과를 많이 쓰는 경우

문서 검색 기반 답변이나 사내 지식 검색을 붙여 쓰는 경우, 검색 결과가 길어질수록 비용이 커집니다.

이때도 LLM에 도달하기 전에 후보 맥락을 정리하는 방식이 유용합니다.

설치와 기본 사용

Headroom CLI를 쓰려면 Python 패키지 또는 uv tool 설치를 기준으로 보는 것이 안전합니다.

uv tool install --python 3.13 "headroom-ai[all]"

또는 pip로 설치할 수 있습니다.

pip install "headroom-ai[all]"

Claude Code에 래핑해서 사용할 수 있습니다.

headroom wrap claude

설치 상태를 확인합니다.

headroom doctor

절감 현황을 확인하려면 대시보드를 실행합니다.

headroom dashboard

실전 프롬프트 5개

아래 프롬프트는 그대로 복사해서 쓸 수 있습니다. 처음부터 다 쓸 필요는 없습니다. 지금 가장 찔리는 것 하나만 골라서 시작해도 충분합니다.

1. AI 비용이 새는 곳 찾기

나는 Claude Code / Codex / Cursor 같은 AI 코딩 에이전트를 사용하고 있어.
최근 AI에게 자주 넣는 입력은 아래와 같아.

- 로그: [예: 서버 에러 로그, 배포 로그, 테스트 실패 로그]
- 파일: [예: 전체 컴포넌트 파일, API 핸들러, 설정 파일]
- 작업 요청: [예: 버그 수정, 리팩토링, 기능 추가]
- 반복되는 상황: [예: 매번 같은 에러 분석, 비슷한 PR 리뷰]

내 AI 사용에서 입력 토큰이 가장 많이 낭비될 가능성이 높은 지점을 찾아줘.
각 항목을 아래 기준으로 분류해줘.

1. 원문 그대로 읽혀도 되는 것
2. 요약 후 읽혀도 되는 것
3. 구조화해서 읽혀야 하는 것
4. 아예 매번 다시 읽힐 필요가 없는 것

마지막에는 오늘 바로 줄일 수 있는 입력 토큰 절감 행동 3개를 제안해줘.
듣기 좋은 말 말고, 낭비가 큰 순서대로 말해줘.

이 질문의 목적은 단순합니다. 내가 AI에게 매번 그대로 던지던 것 중, 사실은 줄여도 되는 것을 찾는 겁니다.

2. 반복 결정을 규칙으로 바꾸기

AI 비용은 로그에서만 새지 않습니다. 반복되는 판단에서도 샙니다.

매번 같은 기준을 설명하고 있다면, 그 자체가 비용입니다.

내가 최근 AI와 함께 반복해서 판단한 상황들이야.

[반복되는 판단 상황을 적기]
예:
- 테스트가 실패하면 전체 로그를 붙여넣고 원인을 물어본다.
- 작은 UI 수정도 매번 전체 파일을 보여준다.
- 리팩토링 범위를 정할 때마다 기준을 새로 설명한다.
- AI가 수정해도 되는 파일과 안 되는 파일을 매번 말한다.

이 중 매번 새로 고민하지 말고 규칙으로 만들어야 할 것을 골라줘.
각 규칙은 내가 그대로 프로젝트 규칙 파일에 넣을 수 있게 한 줄 문장으로 작성해줘.

형식:
- 규칙 이름:
- 한 줄 규칙:
- 이 규칙이 줄여주는 낭비:
- 예외 상황:

너무 일반적인 조언 말고, 실제 작업에서 바로 적용할 수 있는 문장으로 써줘.

좋은 답이 나오면 채팅창에만 두지 마세요. 프로젝트 규칙, Claude Project, ChatGPT 맞춤 지시, Codex의 작업 규칙 파일 등에 넣어두면 됩니다.

3. AI에게 맡길 일과 확인받을 일 나누기

AI 에이전트 비용을 줄이려면 위임 기준도 필요합니다.

매번 확인하느라 느린 것도 문제이고, 확인 없이 맡겼다가 사고 나는 것도 문제입니다.

내가 AI 코딩 에이전트에게 맡기는 작업 목록이야.

[작업 목록]
예:
- 테스트 실패 원인 분석
- 간단한 CSS 수정
- API 응답 타입 수정
- 블로그 글 초안 작성
- 배포 설정 변경
- 데이터베이스 마이그레이션 작성
- 기존 코드 리팩토링

각 작업을 세 단계로 나눠줘.

1. 물어보지 말고 바로 해도 되는 작업
2. 실행 전 반드시 확인받아야 하는 작업
3. AI가 단독으로 손대면 안 되는 작업

그리고 내가 지금 너무 보수적으로 확인하느라 느린 부분과, 반대로 너무 쉽게 맡겨서 위험한 부분을 각각 짚어줘.
마지막에는 이 기준을 프로젝트 규칙 파일에 넣을 수 있게 짧은 운영 규칙으로 정리해줘.

이 프롬프트는 토큰 비용뿐 아니라 작업 안정성에도 도움이 됩니다.

4. Headroom 도입 전 체크리스트 만들기

새 도구를 바로 전체 프로젝트에 붙이기 전에, 먼저 작은 범위에서 테스트하는 것이 좋습니다.

나는 Claude Code 앞단에 Headroom 같은 맥락 압축 도구를 붙이려고 해.
내 프로젝트 상황은 아래와 같아.

- 프로젝트 종류: [예: Next.js 서비스, Node API, 데이터 분석 프로젝트]
- 자주 읽히는 입력: [예: 테스트 로그, 서버 로그, JSON 응답, 코드 파일]
- 민감한 영역: [예: 결제, 인증, DB 마이그레이션, 배포 설정]
- 자주 하는 AI 작업: [예: 버그 수정, 리팩토링, 테스트 작성]

이 프로젝트에 Headroom을 점진적으로 도입하기 위한 체크리스트를 만들어줘.
아래 항목을 포함해줘.

1. 먼저 테스트할 안전한 작업 범위
2. 압축하면 안 되거나 조심해야 할 입력
3. 답변 품질 저하를 확인하는 기준
4. 토큰 절감 효과를 기록하는 방법
5. 팀에 공유하기 전에 확인할 것

최대한 실무적으로 작성해줘.

압축은 비용을 줄여주지만, 모든 맥락을 무조건 줄이는 것이 정답은 아닙니다. 중요한 단서가 사라지면 오히려 디버깅 시간이 늘어날 수 있습니다.

5. 압축하면 안 되는 맥락 찾기

토큰 절감에만 집중하면 위험합니다.

특히 보안, 결제, 데이터 손상, 마이그레이션, 배포 관련 작업은 맥락이 조금만 빠져도 문제가 커질 수 있습니다.

내가 AI에게 맡기는 작업 중, 입력 맥락을 압축하면 위험할 수 있는 작업을 찾아줘.

작업 목록:
[작업 목록]

각 작업에 대해 아래 기준으로 분류해줘.

1. 압축해도 안전한 입력
2. 요약은 가능하지만 원문 확인이 필요한 입력
3. 원문을 반드시 보존해야 하는 입력
4. AI가 판단하기 전에 사람이 먼저 확인해야 하는 입력

특히 보안, 결제, 인증, 데이터베이스, 배포, 고객 데이터와 관련된 위험을 우선해서 봐줘.
마지막에는 "압축 금지 규칙" 5개를 만들어줘.

좋은 도구일수록 사용 기준이 필요합니다. Headroom도 마찬가지입니다.

추천 운영 방식

Claude Code 비용을 줄이고 싶다면 아래 순서로 운영해 보세요.

1. 최상위 모델로 내 AI 사용 패턴을 점검한다.
2. 나온 답을 운영 규칙으로 남긴다.
3. 일상 작업은 그 규칙 위에서 돌린다.
4. Headroom으로 입력 맥락을 압축한다.
5. 절감률과 답변 품질을 함께 본다.

핵심은 비싼 모델을 매번 실행에 쓰는 것이 아닙니다. 비싼 모델로 기준을 세우고, 그 기준을 파일로 남기고, 일상 작업은 더 정리된 맥락 위에서 돌리는 것입니다.

운영 규칙은 이렇게 짧게 시작해도 됩니다.

• 긴 로그를 다룰 때는 전체 원문보다 에러 발생 시점 전후의 핵심 구간과 반복 패턴을 먼저 확인한다.
• 테스트 실패를 분석할 때는 실패한 테스트명, 기대값과 실제값, 첫 번째 에러 스택, 최근 변경 파일을 먼저 본다.
• 대용량 JSON은 전체 필드를 그대로 설명하지 말고, 문제 해결에 필요한 키와 중첩 구조만 요약해서 사용한다.
• 결제, 인증, 권한, 데이터 삭제, 마이그레이션 관련 변경은 실행 전에 반드시 사용자 확인을 받는다.
• 압축된 맥락만으로 원인 판단이 불확실하면 원문 확인이 필요한 지점을 먼저 요청한다.

주의할 점

Headroom 같은 도구는 입력 토큰을 줄이는 데 도움을 줄 수 있지만, 만능은 아닙니다.

첫째, 절감률은 작업마다 다릅니다. JSON, 로그, 반복 출력처럼 구조가 있는 입력은 줄이기 쉽지만, 짧고 밀도 높은 코드나 중요한 에러 맥락은 크게 줄지 않을 수 있습니다.

둘째, 압축 과정에서 중요한 단서가 빠질 수 있습니다. 그래서 처음부터 모든 작업에 적용하기보다 작은 프로젝트나 덜 위험한 작업부터 테스트하는 것이 좋습니다.

셋째, 팀 단위로 쓸 때는 개인 설정과 팀 공용 설정을 분리해야 합니다. 개인의 로컬 규칙이 팀 전체 동작에 섞이면 예상치 못한 결과가 생길 수 있습니다.

넷째, 토큰 절감률만 보지 마세요. 답변 품질이 떨어지면 줄인 토큰보다 디버깅 시간이 더 비싸질 수 있습니다.

마무리

AI 비용을 줄이는 순서는 이렇게 잡는 것이 좋습니다.

1. AI에게 내 사용 방식을 점검시킨다.
2. 반복되는 판단을 운영 규칙으로 남긴다.
3. AI가 읽는 입력 맥락을 줄인다.
4. Headroom 같은 도구로 압축 계층을 붙인다.
5. 절감률과 답변 품질을 함께 확인한다.

프롬프트를 짧게 쓰는 것도 중요합니다. 하지만 그보다 먼저 봐야 할 것이 있습니다.

AI가 읽는 맥락입니다.

Claude Code는 우리가 던진 맥락을 처리합니다. 그래서 더더욱, 무엇을 읽힐지 사람이 먼저 설계해야 합니다.

비싼 AI는 매번 실행 노동자로만 쓰지 마세요. 먼저 내 일의 기준을 점검하게 하세요. 그리고 그 기준을 파일로 남기세요. 그다음 Headroom 같은 도구로 매번 들어가는 입력을 줄이세요.

그때부터 AI 비용 절감은 단순한 아끼기가 아니라, 더 좋은 AI 운영 방식이 됩니다.

Q&A