Claude Code 세션 속도 저하 및 비용 절감 방법

Claude Code 세션이 느려지고 비용이 증가하는 것을 방지하는 방법

Claude Code 세션이 길어지면 속도가 느려지고 비용이 증가합니다. 모든 턴마다 전체 context를 다시 전송하며, 해당 context는 계속해서 커지기 때문입니다. 해결 방법은 정해진 순서에 따라 관리하는 것입니다. 먼저 /context를 실행하여 무엇이 window를 채우고 있는지 확인하십시오. 매 요청마다 비용이 발생하는 항목을 삭제하십시오. 그 다음, 서로 관련 없는 작업 사이에는 /clear를 사용하고, 하나의 긴 작업 내에서는 지시어와 함께 /compact를 사용하십시오. 연속적인 작업 단위로 작업하십시오. Prompt cache가 해제되면 저렴한 read 작업이 모든 대화 내용을 다시 쓰는 full re-write 작업으로 전환됩니다.

비용이 발생하는 이유는 agent session의 token meter에서 확인할 수 있습니다.

변경 사항을 적용하기 전에 /context를 읽으십시오

창에 무엇이 포함되어 있는지 추측하지 마십시오. Claude Code가 알려줍니다.

/context [all]는 현재 context 사용량을 색상 그리드로 표시하며, context 사용량이 많은 도구와 메모리 팽창에 대한 최적화 제안을 제공합니다. all는 전체 화면 모드에서 항목별 상세 내역을 확장합니다. 결과값은 다섯 가지 범주로 해석하십시오.

• The system prompt. Claude Code 자체의 harness 지침입니다. 세션 동안 고정됩니다.
• Tool definitions. 연결된 모든 MCP (Model Context Protocol) 서버를 포함하여 에이전트가 호출할 수 있는 모든 도구의 schema입니다.
• Memory files. 세션 시작 시 로드되는 CLAUDE.md 및 auto memory입니다.
• Files and tool results. 읽은 모든 파일과 명령어가 출력한 모든 내용입니다.
• Message history. 사용자의 입력과 모델의 응답입니다.

처음 세 가지 항목은 세션이 유지되는 동안 모든 요청에 대해 발생하는 고정 비용입니다. 마지막 두 항목은 지속적으로 증가합니다. 세션 시작 시 고정 비용을 한 번 확인하고, 증가하는 항목은 지속적으로 관리하십시오.

다음 두 문자열은 window가 가득 찼음을 나타냅니다.

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

첫 번째는 하드 리미트(hard limit)이며, 이 경우 요청이 거부됩니다. 관련 API (application programming interface) 에러는 Prompt is too long입니다. 두 번째는 compaction window이며, 1 million token 모델의 경우 모델의 실제 context window보다 낮게 설정될 수 있습니다. 이 지점을 넘어도 요청은 성공하므로, 이는 거부가 아닌 경고입니다.

유료 플랜에서는 /usage가 나머지 절반을 추가로 제공합니다. 긴 context 또는 cache miss와 같은 동작을 표시하며, 최근 사용량을 개별 skill, subagent 및 MCP server별로 할당하여 보여줍니다.

CLAUDE.md는 영구적인 비용이므로 간결하게 유지하십시오

CLAUDE.md는 세션 시작 시 context에 로드되며 계속 유지됩니다. 상세한 배포 절차가 포함되어 있으면, 테스트 파일의 오타를 수정하는 동안에도 해당 token을 소모합니다. Anthropic의 가이드는 필수 사항만 포함하고 파일 길이를 200 line 미만으로 유지하는 것입니다.

절차는 skills로 이동하십시오. skill은 호출될 때만 로드되므로, 일주일에 두 번 실행하는 workflow는 나머지 날에는 비용이 발생하지 않습니다. skill은 compaction 이후 자체 budget을 가집니다. 본문은 다시 주입되며, skill당 최대 5,000 token, 총 25,000 token으로 제한됩니다. 가장 오래된 내용부터 삭제됩니다. Truncation 시 파일의 시작 부분이 유지되므로, 가장 중요한 지침을 SKILL.md 상단에 배치하십시오.

Compaction 후 무엇이 남느냐에 따라 지침의 위치가 결정됩니다.

