Claude Code를 비롯한 AI 코딩 에이전트(AI Coding Agent)를 사용하다 보면, "토큰 소비를 줄이려면?"이라는 팁(Tips)들이 세상에 아주 많이 널려 있습니다. "CLAUDE.md를 짧게 만들자", "/clear를 하자", "서브 에이전트(Sub-agent)를 사용하자". 모두 틀린 말은 아니지만, 팁을 무턱대고 모으기만 하면 다음과 같은 문제가 발생하기 쉽습니다.

• 왜 그것이 효과적인지 모른 채 도입하게 된다
• 역효과가 나는 케이스(예: 서브 에이전트의 남용)를 알아차리지 못한다
• 자신의 워크로드(Workload)에 어떤 팁이 적합한지 우선순위를 정할 수 없다

그래서 본 기사에서는 "무엇이 토큰 비용을 발생시키고 있는가"라는 원인(발생 요인)에서 출발하여, 대책을 세우는 접근 방식을 취합니다. Anthropic 공식 문서, AWS 공식 리포지토리(Repository)의 구현을 실제로 조사하여 근거를 확인하며 정리했습니다. 기재 내용에는 확실도에 따라 라벨을 붙였습니다.

• Anthropic 공식 검증됨 — Anthropic 공식 문서(code.claude.com/docs)에 직접적인 기재·인용이 있는 내용
• AWS 실례 — AWS 공식 리포지토리(awslabs/agent-plugins) 고유의 운용 기준. Anthropic 공식 사양이 아님

먼저 전체상입니다. 토큰 비용의 발생 요인은 "언제·왜 발생하는가"에 따라 크게 5가지로 분류할 수 있습니다.

각 카테고리에는 구체적인 비용 요인이 여러 개 달려 있습니다. 상세한 해설에 들어가기에 앞서, 먼저 모든 항목을 일람표로 정리합니다.

이하, 각각을 구체적으로 살펴보겠습니다.

여기서부터는 Anthropic 공식 문서(code.claude.com/docs)에 직접적인 기재·인용이 있는 내용을 중심으로 살펴보겠습니다.

CLAUDE.md·MCP 툴 목록·Skill의 설명문 등은 해당 턴에서 사용하든 사용하지 않든 매번 컨텍스트에 읽혀집니다. Anthropic 공식 문서에도 명시되어 있습니다.

"If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work."

——code.claude.com/docs/en/costs.md

【대책】

• CLAUDE.md는 200행 이내를 기준으로, 본질적인 내용으로만 압축한다
• 상시 필요하지 않은 절차적인 내용(PR 리뷰 절차, 마이그레이션 절차 등)은 CLAUDE.md에 쓰지 않고, Skills로 분리한다 (상세 내용은 Skills의 구조를 참조)
• MCP 툴은 미사용 서버를 /mcp로 무효화한다. 툴 정의는 기본적으로 지연 로드(Lazy Load)되므로, 사용하지 않는 툴은 실제로 호출하기 전까지 스키마(Schema)가 로드되지 않는다

(주의점) CLAUDE.md는 세션 시작 시 한 번만 읽혀 메모리 상에 유지됩니다. 세션 중에 편집해도 캐시는 무효화되지 않지만, 대신 "편집 내용이 해당 세션에는 반영되지 않는다"는 점에 주의가 필요합니다.

세션 중에 편집해도 캐시는 무효화되지 않지만, 대신 "편집 내용이 해당 세션에는 반영되지 않는다"는 점에 주의가 필요합니다. Claude는 세션 시작 시 로드된 버전을 사용하여 계속 작업을 수행합니다.

——code.claude.com/docs/en/prompt-caching.md

새로운 내용이 로드되는 시점은 다음의 /clear,

・/compact

・재시작 시점입니다. "CLAUDE.md를 수정했는데 반영되지 않았다"와 같은 불필요한 대화를 피하기 위해, 이 사양을 숙지해 두는 것은 가치가 있습니다.

Claude Code는 스테이트리스(Stateless)이며, 매 메시지마다 대화 전체를 다시 전송합니다. 단 한 줄의 질문이라도, 그때까지의 대화 전체 비용이 부과됩니다.

