Claude Code 에이전트 토큰 소비 줄이는 완전 가이드

클로드가 파일 하나 고치는 데 수만 토큰을 씁니다. 루프마다 같은 컨텍스트를 반복해서 읽습니다. 왜 이런 현상이 생기는 걸까요?

원문 참고 : https://x.com/ecommartinez/status/2035838484636655791

어디서 토큰이 낭비되는가

단순히 비용 문제가 아닙니다. Claude Code 에이전트에서 토큰 소비는 세 가지를 동시에 결정합니다.

비용. Sonnet 기준으로 입력 1M 토큰에 \(3, 출력은\)15입니다. 에이전트 루프는 매 턴마다 전체 대화 히스토리를 입력으로 넣기 때문에 루프가 길어질수록 비용이 이차함수적으로 증가합니다.

속도. 컨텍스트 창이 클수록 첫 토큰이 나오기까지 걸리는 시간(TTFT)이 길어집니다. 에이전트 루프에서 이게 누적되면 체감 속도 차이가 상당합니다.

품질. 역설적이지만, 컨텍스트가 너무 길면 모델이 중요한 정보를 놓칩니다. 불필요한 도구 출력이나 반복 내용이 쌓이면 오히려 정확도가 떨어집니다.

토큰 소비 구조를 이해하려면 에이전트 루프 한 턴이 어떻게 구성되는지 알아야 합니다.

[시스템 프롬프트]
+ [대화 히스토리 전체]
+ [현재 사용자 메시지]
+ [도구 정의 전체]
= 입력 토큰

여기서 낭비가 주로 생기는 지점은 다섯 곳입니다.

1. 대화 히스토리 누적 — 루프가 길어질수록 앞 턴의 내용이 계속 포함됩니다.
2. 도구 출력 비대화 — Read 도구로 파일 전체를 읽으면 그 내용 전부가 히스토리에 쌓입니다.
3. 시스템 프롬프트 중복 — CLAUDE.md가 매 턴마다 다시 로드되면서 캐시 미스가 납니다.
4. 불필요한 재확인 루프 — 에이전트가 이미 알고 있는 내용을 확인하기 위해 추가 도구 호출을 하는 경우입니다.
5. 에이전트 팀 — Claude Code의 Agent 팀 기능을 쓰면 팀원 각자가 별도의 컨텍스트 창을 가지므로, 팀원 수에 비례해 토큰이 늘어납니다. 팀원이 plan mode로 실행될 경우 단독 세션 대비 약 7배 더 씁니다.

/compact와 /clear: 다르게 쓰는 두 가지 초기화

컨텍스트를 줄이는 명령어가 두 개 있는데, 용도가 다릅니다.

*/compact* 는 대화 히스토리를 요약본으로 교체합니다. 7만 토큰짜리 대화가 4,000토큰 안팎으로 줄어드는 식입니다. 지금까지 내린 결정, 방향, 제약조건 같은 "작업 맥락"이 요약 안에 남습니다. 태스크 중간에 쓰기 좋습니다.

/compact


<!-- -->
# 요약 범위를 직접 지정할 수도 있습니다
/compact auth 리팩토링에 집중하고, 테스트 디버깅 내용은 제외해줘

*/clear* 는 히스토리를 통째로 지웁니다. 관련 없는 새 태스크를 시작할 때 씁니다. 수동으로 중요한 내용을 정리해두고 새 세션처럼 시작하는 방식입니다.

<!-- -->
# 자동 압축 임계값 설정 (settings.json)
{
  "autoCompact": true,
  "autoCompactThreshold": 0.7
}

autoCompactThreshold: 0.7은 컨텍스트 창의 70%가 차면 자동으로 압축한다는 의미입니다. 기본값은 없으므로 직접 설정해야 합니다.

주의할 점이 있습니다. /compact는 그 자체가 LLM 호출이라 시간(1분 내외)과 토큰을 씁니다. 자동 압축이 태스크 중간에 끼어들면 흐름이 끊기고 성능이 떨어질 수 있습니다. 자동 압축에 기대기보다 태스크 경계에서 선제적으로 실행하는 게 낫습니다. 한 단위 작업이 끝난 직후, 다음 태스크로 넘어가기 전이 타이밍입니다.

.claudeignore로 탐색 범위 제한

Claude Code는 .claudeignore 파일을 지원합니다. .gitignore와 문법이 동일합니다. 여기에 등록한 경로는 Claude가 자동 탐색하거나 검색할 때 포함되지 않습니다. (명시적으로 읽어달라고 하면 읽을 수 있습니다. 탐색·인덱싱에서만 제외됩니다.)

.claudeignore가 없으면 Claude는 node_modules/, .next/, dist/, .venv/, build/ 같은 폴더를 전부 인덱싱 대상으로 씁니다. 파일 수만 개가 있는 빌드 산출물 폴더가 컨텍스트에 포함되는 거죠.