• system prompt와 output style은 message history의 일부가 아니므로 변경되지 않습니다.
• project-root CLAUDE.md, unscoped rules, auto memory는 disk에서 다시 주입됩니다.
• paths: frontmatter가 있는 rule은 일치하는 파일이 다시 읽히기 전까지 유실됩니다.
• 하위 디렉토리의 중첩된 CLAUDE.md은 해당 디렉토리의 파일이 다시 읽히기 전까지 유실됩니다.
• Hook은 코드로 실행되며 context에 들어가지 않으므로 영향을 받지 않습니다.

따라서 의존성이 있는 rule은 project-root CLAUDE.md에 위치해야 합니다. Claude Code는 오래된 tool output을 먼저 삭제한 후 요약하므로, 대화 초반의 지침은 유실될 수 있습니다. memory는 /memory으로 편집하십시오. Claude Code는 세션 시작 시 로드한 복사본을 유지합니다. 세션 중간의 trim은 prompt cache를 유지하며, 다음 /clear, /compact 또는 restart 시점에 적용됩니다.

작업 간에는 /clear를, 하나의 작업 내부에서는 /compact를 사용하십시오

이 두 명령은 서로 교체 가능한 것처럼 보이지만 비용 차이가 매우 큽니다.

/clear [name]은 빈 컨텍스트로 새로운 대화를 시작합니다. 요청을 보내지 않으므로 비용이 발생하지 않습니다. 이전 대화에 이름을 붙이려면 /resume 선택기에 이름을 전달하십시오. /reset 및 /new는 별칭입니다. 관련 없는 작업으로 전환하는 즉시 이 명령을 사용하십시오. 그렇지 않으면 이전 작업 내용이 새 작업의 메시지마다 다시 전송되어 비용이 중복 청구됩니다.

/compact [instructions]은 동일한 대화를 유지하면서 컨텍스트를 확보합니다. 지금까지의 이력을 요약하여 교체합니다. 연속성이 필요한 하나의 긴 작업 내부에서 이 명령을 사용하십시오.

/compact에는 항상 지침을 제공하십시오. 지침이 없는 /compact은 작업의 어느 부분이 여전히 필요한지 알 수 없는 기본 프롬프트를 사용하여 요약합니다. 지침이 포함된 요약은 다음을 유지합니다:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

매번 동일한 이유로 압축을 수행한다면, 프로젝트의 CLAUDE.md 내 # Compact instructions 헤딩 아래에 상시 지침을 설정하십시오. 새 세션에서 /compact은 Not enough messages to compact.을 출력하며, 이는 아직 이력이 없음을 의미합니다.

여기서 두 가지 비용 개념이 혼동될 수 있습니다. 요약 요청은 사용자의 prefix를 공유하므로, 이력을 다시 처리하는 대신 기존 cache를 읽습니다. 따라서 대부분의 시간은 요약을 생성하는 데 소요됩니다. 대규모 컨텍스트를 압축하는 것은 여전히 대규모 요청입니다. 요약 대상인 대화 내용이 입력값이 되기 때문입니다. 압축 직후의 턴은 느리지 않습니다. 훨씬 짧아진 프롬프트를 위해 cache를 다시 구축하기 때문입니다.

두 가지 더 저렴한 명령이 있습니다. /rewind [description]은 코드와 대화를 체크포인트로 되돌립니다. 완전히 포기하려는 경로가 있다면 압축보다 이 명령이 유리합니다. 이미 cache된 prefix로 내용을 잘라내기 때문입니다. /recap은 이력을 교체하는 대신 요약을 명령 출력으로 추가하므로, cache된 prefix가 그대로 유지됩니다.

자동 압축이 반복적으로 실행되면 다음이 출력됩니다:

Autocompact is thrashing: the context refilled to the limit...

압축에 성공했으나, 파일 또는 도구 출력이 연속적으로 윈도우를 다시 채웠기 때문에 Claude Code가 재시도를 중단했습니다. 해결 방법은 다음과 같습니다: 라인 범위로 대용량 파일을 읽거나, 대용량 출력을 제외하도록 focus를 설정하여 /compact을 실행하거나, 해당 작업을 subagent로 이동시키십시오. 이전 대화가 완료된 경우라면 /clear을 사용하십시오.

MCP servers are fixed overhead

