Claude Code 서브에이전트에 사용량이 새는 이유와 해결법, Cursor 토큰 절약법까지 (2026)

Claude Code에서 서브에이전트를 여러 개 띄워 두면 에이전트 패널에 "파일 읽는 중" 같은 짧은 상태 문구가 붙습니다. 이 몇 단어를 만들려고 대화 전체를 모델에 계속 다시 보낸다는 분석이 10월 말 해커뉴스에서 화제가 됐습니다. 이 글은 그 문제를 짧게 정리하고, Claude Code와 Cursor에서 바로 쓸 수 있는 토큰 절약법을 공식 문서 기준으로 모았습니다. 확인 기준일은 2026년 11월 6일입니다.

1. 문제 요약: 상태 문구 하나에 대화 전체를 다시 보낸다

Flamerix 팀의 분석 gist에 따르면, 백그라운드 에이전트가 일하는 동안 Claude Code는 약 30초마다 그 에이전트의 대화 기록 전체를 모델(보통 Opus)에 보내 "최근 행동을 3~5단어로" 요약받습니다. 내부 이름은 agent_summary이고, gist는 2.1.232 버전(2026년 8월)부터 기본으로 켜져 있다고 적었습니다. 이 요청은 디스크의 세션 로그에 남지 않아서 로컬 기록을 읽는 사용량 도구로는 보이지 않습니다.

Flamerix gist의 측정표: agent_summary가 추정 비용의 16.4%로 메인 대화(15.7%)보다 많았다

• gist에 실린 한 팀의 일주일 기록: 추정 비용의 16.4%, 전체 요청의 19.7%가 이 요약(메인 대화는 15.7%)
• GitHub 이슈 #86879: 서브에이전트 27개를 쓴 4시간 세션에서 요청의 22.7%, 가중 토큰 약 18%
• 해커뉴스에서 Claude Code 팀 엔지니어가 밝힌 전체 사용자 평균: 비용의 약 2%, 터미널 사용자 약 6%(Soba Labs 정리 인용)

8월에 처음 제기된 GitHub 이슈 #86879: 서브에이전트 27개 세션에서 요청의 22.7%가 상태 요약

두 숫자는 모순이 아닙니다. 에이전트를 여러 개, 오래 돌릴수록 비율이 커집니다. 혼자 대화만 하면 거의 0이고, 병렬 에이전트를 많이 쓰는 팀은 15%를 넘깁니다. 여기서 비용은 청구서가 아니라 Claude Code가 계산한 추정치이고, 구독 요금제라면 사용 한도가 그만큼 빨리 닳는다는 뜻입니다.

16.4%와 2%가 동시에 맞는 이유를 정리한 Soba Labs 분석

2. Claude Code에서 바로 쓰는 해결법

요약만 따로 끄는 공식 설정은 아직 없습니다. 그래서 순서대로 아래를 해 보시길 권합니다. 1~3단계는 대가가 거의 없고, 4단계부터는 기능을 일부 포기합니다.

1단계: 최신 버전으로 업데이트

Anthropic 엔지니어는 캐시를 놓친 요약이 비싸지는 문제를 2.1.311에서 고쳤다고 밝혔습니다(Soba Labs 정리 인용). 요약 호출 횟수는 그대로지만 한 번당 부담이 줄어드는 쪽입니다. claude --version으로 버전부터 확인하세요.

2단계: /usage로 어디서 새는지 먼저 보기

공식 비용 관리 문서에 따르면 구독 요금제에서 /usage를 실행하면 최근 사용량을 스킬, 서브에이전트, 플러그인, MCP 서버별 비율로 보여 주고, 최근 사용량의 10% 이상을 차지하는 행동에는 개선 추천을 붙여 줍니다. d/w로 24시간과 7일을 바꿔 볼 수 있고, 2.1.305 이상에서는 f를 눌러 적용 가능한 추천을 바로 실행할 수 있습니다. 서브에이전트 비율이 크게 나오면 아래 단계가 효과를 볼 가능성이 높습니다. 다만 이 수치는 로컬 세션 기록 기반이라, 로그에 안 남는 agent_summary까지 다 잡힌다고 보장할 수는 없습니다.

3단계: 동시에 돌리는 에이전트 수와 모델 줄이기