<!-- -->
# .claudeignore 예시
node_modules/
.next/
dist/
build/
.venv/
*.lock
*.log
coverage/

실제로 측정한 사례에서는 11,000토큰이 800토큰으로 줄었다는 보고도 있습니다. 규모가 큰 프로젝트에서는 단순히 이 파일 하나를 만드는 것만으로 세션 토큰의 30~40%를 절감할 수 있습니다.

파일 읽기 전략

Read 도구의 기본 동작은 파일 전체를 읽는 것입니다. 2,000줄짜리 파일을 통으로 읽으면 그 내용이 전부 컨텍스트에 들어갑니다.

*limit과 offset 파라미터를 활용하세요.*

// 파일의 50~100번째 줄만 읽기
{
  "tool": "Read",
  "file_path": "/path/to/file.py",
  "offset": 49,
  "limit": 51
}

필요한 부분을 먼저 grep이나 Bash로 위치를 잡고, 그 주변만 읽는 패턴이 효과적입니다.

<!-- -->
# 먼저 위치 확인
grep -n "def target_function" src/module.py

<!-- -->
# → 143줄에 있다는 걸 확인


<!-- -->
# 그 주변만 읽기 (offset: 140, limit: 30)

전체 파일을 읽는 것과 필요한 30줄만 읽는 것의 차이가 2,000줄 파일에서는 거의 100배입니다.

도구 호출 배치 처리

Claude Code는 한 턴에 여러 도구를 병렬로 호출할 수 있습니다. 도구를 하나씩 순차적으로 호출하는 것과 한 번에 묶어서 호출하는 것은 토큰 소비 측면에서 크게 다릅니다.

순차 호출의 경우:

턴 1: [히스토리] + Read(파일A) → 응답 포함
턴 2: [히스토리 + 턴1 결과] + Read(파일B) → 응답 포함
턴 3: [히스토리 + 턴1+2 결과] + Read(파일C) → 응답 포함

병렬 호출의 경우:

턴 1: [히스토리] + Read(파일A) + Read(파일B) + Read(파일C) → 세 결과 한 번에

병렬 호출이 입력 히스토리 누적을 2턴 줄여줍니다. 에이전트 프롬프트에 "독립적인 작업은 한 번에 묶어서 처리하세요"라고 명시하거나, 스킬을 설계할 때 병렬 처리를 염두에 두는 게 중요합니다.

프롬프트 캐싱 활용

Anthropic API에는 cache_control 파라미터가 있어 반복적으로 전달되는 컨텍스트를 캐싱할 수 있습니다. Claude Code 내부적으로도 이 메커니즘을 씁니다.

캐싱이 가장 효과적인 대상은 시스템 프롬프트와 CLAUDE.md입니다. 이 내용은 매 턴마다 변하지 않기 때문에 캐시 히트율이 높습니다.

캐시 옵션은 두 가지입니다.

읽기 비용이 0.1배라는 게 핵심입니다. 같은 컨텍스트가 두 번 이상 사용되면 캐싱이 이득입니다. 긴 시스템 프롬프트를 반복해서 쓰는 에이전트라면 실제 입력 비용의 90%까지 절감됩니다.

레이턴시도 줄어듭니다. Anthropic 발표 기준, 100K 토큰 문서 예시에서 첫 토큰 응답 시간이 11.5초에서 2.4초로 줄었습니다. 비용만의 문제가 아닙니다.

세션 간격이 길어지면 캐시가 만료됩니다. 5분 캐시 기준으로 세션이 5분 이상 비워지면 다음 턴에 캐시 미스가 납니다. ScheduleWakeup이나 긴 대기가 포함된 루프에서는 이 점을 신경 써야 합니다.

모델 선택 전략

Claude Code는 기본적으로 Sonnet을 씁니다. 하지만 모든 작업에 Sonnet이 필요한 건 아닙니다.

서브에이전트(Agent 툴)를 사용할 때 단순 조회나 포맷 변환 같은 작업은 Haiku로 위임하면 비용이 약 10분의 1로 줄어듭니다.

Agent({
  model: "haiku",
  prompt: "이 JSON 파일에서 name 필드만 추출해서 배열로 반환해줘"
})

반대로 복잡한 추론·코드 생성은 Sonnet이나 Opus를 쓰는 게 맞습니다. 싼 모델로 틀린 결과를 받아서 재시도하는 비용이 처음부터 비싼 모델 쓰는 것보다 클 수 있습니다.

판단 기준은 단순합니다: "이 작업이 틀렸을 때 재시도 비용이 큰가?" 크면 좋은 모델, 그렇지 않으면 빠른 모델입니다.

서브에이전트로 컨텍스트 격리

메인 에이전트가 모든 작업을 처리하면 히스토리가 빠르게 불어납니다. 독립적인 서브태스크는 서브에이전트에 위임하면 메인 컨텍스트를 보호할 수 있습니다.