연결된 모든 MCP server는 세션 전체의 모든 request에 오버헤드를 추가합니다. 해당 tool을 호출하지 않더라도 비용이 발생합니다.

Claude Code는 이 문제를 완화합니다. MCP tool definition은 기본적으로 지연(deferred)됩니다. 따라서 Claude가 특정 tool을 사용하기 전까지는 tool name만 context에 포함됩니다. 서버의 실제 비용을 확인하려면 /context을 실행하고, 오늘 사용하지 않을 서버를 제거하려면 /mcp disable <name>을 실행하십시오. VPS에서 자체 MCP servers를 실행하는 경우에도 동일한 계산 방식이 적용되며, 이는 한 server가 노출해야 하는 tool의 개수를 제한합니다.

이 작업은 session 시작 시 수행하십시오. definition이 지연 상태로 유지되는 동안에는 server를 연결하거나 연결 해제해도 대화 내용이 추가될 뿐이며 cache는 유지됩니다. 반면, tool search가 꺼져 있거나 server가 지연 대상에서 제외되어 definition이 prefix에 로드되는 경우에는, 동일한 변경 사항으로 인해 다음 request에서 모든 내용을 다시 읽어야 합니다.

컨텍스트에 입력되기 전 verbose한 도구 출력을 필터링하십시오

도구 결과는 입력값이 되며, 입력값은 이후의 모든 turn에서 다시 전송됩니다. 20,000 tokens의 출력을 생성하는 테스트 실행은 일회성 비용이 아닙니다. 해당 출력이 컨텍스트 창을 벗어날 때까지 매 turn마다 비용이 발생합니다.

출력 원본 단계에서 필터링하십시오. Claude가 확인하기 전에 테스트 실행 결과를 실패한 항목 위주로 축소하는 hook을 사용하면, 해당 출력 뭉치를 이번 turn과 이후의 모든 재전송 시점에서 수백 tokens 수준으로 줄일 수 있습니다.

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Hook은 코드로 실행되므로 컨텍스트에 직접 포함되지 않습니다. 출력 내용이 화면을 넘어가는 모든 도구에 이 방식을 적용하십시오. 3,000줄짜리 파일에도 동일한 논리가 적용됩니다. 파일 전체가 컨텍스트 창에 유지되므로, 필요한 줄 범위(line range)만 요청하십시오.

에이전트의 읽기 범위를 제한하고 번거로운 작업은 위임하십시오

파일 이름과 증상을 명시한 프롬프트는 해당 파일을 읽습니다. 프로젝트 정리와 같은 광범위한 요청은 에이전트가 관련 있다고 판단하는 모든 내용을 읽으며, 읽은 모든 내용은 컨텍스트 창에 유지됩니다.

상세한 작업은 subagent에게 위임하십시오. 테스트 실행과 로그 처리는 모두 많은 context를 소모합니다. subagent는 해당 출력을 자체 창에 유지하며 요약본만 반환합니다. 트레이드오프는 다음과 같습니다. subagent는 첫 호출 시 cache hit가 발생하지 않으며, subscription을 사용하더라도 5분간의 cache lifetime이 적용됩니다. 위임은 메인 context를 안정적으로 보호합니다. 다만, 전체 token 수가 항상 줄어드는 것은 아닙니다.

캐시 클록: 연속적인 작업 흐름 유지

Prompt caching 덕분에 재전송 비용이 저렴해집니다. Prefix를 읽는 비용은 기본 입력 비용의 0.1x이며, 1시간 수명(lifetime) 기준 쓰기 비용은 1.25x입니다. 각 사용 시 추가 비용 없이 엔트리가 갱신되므로, 클록은 마지막 사용 시점부터 다시 시작됩니다.

수명은 인증 방식에 따라 달라집니다. 따라서 "캐시가 5분 후에 만료된다"는 일반적인 설명은 틀린 설명입니다.

• Claude subscription 사용 시, Claude Code는 자동으로 1시간 수명을 요청합니다.
• 플랜 한도를 초과하여 usage credits를 사용하는 경우, 해당 사용량에 대해 과금되므로 수명이 5분으로 줄어듭니다.
• API key 또는 cloud provider 사용 시, 수명은 5분으로 유지됩니다. ENABLE_PROMPT_CACHING_1H=1은 1시간 수명을 선택하며, FORCE_PROMPT_CACHING_5M=1은 이를 다시 5분으로 강제합니다.