"Claude Code는 매 메시지마다 전체 대화를 전송하므로, 하루 종일 열려 있었던 세션에서의 한 줄짜리 질문은 단 한 줄이 아니라 대화 전체에 대한 토큰을 사용합니다."

——code.claude.com/docs/en/costs.md

【대책】

• 무관한 작업에 들어가기 전에는 /clear로 완전히 리셋한다. 연속성이 필요 없다면 /clear는 실행 비용이 제로(아무것도 읽지 않고 단순히 폐기할 뿐)입니다. 실제로 Anthropic은 고액 청구의 전형적인 원인으로 "클리어되지 않은 장시간 세션"을 명시적으로 꼽고 있습니다.
  "API 또는 클라우드 제공업체 플랜에서의 예상치 못한 높은 지출: 대개 클리어되지 않은 장시간 세션이나 Opus가 기본 모델로 설정된 경우로 거슬러 올라갑니다."

• 클리어로 대화를 잃고 싶지 않다면, /rename을 한 뒤에 클리어하면 나중에 /resume으로 돌아올 수 있습니다.

여기서부터는 특정 행동이나 지시로 인해 "본래 불필요했을 토큰"이 발생하는 케이스입니다.

기존의 절차나 구조가 어디에도 명시되어 있지 않으면, Claude는 매번 파일을 뒤져가며 재발견해야 하는 상황에 처하게 됩니다.

"스킬(Skill)은 Claude에게 도메인 지식(Domain knowledge)을 제공하여 탐색할 필요가 없게 만들 수 있습니다. 예를 들어, 'codebase-overview' 스킬은 프로젝트의 아키텍처, 주요 디렉토리, 명명 규칙(Naming conventions)을 설명할 수 있습니다. Claude가 이 스킬을 호출하면, 구조를 이해하기 위해 여러 파일을 읽으며 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻게 됩니다."

——code.claude.com/docs/en/costs.md

【대책】

정형화된 절차나 프로젝트 구조에 대한 지식을 스킬(Skill)로서 명시적으로 제공한다 (자세한 내용은 Skills 구조를 참조).

거대한 로그 파일이나 가공되지 않은 JSON 응답 등, 필요한 정보 이상의 출력이 그대로 컨텍스트에 포함되어 버리는 케이스입니다.

"Claude가 에러를 찾기 위해 10,000줄짜리 로그 파일을 읽는 대신, 훅(Hook)을 사용하여 ERROR를 grep하고 일치하는 줄만 반환하게 함으로써, 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다."

——code.claude.com/docs/en/costs.md

【대책】

PreToolUse 훅을 사용하여, Bash 명령어가 실행되기 전에 명령어 문자열 자체를 다시 써서 필터링 처리가 포함된 명령어로 교체한다. PreToolUse는 실행 전에 트리거되므로 tool_output(실행 결과)은 받을 수 없지만, tool_input

（실행하려는 명령）은 재작성 가능(hookSpecificOutput.updatedInput)합니다. 이를 이용해, 예를 들어 npm test를 npm test 2>&1 | grep -E 'FAIL|ERROR' | head -100와 같은 파이프가 포함된 명령으로 교체한 뒤 실행하게 함으로써, Claude에게 전달되는 시점의 출력(실행 후의 결과) 자체를 이미 압축된 상태로 만들 수 있습니다(costs.md).