서브에이전트는 별도 컨텍스트 창에서 실행됩니다. 서브에이전트가 1만 토큰을 써도 메인 에이전트 컨텍스트에는 결과 요약만 들어옵니다.

// 나쁜 패턴: 메인 에이전트가 직접 10개 파일을 순차 읽기
// → 10개 파일 내용이 전부 메인 히스토리에 누적

// 좋은 패턴: Explore 서브에이전트에게 탐색 위임
Agent({
  subagent_type: "Explore",
  prompt: "src/ 디렉토리에서 auth 관련 함수 정의 위치 찾아서 파일명:줄번호 형식으로 목록만 반환해줘"
})
// → 메인 히스토리에는 결과 목록 몇 줄만 들어옴

Explore처럼 탐색 전용 서브에이전트를 쓰면 "탐색 과정의 노이즈"가 메인 컨텍스트를 오염시키는 걸 막을 수 있습니다.

CLAUDE.md 최적화

CLAUDE.md는 매 세션마다 로드되는 시스템 지침입니다. 흔한 오해가 있는데 — 길고 자세할수록 좋은 게 아닙니다.

5,000토큰짜리 CLAUDE.md는 아무것도 하기 전에, 매 턴마다, 모든 세션에서 5,000토큰을 씁니다. 500토큰짜리가 세션당 4,500토큰을 아낍니다. 실무 가이드라인은 500토큰(200줄) 이하, 핵심 규칙만 남기는 것입니다.

CLAUDE.md가 무거워지는 대표적인 패턴이 두 가지입니다.

첫째, 에이전트가 직접 확인할 수 있는 내용. 프로젝트 구조나 파일 경로는 에이전트가 find나 ls로 확인할 수 있습니다. CLAUDE.md에 넣을 필요 없습니다.

둘째, 자주 바뀌는 내용. CLAUDE.md가 바뀌면 캐시가 무효화됩니다. 변하지 않는 핵심 규칙만 남기고, 임시 지침은 별도 파일로 관리하세요.

도메인 지식이 많다면 온디맨드 로딩이 대안입니다. 스킬·레퍼런스 파일을 별도로 두고 필요할 때만 로드하는 방식입니다. 실제 측정 결과에서 모든 것을 CLAUDE.md에 넣는 방식 대비 세션당 약 15,000토큰을 절약했다는 보고가 있습니다.

토큰 소비 모니터링

최적화를 하려면 먼저 현재 얼마나 쓰는지 알아야 합니다.

Claude Code CLI에서 /usage 명령어로 현재 세션의 토큰 소비를 확인할 수 있습니다. API를 직접 쓰는 경우라면 응답 헤더의 x-cache-read-input-tokens와 x-cache-creation-input-tokens로 캐시 히트율을 볼 수 있습니다.

캐시 히트율이 낮다면 (50% 이하) 다음을 점검하세요:

• 세션 간격이 5분을 초과하는가? (캐시 만료)
• 시스템 프롬프트가 매 요청마다 달라지는가?
• CLAUDE.md에 타임스탬프나 동적 값이 들어가 있는가?

Batch API: 실시간이 아니어도 되는 작업은 50% 할인

Claude Code 직접 사용과는 다른 이야기지만, 에이전트를 API로 구성해서 쓰는 경우라면 Batch API를 빼놓을 수 없습니다.

Anthropic의 Message Batches API는 비동기 처리 방식으로, 결과를 24시간 내에 돌려줍니다. 대신 입력·출력 토큰 모두 50% 할인이 적용됩니다.

(1M 토큰 기준, 2026년 기준 가격)

여기에 프롬프트 캐싱을 더하면 시스템 프롬프트 비용이 표준 대비 95%까지 내려갑니다. \(1/MTok → 배치 할인으로\)0.50 → 캐시 읽기로 $0.05/MTok입니다.

한 배치에 최대 100,000건 요청 또는 256MB까지 처리 가능합니다. 대부분의 배치는 1시간 내 완료됩니다.

문서 처리, 데이터 분류, 대량 콘텐츠 생성처럼 결과가 즉시 필요하지 않은 작업에 적합합니다.

Claude Code 에이전트의 토큰 낭비는 대부분 같은 패턴에서 옵니다: 긴 히스토리 누적, 통째로 읽는 파일, 캐시 미스, 순차 도구 호출입니다. 각각에 대응하는 해결책을 정리하면 이렇습니다.

비용보다 품질이 나빠지는 게 먼저 체감됩니다. 컨텍스트가 불필요한 내용으로 가득 차면 에이전트가 엉뚱한 곳에 집중하기 시작합니다. 토큰을 줄이는 것은 비용 절감이기도 하지만, 에이전트가 실제로 필요한 것에 집중하게 만드는 작업이기도 합니다.