요약은 백그라운드 에이전트마다 따로 돕니다. 에이전트가 10개면 요약도 10갈래로 돕니다. 공식 문서도 서브에이전트는 메인 대화와 별개로 요청을 보낸다고 설명하고, 서브에이전트 비용을 줄이려면 더 작은 모델을 지정하라고 권합니다(단순한 일은 서브에이전트 설정에 model: haiku). 끝난 에이전트는 바로 정리하고, 정말 병렬이 필요한 일만 나눠 주세요.

4단계: 포크 모드 끄기 (CLAUDE_CODE_FORK_SUBAGENT=0)

공식 환경 변수 문서에 있는 설정입니다. 모든 세션에 적용하려면 ~/.claude/settings.json의 env에 넣습니다.

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

이번 세션에만 쓰고 싶다면 터미널에서 이렇게 실행하면 됩니다.

CLAUDE_CODE_FORK_SUBAGENT=0 claude

대가: 서브에이전트가 지금까지의 대화를 물려받지 않고, 맡은 일 설명만 듣고 시작합니다. 앞에서 정한 규칙이 중요하다면 작업을 넘길 때 설명을 조금 더 자세히 적어 주세요. gist는 이 설정으로 요약 호출이 멈춘다고 적었지만, 공식 문서에 그렇게 쓰여 있지는 않으니 다음 절의 방법으로 직접 확인하는 걸 권합니다.

공식 환경 변수 문서의 CLAUDE_CODE_FORK_SUBAGENT 항목 (0으로 포크 모드 끄기)

5단계(최후 수단): 백그라운드 작업 끄기 (CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1)

{
  "env": {
    "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1"
  }
}

대가가 큽니다. 백그라운드 서브에이전트와 Ctrl+B로 작업을 뒤로 보내는 기능 전체를 잃습니다. 병렬 작업을 거의 안 쓰는데 한도가 유난히 빨리 닳는 분에게만 맞습니다.

함께 하면 좋은 기본 습관 (공식 문서 권장)

• 관계없는 일로 넘어가면 /clear: 오래된 맥락이 이후 모든 메시지에 실려 갑니다. 문서는 새로 시작하는 게 목적이면 /clear는 비용이 들지 않지만, /compact는 요약하려고 대화를 읽으니 그 자체가 큰 요청이라고 설명합니다.
• 대부분은 Sonnet, Opus는 복잡한 설계에만: Opus로 바꾸면 세션 모델을 물려받는 서브에이전트도 같이 바뀝니다.
• 안 쓰는 MCP 서버는 /mcp에서 끄기, /context로 무엇이 자리를 차지하는지 확인하기. gh 같은 CLI가 있으면 MCP보다 맥락을 덜 씁니다.
• CLAUDE.md는 200줄 이하로: 특정 작업용 지침은 필요할 때만 불러오는 스킬로 옮기세요.
• 단순 작업은 생각 강도 낮추기: /effort로 조절할 수 있습니다. 생각 토큰은 출력 토큰으로 계산됩니다.

서드파티 스크립트는 신중하게: Flamerix gist에는 요약 타이머만 막는 Bun preload 스크립트(MIT)도 있습니다. 포크 기능은 살릴 수 있지만 남이 만든 코드가 코딩 에이전트와 같이 돌고, 업데이트 때 조용히 무력화될 수 있습니다. 쓴다면 내용을 다 읽고, 받은 파일을 고정해 두고, 효과를 계속 측정하세요.

3. Cursor에서 토큰 아끼는 법

Cursor의 에이전트도 원리는 같습니다. Cursor 공식 문서는 채팅마다 정해진 크기의 맥락 창을 모델과 함께 쓰고, 파일을 붙이고 도구를 돌리고 메시지를 주고받을수록 그 창이 찬다고 설명합니다. 결국 매 요청에 실려 가는 양을 줄이는 것이 핵심입니다.

① 맥락 링으로 무엇이 자리를 차지하는지 보기

입력창 옆의 맥락 링(context ring)을 누르면 사용 중인 토큰이 시스템 프롬프트, 도구, 규칙(Rules), 스킬, MCP, 서브에이전트, 요약된 대화, 대화로 나뉘어 보입니다(Prompting agents 문서). 아래 방법 중 무엇부터 할지 여기서 정하면 됩니다.