{
"hooks": {
"PreToolUse": [
...

테스트 명령의 출력을 실패한 행으로만 제한하는 훅(hook) 등이 전형적인 예시입니다. 실제로 공식 문서의 샘플 스크립트도 테스트 명령인지 여부를 판정하고, 명령 문자열에 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100를 추가한 뒤 updatedInput.command로 교체하는 방식으로 구현되어 있습니다.

"'이 코드베이스를 개선해줘'와 같은 모호한 요청은 광범위한 스캐닝을 유발합니다. 'auth.ts의 login 함수에 입력 유효성 검사를 추가해줘'와 같은 구체적인 요청은 Claude가 최소한의 파일 읽기로 효율적으로 작업할 수 있게 합니다."

——code.claude.com/docs/en/costs.md

【대책】

대상 파일·함수명을 구체적으로 지정하는 등 모호함을 줄인 프롬프트를 작성한다. 당연한 이야기 같지만, 공식 측에서 명시적으로 "토큰 비용의 요인"으로 언급하고 있다는 점은 유념할 가치가 있습니다.

구현의 방향성을 잘못 잡으면 지금까지의 작업이 모두 재작업이 됩니다.

"Claude는 코드베이스를 탐색하고 승인을 위한 접근 방식을 제안함으로써, 초기 방향이 틀렸을 때 발생하는 비용이 많이 드는 재작업을 방지합니다."

——code.claude.com/docs/en/costs.md

【대책】

• Plan mode (Shift+Tab으로 전환)에서 먼저 승인을 받은 후 구현에 들어간다.
• 방향성이 어긋나면 즉시 Escape로 중단하고, /rewind로 되돌린다.
• 테스트 케이스나 기대하는 출력을 사전에 제시하여 Claude 스스로 검증할 수 있도록 한다.
• 파일 1개를 작성하고 테스트, 다시 파일 1개를 작성하고 테스트하는 식으로 단계적으로 진행한다.

(보충) /rewind는 /compact보다 캐시 효율 측면에서도 유리합니다. /compact는 대화 이력을 새로운 요약으로 교체하기 때문에 새로운 프리픽스(prefix)를 다시 만들어야 하지만, /rewind는 이미 캐시된 과거 시점까지 대화를 자르기만 하므로 해당 프리픽스는 기존 캐시를 그대로 재사용할 수 있습니다.

"Rewinding은 compaction이 하는 것처럼 새로운 것을 구축하는 대신, 이미 캐시된 프리픽스까지 되돌립니다."

——code.claude.com/docs/en/prompt-caching.md

"잘못된 방향으로 가면 /compact가 아니라 /rewind를 사용한다"는 재작업 방지와 과금 측면 모두에서 합리적입니다.

Extended thinking은 기본적으로 활성화되어 있으며, thinking 토큰은 출력 토큰으로 과금됩니다. 기본 예산은 모델에 따라 수만 토큰에 달할 수 있습니다.

"Extended thinking은 복잡한 계획 및 추론 작업에서 성능을 크게 향상시키기 때문에 기본적으로 활성화되어 있습니다. Thinking 토큰은 출력 토큰으로 과금되며, 기본 예산은 모델에 따라 요청당 수만 토큰에 이를 수 있습니다."

——code.claude.com/docs/en/costs.md

【대책】

깊은 추론 (Deep Reasoning)이 필요하지 않은 단순 작업에서는 /effort로 effort 레벨을 낮추거나, /config로 thinking을 비활성화하거나, 고정된 thinking budget을 가진 모델에서는 환경 변수 MAX_THINKING_TOKENS (예: MAX_THINKING_TOKENS=8000)로 예산을 제한하는 등의 조정이 가능합니다.

(보충) Extended thinking에 국한되지 않고, 출력 토큰 (Output Token)은 입력 토큰 (Input Token)보다 단가가 높게 설정되어 있습니다. 예를 들어 Claude Sonnet 5는 입력 $2 / 출력 $10 (2026년 8월 31일까지의 도입 가격. 이후에는 입력 $3 / 출력 $15로 이행 예정), Opus 5는 입력 $5 / 출력 $25 (모두 1M 토큰당)로, 어떤 가격대에서도 출력은 입력의 5배입니다 (공식 Pricing 페이지). 즉, thinking의 유무와 상관없이 Claude 자신의 응답이 장황해지는 것 자체가 비용과 직결됩니다. 게다가 멀티 턴 (Multi-turn) 대화에서는 특정 회차의 장황한 응답이 그대로 다음 턴 이후의 입력 토큰으로 재전송되어 계속 유지되기 때문에, 응답의 길이는 '그 시점의 출력 비용'과 '이후의 입력 비용 팽창' 모두에 영향을 미칩니다. CLAUDE.md나 /output-style로 간결한 응답을 유도하는 지시를 내리는 것은 이러한 단가의 비대칭성을 고려했을 때 합리적인 대책이라고 할 수 있습니다.

(B6. 도구 왕복 비용에 대해서는 AWS 공식 리포지토리의 실례에 기반한 내용이므로, 제2부 「구체적인 수치 기준」에서 정리하여 해설하겠습니다.)

Claude Code는 기본적으로 프롬프트 캐싱 (Prompt Caching)을 자동으로 관리합니다. 모델 전환·설정 변경, 그리고 캐시의 TTL (구독 시 1시간, API 키 사용 시 5분)을 초과하는 간격으로 세션을 재개하는 등의 상황에서 프리픽스 (Prefix)가 변경되어 이후부터는 전액 과금됩니다.

"Cache misses: your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context."

——code.claude.com/docs/en/costs.md

【대책】

API 키, Bedrock, Google Cloud, Microsoft Foundry, Claude Platform on AWS 이용 시 (기본 TTL 5분)에는 환경 변수 ENABLE_PROMPT_CACHING_1H=1을 설정하면 TTL을 1시간으로 연장할 수 있습니다 (캐시 쓰기 단가는 높아지지만, 긴 간격에서의 캐시 미스 (Cache Miss)를 방지할 수 있음). 또한, 공식 문서에서는 다음과 같이 명확하게 권장하고 있습니다.

"Pick your model and effort level at the top of a session, then save /compact for natural breaks between tasks. The fewer changes you make mid-task, the higher your cache hit rate."

——code.claude.com/docs/en/prompt-caching.md

즉, 모델과 effort 레벨은 세션 시작 시 결정하고 도중에 바꾸지 않으며, /compact는 태스크의 구분점에서 실행한다 (자동 컴팩션에 맡기지 않는다)와 같이, '캐시를 무효화하는 조작'을 작업 도중에 의식적으로 피하는 것이 공식적으로 뒷받침된 대책이 됩니다 (기타 무효화 트리거: fast mode 전환, MCP 서버 연결 변경, 도구 전체 거부 규칙 추가, Claude Code 업그레이드 등).

이는 간과하기 쉽지만, /compact는 공짜가 아닙니다.

"/compact reads the conversation it summarizes, so compacting a large context is itself a large request. When you want a fresh start instead of continuity, /clear costs nothing."

——code.claude.com/docs/en/costs.md

「컨텍스트 사용률이 ◯%가 되면 /compact

」라는 구체적인 임계값은 사실 공식 문서 어디에도 존재하지 않습니다. 대신 Claude Code에는 최대 입력 사이즈에 가까워지면 자동으로 요약하는 메커니즘(자동 컴팩션 (Automatic Compaction))이 있습니다.

【대책】

• 지속성이 필요 없다면 /compact (비용 발생)보다 /clear (무료)가 합리적이라는 판단 기준이 공식적으로 제시되어 있음 - 수동 /compact는 "자동 컴팩션에 맡길 것인가" 아니면 "/compact [focus]를 통해 능동적으로 요약 내용을 제어할 것인가"의 선택이 됩니다.

여러 개의 Claude Code 인스턴스를 실행하는 Agent teams 기능(실험적 기능, 기본값 비활성화)에서는 각 팀원이 독립적인 풀 컨텍스트 윈도우 (Full Context Window)를 가집니다.

"Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance."

——code.claude.com/docs/en/costs.md

약 7배라는 숫자는 임팩트가 큽니다. costs.md에는 이 중복 비용을 억제하기 위한 전용 섹션이 마련되어 있습니다.

"To keep agent team costs manageable: Use Sonnet for teammates... Keep teams small... Keep spawn prompts focused... Shut down teammates when their work is done."

——code.claude.com/docs/en/costs.md

【대책】

• 팀원으로는 Sonnet을 사용한다 (코디네이션 태스크에는 비용과의 밸런스가 좋음)
• 팀 규모를 작게 유지한다 (토큰 소비는 팀 규모에 거의 비례함)
• spawn 프롬프트를 가볍게 한다 (CLAUDE.md/MCP/skills는 자동 로드되므로, spawn 프롬프트에 작성한 내용이 그대로 컨텍스트에 추가로 얹어짐)
• 작업 완료 후에는 신속하게 종료시킨다 (가동 중인 팀원은 종료하거나 세션이 끝날 때까지 토큰을 계속 소비함)

--resume용 대화 요약 작업, /usage 상태 확인, 스케줄 태스크의 정기적 실행 등이 세션이 유휴(Idle) 상태일 때도 발생합니다. 1세션당 통상 $0.04 미만으로 영향은 작지만, 존재 자체는 알고 있는 것이 좋습니다.

【대책】

영향이 작으므로 적극적인 대책은 불필요합니다. 이러한 배경 비용이 존재한다는 것을 파악해 두는 정도로 충분합니다.

이 부분이 본 기사에서 가장 강조하고 싶은 포인트입니다. "Skills를 사용하자", "서브 에이전트(Sub-agent)에게 맡기자"라는 조언을 자주 접하지만, 단발성 호출만 놓고 보면 오히려 토큰이 늘어나는 경우가 많다는 것이 정확한 이해입니다.

서브 에이전트는 부모의 캐시를 승계하지 않습니다 (콜드 스타트 (Cold Start)). 따라서 다음과 같은 비용이 발생합니다.

• 시스템 프롬프트 분량의 토큰을 처음부터 소비함
• "원래 출력을 읽기" + "요약을 작성하기" + "그 요약을 부모가 읽기"라는 공정이 늘어남
• 기동 오버헤드(Startup Overhead)는 서브 에이전트 자신의 대화 전체가 새로 발생하는 만큼 발생함

절감 효과가 나타나는 것은 단발 호출이 아니라, 세션 전체 및 장기적인 관점입니다. 장황한 출력을 메인 대화에 남겨두면, 이후의 모든 턴에서 그만큼이 누적 비용으로 계속 따라붙습니다 (A2). 서브 에이전트로 격리하면 메인 스레드는 요약분만으로 충분하며, 캐시 히트율(Cache Hit Rate)도 유지하기 쉬워집니다. 본질적인 가치는 "탐색 작업 그 자체를 싸게 만드는 것"이 아니라, "그 이후의 대화가 길어졌을 때의 복리적인 비대화를 방지하는 것"입니다.

적합한 경우: 대규모 코드베이스 탐색, 대량 로그 처리 등 원본 출력이 거대하여 메인에 남기고 싶지 않은 일회성 작업. 병렬화가 가능한 독립적인 태스크.

적합하지 않은 경우: 간단한 확인, 메인 대화와 밀접한 상호작용이 필요한 태스크 (콜드 스타트 + 요약 왕복의 오버헤드가 더 높게 책정됨).

참고로, 일반적인 서브 에이전트는 구독 이용 시에도 항상 5분 TTL의 캐시가 적용됩니다 (메인 대화에 적용되는 1시간 TTL 자동 연장은 적용되지 않음).

"서브 에이전트 (Subagents)는 구독 이용 시에도 5분 TTL을 사용합니다. 자동 1시간 TTL은 메인 대화에만 적용되기 때문입니다."

——code.claude.com/docs/en/prompt-caching.md

(보충) 「콜드 스타트 (Cold Start)를 피하고 싶지만, 격리도 하고 싶은」 경우의 예외로서 /subtask

(구 /fork)라는 「포크 (Fork)」 기능이 있습니다. 포크는 대화 기록, 시스템 프롬프트 (System Prompt), 도구 (Tool), 모델을 메인 세션으로부터 그대로 물려받는 서브 에이전트로, 첫 번째 요청이 메인 대화의 프롬프트 캐시 (Prompt Cache)를 그대로 재사용할 수 있습니다 (=콜드 스타트가 발생하지 않음). 결과만 메인으로 반환되며, 포크 자체의 도구 호출은 메인 대화에 남지 않기 때문에, "배경 설명 없이 요청할 수 있으면서도" 동시에 "메인 대화를 더럽히지 않는" 것을 양립할 수 있습니다. 다만 일반적인 서브 에이전트와 달리, 포크는 독자적인 시스템 프롬프트나 도구 제한을 가질 수 없다는 점이 트레이드오프 (Trade-off)입니다.

"포크의 시스템 프롬프트와 도구 정의는 부모와 동일하기 때문에, 첫 번째 요청이 부모의 프롬프트 캐시를 재사용합니다. 이는 동일한 컨텍스트 (Context)가 필요한 작업의 경우, 새로운 서브 에이전트를 생성하는 것보다 포크를 사용하는 것이 더 저렴합니다."

——code.claude.com/docs/en/sub-agents.md

Skills 또한 CLAUDE.md와 달리, 본문은 "사용될 때까지 로드되지 않는" 점진적 공개 (Progressive Disclosure) 메커니즘을 가집니다.

"CLAUDE.md 내용과 달리, 스킬 (Skill)의 본문은 사용될 때만 로드되므로, 긴 참조 자료는 필요할 때까지 비용이 거의 들지 않습니다."

——code.claude.com/docs/en/skills.md

즉, Skill이 발화하는 순간의 비용은 그 내용을 CLAUDE.md에 직접 작성했을 때와 큰 차이가 없습니다. 이득을 보는 지점은 "해당 Skill을 사용하지 않는 세션"에서 비용이 제로 (Zero)가 된다는 점입니다. 따라서 다음과 같이 구분하여 사용하는 것이 합리적입니다.

• 발생 빈도가 낮거나 특정 태스크 (Task)에서만 사용하는 절차 (PR 리뷰, 마이그레이션 절차 등)는 Skill화하는 것이 유효
• 거의 매 턴 사용하는 내용은 지연 로드 (Lazy Load)의 이점이 적으므로, 오히려 CLAUDE.md에 상주시키는 것이 합리적인 경우도 있음

Anthropic 공식 측에서도 정형 워크플로 (Workflow)를 분리할 대상으로 Skills를 명확히 권장하고 있습니다.

"지침을 CLAUDE.md에서 skills로 이동시키세요... 필수적인 내용만 포함하여 CLAUDE.md를 200행 미만으로 유지하는 것을 목표로 하세요."

——code.claude.com/docs/en/costs.md

정형 작업이 Skills와 궁합이 좋은 이유는 3가지가 있습니다.

• 지연 로드와의 궁합 (빈번하지만 항상 있는 것은 아니라는 사용 빈도 패턴에 부합)
• 탐색 비용의 절감 (B1에서 언급했듯이, Skill이 있으면 매번 파일을 뒤질 필요가 없음)
• 일관성에 의한 재작업 감소 (절차가 명시되어 있으면, Claude가 매번 다른 접근 방식을 시도하여 수정이 발생하는 등의 낭비가 줄어들 가능성이 높음)

여기서부터는 AWS가 공개한 Agent Skills 모음 리포지토리 awslabs/agent-plugins에서 얻은 지식입니다. Anthropic 공식 사양이 아니라, AWS가 이 리포지토리를 위해 독자적으로 정한 운용 기준 및 설계 지침이라는 점에 다시 한번 주의해 주세요 (AWS 라벨).

Anthropic 공식 문서에도 SKILL.md의 크기에 대한 구체적인 수치 기준이 사실 존재합니다.

Anthropic 공식

"SKILL.md를 500행 미만으로 유지하세요. 상세한 참조 자료는 별도의 파일로 이동시키세요."

——code.claude.com/docs/en/skills.md

500행이라는 이 하나의 기준에 대해, AWS가 공개하고 있는 Agent Skills 모음 리포지토리 awslabs/agent-plugins는 더욱 운영 수준까지 깊이 들어간 기준을 가지고 있습니다 (이후부터는 AWS 고유의 운영 기준이며, Anthropic 공식 사양이 아닙니다).

이 리포지토리의 설계 철학은 다음 한 문장으로 집약됩니다.

AWS 사례

"Files should be SHORT and FOCUSED. Every token counts in an agent's context window."

——docs/DESIGN_GUIDELINES.md

그리고 CI에서 강제되는 크기 기준(tools/markdownlint-skill-length.cjs, 자체 lint 규칙 SKILL001)은 다음 표와 같습니다.