두 경우 모두 작업 방식에 대한 조언은 동일합니다. 연속적인 stints 단위로 작업하십시오. 수명을 초과하여 유휴 상태(idle)가 되면, 다음 작업 시 누적된 전체 prefix를 다시 써야 하기 때문입니다. tmux에서 분리된 Claude Code session은 유휴 상태일 때 비용이 발생하지 않으며, 유휴 시간 동안 따르는 손실은 warm cache를 잃는 것입니다.

작업 중에도 캐시가 삭제되는 동작이 있습니다: 모델 전환, effort level 변경, fast mode 활성화, MCP server 연결 또는 해제, plugin 활성화 또는 비활성화, 전체 tool 거부, compacting, Claude Code 업그레이드 등이 해당됩니다. /model은 흔히 발생하는 상황입니다. 각 모델은 고유한 캐시를 가지므로, 내용이 동일하더라도 다음 요청 시 캐시 히트 없이 전체 히스토리를 다시 읽게 됩니다.

파일 편집, CLAUDE.md 편집, skills 및 commands 호출, /recap 실행, rewinding, subagent 생성 시에는 캐시가 유지됩니다. 캐시는 하나의 machine과 하나의 directory에 국한되므로, 서로 다른 directory의 두 session은 서로의 캐시를 공유할 수 없습니다.

캐싱 작동 여부를 확인하려면 current_usage을 읽으십시오. cache_creation_input_tokens은 캐시 쓰기 속도로 작성되었습니다; cache_read_input_tokens은 표준 입력 속도의 약 1/10로 제공되었습니다. read-to-creation ratio가 높으면 정상입니다. 만약 매 작업마다 creation 수치가 높게 유지된다면, prefix의 일부가 계속 변경되고 있는 것입니다.

컨텍스트 윈도우를 키우면 이 문제가 해결됩니까?

부분적으로 그렇습니다. 현재 여러 모델이 1 million token 컨텍스트 윈도우를 지원하며, 더 큰 제한 범위에서도 compaction 방식은 동일하게 작동합니다. 전체 프롬프트가 매 턴마다 다시 전송되고 비용이 청구되므로 경제적 측면은 변하지 않습니다. 더 큰 윈도우는 작업을 수행해야 하는 시점을 결정하며, 데이터 관리(hygiene)는 비용을 결정합니다. 한계치보다 비용이 문제라면, 작업 방식에 적합한 Claude 플랜을 통해 달러를 지불할지 또는 플랜 할당량을 사용할지 결정해야 합니다.

API에서 Context editing과 Compaction은 서로 다른 기능입니다

Messages API를 사용하여 직접 agent를 구축하는 경우, slash commands가 존재하지 않으므로 직접 구현해야 합니다. 서버 측 기능 중 두 가지가 이 역할을 수행하며, 두 기능은 서로 다릅니다.

Context editing은 대화 기록이 길어짐에 따라 특정 콘텐츠를 선택적으로 삭제합니다. 삭제된 결과는 placeholder text로 대체되어 Claude가 내용이 삭제되었음을 알 수 있게 합니다. 이 기능은 beta 버전입니다. anthropic-beta: context-management-2025-06-27를 전송하고 context_management.edits 아래에서 전략을 설정하십시오. clear_tool_uses_20250919은 tool results를 삭제하며, clear_thinking_20251015은 thinking blocks를 관리합니다. trigger의 기본값은 100,000 input tokens이며, keep은 마지막 3개의 tool uses, clear_tool_inputs은 false으로 설정되어 입력값은 유지하고 결과값만 삭제합니다.

Compaction은 요약본을 생성하고 전체 대화 기록을 해당 요약본으로 대체합니다. 이 기능 또한 beta 버전입니다. anthropic-beta: compact-2026-01-12를 전송하고 compact_20260112 edit type을 사용하십시오. 트리거의 기본값은 {"type": "input_tokens", "value": 150000}이며, 값은 최소 50,000이어야 합니다.