Cursor 공식 문서의 Context usage 항목: 맥락 링을 누르면 규칙·MCP·대화 등 항목별 토큰이 보인다

② 필요한 파일만 @로 붙이기

@auth.ts, @src/components/처럼 파일이나 폴더를 직접 지정할 수 있습니다. 공식 문서는 관련 파일을 알 때만 @를 쓰고, 모르겠으면 생략하라고 합니다. 그러면 에이전트가 스스로 검색해서 필요한 파일을 찾습니다. 큰 폴더를 통째로 붙이는 것보다 맥락을 덜 씁니다.

③ 규칙(Rules)은 짧게, 필요할 때만 붙게

Rules 문서에 따르면 적용된 규칙 내용은 모델 맥락 맨 앞에 들어갑니다. 즉 Always Apply 규칙은 모든 채팅에 매번 실립니다. 그래서 이렇게 해 보세요.

• 항상 필요한 것만 alwaysApply: true로 두고, 나머지는 globs(특정 파일에만)나 description(에이전트가 필요할 때 판단)으로 바꾸기
• 공식 권장대로 규칙은 500줄 이하로, 큰 규칙은 여러 개로 쪼개기
• 스타일 가이드 전체나 코드 내용을 복사해 넣지 말고 @파일명으로 가리키기. 문서는 규칙 안의 파일 언급은 내용이 프롬프트에 그대로 들어가지 않고, 에이전트가 필요할 때 읽는다고 설명합니다.

---
globs: src/components/**/*.tsx
alwaysApply: false
---
- 컴포넌트는 named export
- 구조는 @component-template.tsx 참고

④ 안 쓰는 MCP 서버 끄기

맥락 링 항목에 MCP가 따로 있을 만큼, 연결된 MCP 서버의 안내문과 도구 목록은 맥락을 차지합니다. MCP 문서에 따르면 사이드바의 Customize에서 서버별 토글로 지우지 않고 끌 수 있고, 꺼진 서버는 로드되지 않으며 채팅에도 나타나지 않습니다. 이 프로젝트에서 안 쓰는 서버부터 꺼 보세요.

Cursor MCP 문서의 FAQ: Customize에서 MCP 서버를 삭제하지 않고 끌 수 있다

⑤ .cursorignore로 상관없는 파일 빼기

Ignore file 문서에 따르면 프로젝트 루트의 .cursorignore에 적은 파일은 Agent·Tab과 @ 언급에서 막힙니다. 큰 코드베이스나 모노레포에서 관련 없는 부분을 빼면 파일 찾기가 더 정확해진다고 설명합니다. .gitignore에 있는 파일과 node_modules/, 락 파일, 이미지 등은 이미 기본으로 빠지니, 그 외에 빌드 결과물이나 큰 데이터 폴더를 추가하면 됩니다.

# .cursorignore
dist/
**/logs
fixtures/large-data/

참고로 문서는 에이전트가 쓰는 터미널과 MCP 도구는 .cursorignore를 막지 못한다고 적어 두었습니다.

⑥ 일에 맞는 모델 고르기

Cursor Usage and limits 도움말은 어떤 요금제든 모델 선택이 포함 사용량이 닳는 속도를 좌우한다고 적고 있습니다. 공식 문서도 빠른 모델은 간단한 수정과 반복 작업에, 더 강한 모델은 복잡한 추론과 여러 파일 리팩터링에 맞다고 안내합니다. 기본 모델은 Cursor Settings > Models에서 정할 수 있습니다. 모델별 단가는 Models & Pricing 표에서 확인하세요. 같은 문서들에 따르면 Max Mode는 이제 예전 요청 기반(legacy) 요금제에만 있고, 기본 맥락 창보다 큰 맥락이 필요할 때만 쓰라고 권합니다.

⑦ 복잡한 일은 Plan Mode로 먼저 계획

Plan Mode 문서에 따르면 입력창에서 Shift+Tab으로 전환하면 에이전트가 코드를 쓰기 전에 질문하고 조사해 계획을 만듭니다. 결과가 원하던 것과 다르면 후속 프롬프트로 고치기보다 변경을 되돌리고 계획을 다듬어 다시 실행하는 편이 더 빠르다고 안내합니다. 엉뚱한 방향으로 오래 고치느라 쓰는 토큰을 줄이는 방법입니다. 간단한 수정은 바로 Agent로 해도 된다고 합니다.

⑧ 일이 바뀌면 새 채팅

공식 문서는 맥락 창이 거의 차면 Cursor가 오래된 대화를 요약해 압축한다고 설명합니다. 압축 전까지는 긴 대화가 매 요청에 실려 갑니다. Cursor 포럼의 팀 답변들은 새 작업은 새 채팅에서 시작하라고 거듭 권하고, 이전 맥락이 필요하면 @Chats로 예전 대화를 참조할 수 있습니다(공식 문서). Cursor CLI에는 /clear(새 세션)와 /summarize(대화 압축) 명령이 있습니다(CLI 슬래시 명령 문서).

4. 두 도구에 같이 통하는 체크리스트

습관	Claude Code	Cursor
일이 바뀌면 새로 시작	/clear	새 채팅, CLI는 /clear
무엇이 맥락을 차지하는지 보기	/context, /usage	맥락 링 클릭
항상 실리는 지침 줄이기	CLAUDE.md 200줄 이하, 나머지는 스킬로	Always 규칙 최소화, globs·description 활용
안 쓰는 MCP 끄기	/mcp	Customize의 서버 토글
모델을 일에 맞추기	기본 Sonnet, 서브에이전트는 작은 모델	간단한 일은 빠른 모델
병렬 에이전트는 꼭 필요할 때만	백그라운드 에이전트 수 줄이기	서브에이전트도 별도 요청
필요한 것만 붙이기	구체적으로 파일·함수 지정	아는 파일만 @, 모르면 에이전트 검색

한 가지 더: Cursor 도움말에 따르면 서브에이전트는 선택기에 Auto나 Composer가 보이더라도 이름이 지정된 서드파티 모델로 돌 수 있고, 그 요청은 서드파티 사용량으로 계산됩니다. 두 도구 모두 서브에이전트가 어떤 모델로 도는지 한 번 확인해 두세요.

5. 효과는 직접 재 보기

Claude Code: 간단히는 /usage, 자세히는 공식 모니터링 문서대로 OpenTelemetry를 켜고 일주일쯤 모은 뒤, claude_code.api_request 이벤트를 query_source로 묶어 cost_usd를 더해 보세요. 위 환경 변수를 켜기 전후를 비교하면 됩니다.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

공식 문서의 예시 값 목록에는 agent_summary라는 이름이 나오지 않으니, 내 데이터에서 실제 값을 먼저 확인하세요.

Cursor: Usage and limits 도움말에 따르면 예전 Cursor 요금제는 대시보드의 Spending 탭에서 실시간 사용량과 남은 한도를, X 구독 요금제는 grok.com/dashboard의 Usage에서 주간 사용량과 초기화 날짜를 볼 수 있습니다. 요청별 비용은 사용량 대시보드에서 확인하라고 안내합니다. 규칙 하나, MCP 서버 하나를 끌 때마다 맥락 링 숫자가 어떻게 바뀌는지 보는 것도 간단한 측정법입니다.

정리: 무엇부터 해 볼까

대화 하나로만 쓰는 분이라면 agent_summary는 신경 쓸 일이 거의 없고, 새 작업은 새로 시작하기, 항상 실리는 지침 줄이기, 안 쓰는 MCP 끄기만으로도 충분합니다. 서브에이전트를 여러 개 오래 돌리는 분이라면 업데이트하고 /usage로 서브에이전트 비율을 본 뒤, 크면 에이전트 수를 줄이거나 CLAUDE_CODE_FORK_SUBAGENT=0을 시험해 보세요. Cursor를 함께 쓴다면 오늘 맥락 링을 한 번 눌러 보는 것부터 시작하면 됩니다.

참고: 민둥이 | 쉽게 배우는 AI 영상에서 주제를 얻었고, 내용은 Flamerix gist, GitHub 이슈 #86879, Claude Code 비용 관리·환경 변수·모니터링 문서, Cursor 공식 문서로 확인했습니다. 수치는 특정 팀·세션의 측정값이라 환경마다 다를 수 있고, 환경 변수 효과는 직접 시험한 결과가 아닙니다.