Compaction에는 agent의 동작을 방해할 수 있는 한 가지 handoff rule이 있습니다. 응답은 요약본을 포함하는 compaction content block로 시작하며, 그 뒤에 일반 text block이 이어집니다. 이후의 요청 시 해당 block을 반드시 다시 전달해야 합니다. 그러면 API는 해당 block 이전의 모든 content block을 삭제합니다. 실제 적용 시 response.content의 전체 내용을 추가해야 하며, 텍스트만 추가해서는 안 됩니다.

Anthropic의 문서에 따르면, 서버 측 compaction은 장기 대화에서 context를 관리하는 기본 전략이며, context editing은 삭제할 내용을 더 세밀하게 제어하는 옵션입니다. 먼저 모델 지원 여부를 확인하십시오. 현재 Opus, Sonnet, Fable 모델은 compaction을 지원합니다. claude-haiku-4-5은 지원하지 않으며, 최신 목록은 compaction 페이지에서 확인할 수 있습니다. 두 beta 기능 모두 Claude Code의 /compact을 구동하지 않습니다. Claude Code의 문서에 따르면 /compact은 클라이언트가 보내는 일회성 summarization request입니다.

FAQ

Claude Code 세션이 길어질수록 왜 느려지고 비용이 많이 발생합니까?

매 턴마다 전체 대화 내용이 다시 전송되기 때문입니다. 하루 종일 열려 있는 세션에서 던지는 한 줄짜리 질문도 하루 치의 전체 대화 내용을 포함합니다. Prompt caching을 사용하면 캐시가 유지되는 동안에는 기본 입력 비용의 0.1x로 저렴하게 유지됩니다. 하지만 캐시를 벗어나면 동일한 prefix를 1.25x 비용으로 다시 작성해야 합니다. /context을 실행하여 컨텍스트를 차지하는 요소를 확인하십시오. 과금 메커니즘에 대한 상세 내용은 Claude Code 과금 방식을 참조하십시오.

Claude Code에서 /clear와 /compact의 차이점은 무엇입니까?

/clear은 빈 컨텍스트로 새로운 대화를 시작합니다. 요청을 보내지 않으므로 비용이 발생하지 않으며, 서로 관련 없는 작업을 수행할 때 적합합니다. /compact은 대화를 유지하면서 히스토리를 요약본으로 교체합니다. 따라서 하나의 긴 작업을 수행할 때 적합합니다. /compact keep only the plan and the diff처럼 지침을 제공하여 요약할 내용을 결정하십시오.

Claude Code의 컨텍스트 윈도우를 무엇이 사용 중인지 어떻게 확인합니까?

/context을 실행하거나, 항목별 상세 내역을 보려면 /context all을 실행하십시오. 시스템 프롬프트, tool definitions, MCP servers, memory files, history를 색상 그리드로 보여주며, 컨텍스트를 많이 사용하는 tool이나 memory 팽창에 대한 제안을 제공합니다. 유료 플랜의 경우, /usage을 통해 최근 사용량을 개별 skills, subagents, MCP servers별로 확인할 수 있습니다.

compaction 대신 1 million token 컨텍스트 윈도우를 사용해야 합니까?

더 큰 윈도우를 사용하는 것은 문제를 해결하는 것이 아니라 지연시키는 것입니다. Opus 4.8 및 Sonnet 5를 포함한 여러 최신 모델이 1 million token 컨텍스트 윈도우를 지원하지만, compaction의 동작 방식은 동일합니다. 매 턴마다 전체 프롬프트를 다시 전송하므로 비용이 발생합니다. 따라서 400,000-token 대화는 컨텍스트 용량 포함 여부와 상관없이 비용이 많이 듭니다.

Claude API에서 context editing과 compaction의 차이점은 무엇입니까?

Context editing은 오래된 콘텐츠(주로 tool results)를 선택적으로 삭제합니다. 이때 삭제된 위치에 placeholder text를 남겨 Claude가 해당 내용이 제거되었음을 알 수 있게 합니다. Compaction은 요약본을 생성하여 전체 히스토리를 대체합니다. Anthropic 문서는 compaction을 장기 대화를 위한 주요 전략으로, context editing을 세밀한 제어를 위한 옵션으로 정의합니다. 두 기능 모두 베타 버전이며 각각 고유한 헤더를 가지며, Claude Code의 /compact과는 별개입니다.