Claude Code 세션 속도 저하 및 비용 증가 해결 방법

장시간 Claude Code 세션의 속도 저하 및 비용 증가를 방지하는 방법

장시간 Claude Code 세션을 유지하면 모든 턴마다 전체 컨텍스트를 다시 전송하게 되며, 컨텍스트는 계속 커지기 때문에 속도가 느려지고 비용이 증가합니다. 이를 해결하려면 정해진 순서대로 관리하는 습관이 필요합니다. /context를 실행하여 컨텍스트 창을 채우는 항목을 확인하고, 매 요청마다 비용이 발생하는 항목을 제거하십시오. 그 후 관련 없는 작업 사이에는 /clear를 사용하고, 하나의 긴 작업 내에서는 /compact를 사용하여 지침을 전달하십시오. 프롬프트 캐시가 식으면 저렴한 읽기 작업이 전체 내용을 다시 작성하는 작업으로 바뀌므로, 연속적으로 작업하는 것이 좋습니다.

요금 측정기가 작동하는 이유는 에이전트 세션의 토큰 측정기에서 확인할 수 있습니다.

변경 전 /context 읽기

창에 무엇이 채워져 있는지 추측하지 마십시오. Claude Code가 알려줄 것입니다.

/context [all]은 현재 컨텍스트 사용량을 색상 격자로 표시하며, 컨텍스트를 많이 사용하는 도구와 메모리 비대화에 대한 최적화 제안을 제공합니다. all은 항목별 상세 내역을 전체 화면 모드로 확장합니다. 결과를 다섯 개의 버킷으로 읽으십시오.

• 시스템 프롬프트. Claude Code 자체의 하네스 지침입니다. 세션 동안 고정됩니다.
• 도구 정의. 연결된 모든 MCP(Model Context Protocol) 서버를 포함하여 에이전트가 호출할 수 있는 모든 도구의 스키마입니다.
• 메모리 파일. CLAUDE.md 및 자동 메모리로, 세션 시작 시 로드됩니다.
• 파일 및 도구 결과. 읽은 모든 파일과 명령어가 출력한 모든 내용입니다.
• 메시지 기록. 사용자의 차례와 에이전트의 응답입니다.

앞의 세 가지는 세션이 유지되는 동안 모든 요청마다 지불해야 하는 고정 비용입니다. 마지막 두 가지는 계속 증가합니다. 시작할 때 고정 비용을 한 번 줄이고, 증가하는 부분은 지속적으로 관리하십시오.

창이 가득 찼음을 알리는 두 가지 문자열이 있습니다.

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.

첫 번째는 하드 리밋이며, 요청이 거부됩니다. 일치하는 API(application programming interface) 오류는 Prompt is too long으로 표시됩니다. 두 번째는 압축 윈도우로, 100만 토큰 모델에서 모델의 실제 컨텍스트 윈도우보다 낮게 설정될 수 있습니다. 이 지점을 지나도 요청은 성공하므로, 이는 거부가 아닌 경고입니다.

유료 플랜에서는 /usage이 나머지 절반을 추가하며, 긴 컨텍스트나 캐시 미스와 같은 동작을 표시하고 최근 사용량을 개별 기술, 하위 에이전트 및 MCP 서버에 귀속시킵니다. 허용량이 이미 소진되었다고 표시되면, 어떤 리밋 윈도우를 기다리고 있는지에 따라 컨텍스트를 줄이는 것이 도움이 될지, 아니면 작업으로 돌아갈 다른 경로가 필요한지 결정하십시오.

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

귀하의 CLAUDE.md는 세션 시작 시 컨텍스트에 로드되어 계속 유지됩니다. 상세한 배포 절차가 포함되어 있다면, 테스트 파일의 오타를 수정하는 동안에도 해당 토큰이 계속 소비됩니다. Anthropic의 지침은 필수 사항만 포함하고 파일 길이를 200줄 미만으로 유지하는 것입니다.

절차는 스킬(skills)로 옮기십시오. 스킬은 호출될 때만 로드되므로, 일주일에 두 번 실행하는 워크플로우는 나머지 날에는 비용이 발생하지 않습니다. 스킬은 압축(compaction) 후 자체 예산을 가집니다. 본문은 스킬당 5,000 토큰, 전체 25,000 토큰으로 제한되며, 가장 오래된 것부터 삭제됩니다. 잘림(truncation)은 파일의 시작 부분을 유지하므로, 가장 중요한 지침은 SKILL.md의 상단에 배치하십시오.

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

• 시스템 프롬프트와 출력 스타일은 메시지 기록의 일부가 아니므로 변경되지 않습니다.
• 프로젝트 루트의 CLAUDE.md, 범위가 지정되지 않은 규칙, 자동 메모리는 디스크에서 다시 주입됩니다.
• paths: 프론트매터가 있는 규칙은 일치하는 파일을 다시 읽을 때까지 손실됩니다.
• 하위 디렉터리의 중첩된 CLAUDE.md은 해당 하위 디렉터리의 파일을 다시 읽을 때까지 손실됩니다.
• 훅(hooks)은 코드로 실행되며 컨텍스트에 들어가지 않으므로 영향을 받지 않습니다.

따라서 의존하는 규칙은 프로젝트 루트의 CLAUDE.md에 두어야 합니다. Claude Code는 이전 도구 출력을 먼저 지운 다음 요약하므로, 대화 초기의 지침은 손실될 수 있습니다. /memory을 사용하여 메모리를 편집하십시오. Claude Code는 세션 시작 시 로드된 복사본을 유지하므로, 세션 중간의 다듬기는 프롬프트 캐시를 유지하며 다음 /clear, /compact 또는 재시작 전까지는 적용되지 않습니다. 컨텍스트 손실은 규칙이 더 이상 따르지 않게 되는 한 가지 이유일 뿐입니다. 따라서 규칙이 여전히 윈도우 내에 있음에도 무시된다면, 규칙을 다시 작성하기 전에 다른 원인들을 먼저 검토하십시오.

작업 간의 /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.이 출력되는데, 이는 아직 기록이 없음을 의미합니다.

여기서 두 가지 비용을 혼동하기 쉽습니다. 요약 요청은 접두사를 공유하므로 기록을 다시 처리하는 대신 기존 캐시를 읽으며, 대부분의 시간은 요약 생성에 소요됩니다. 대규모 컨텍스트를 압축하는 작업은 요약 대상인 대화 자체가 입력값이므로 여전히 큰 요청입니다. 압축 직후의 턴은 느리지 않습니다. 훨씬 짧아진 프롬프트에 대해 캐시를 다시 빌드하기 때문입니다.

더 저렴한 두 가지 명령어가 있습니다. /rewind [description]는 코드와 대화를 체크포인트로 되돌립니다. 완전히 포기하려는 경로의 경우, 이미 캐시된 접두사로 잘라내기 때문에 압축보다 효율적입니다. /recap은 기록을 대체하는 대신 명령어 출력으로 요약을 추가하므로 캐시된 접두사가 그대로 유지됩니다.

자동 압축이 반복적으로 실행되면 다음 메시지가 출력됩니다.

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

압축은 성공했으나 파일이나 도구 출력이 창을 계속 채워 Claude Code가 재시도를 중단한 상태입니다. 너무 큰 파일을 행 단위로 읽거나, 큰 출력을 제외하고 집중 범위를 설정하여 /compact를 실행하거나, 작업을 하위 에이전트로 옮기거나, 이전 대화가 완료되었다면 /clear를 사용하여 복구하십시오.

MCP 서버는 고정 오버헤드를 발생시킵니다

연결하는 모든 MCP 서버는 전체 세션의 모든 요청에 오버헤드를 추가합니다. 해당 서버의 도구를 호출하는지 여부와 관계없이 비용이 발생합니다.

Claude Code는 이 문제를 완화합니다. MCP 도구 정의는 기본적으로 지연 로딩(deferred)되므로, Claude가 특정 도구를 사용하기 전까지는 도구 이름만 컨텍스트에 포함됩니다. /context을 실행하여 서버가 실제로 소모하는 비용을 확인하고, 오늘 사용하지 않을 서버는 /mcp disable <name>을 사용하여 연결을 해제하십시오. 만약 VPS에서 직접 MCP 서버를 운영한다면, 동일한 계산 방식에 따라 서버 하나가 노출해야 할 도구의 개수를 제한해야 합니다.

이 작업은 세션 시작 시 수행하십시오. 도구 정의가 지연 로딩되는 동안에는 서버를 연결하거나 연결 해제해도 대화 내용에 추가되기만 할 뿐이며, 캐시는 유지됩니다. 도구 검색 기능이 꺼져 있거나 서버가 지연 로딩 대상에서 제외되어 정의가 접두사(prefix)로 로드되는 경우에는, 서버 연결 상태를 변경할 때마다 다음 요청에서 모든 내용을 다시 읽어야 합니다.

도구의 상세 출력이 컨텍스트에 포함되기 전에 필터링하기

도구의 결과값은 입력으로 간주되며, 이후 모든 대화 턴마다 다시 전송됩니다. 20,000 토큰의 출력을 쏟아내는 테스트 실행은 일회성 비용이 아닙니다. 해당 내용이 컨텍스트 창에서 사라질 때까지 매 턴마다 비용을 지불하게 됩니다.

출력 원본에서 필터링하십시오. 테스트 실행 결과를 실패한 항목으로만 압축하여 Claude에게 전달하는 훅(hook)을 사용하면, 해당 턴은 물론 이후 모든 재전송 과정에서 출력의 양을 수백 토큰 수준으로 줄일 수 있습니다.

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

훅은 코드로 실행되므로 그 자체로는 컨텍스트에 포함되지 않습니다. 화면을 넘어가는 출력을 내보내는 모든 도구에 이 방식을 적용하십시오. 3,000줄짜리 파일도 같은 논리가 적용됩니다. 파일 전체가 한 번 들어오면 컨텍스트 창에 계속 남아 있게 되므로, 필요한 줄 범위만 요청하십시오.

에이전트가 읽는 범위를 제한하고 번거로운 작업 위임하기

파일 이름과 증상을 명시하는 프롬프트는 해당 파일만 읽습니다. 프로젝트를 정리해 달라는 포괄적인 요청은 에이전트가 관련 있다고 판단하는 모든 파일을 읽으며, 이러한 읽기 작업은 모두 컨텍스트 윈도우에 남습니다.

번거로운 작업은 서브 에이전트에게 위임하십시오. 테스트 실행과 로그 처리는 모두 실제 컨텍스트를 소모합니다. 서브 에이전트는 해당 출력을 자체 윈도우에 유지하고 요약본만 반환합니다. 이 방식의 장단점은 다음과 같습니다. 서브 에이전트는 자체 캐시를 구축하므로 첫 호출 시에는 캐시 적중이 발생하지 않으며, 구독 중이라도 5분의 캐시 유효 기간을 사용합니다. 위임은 메인 컨텍스트를 안정적으로 보호합니다. 다만, 전체 토큰 사용량이 항상 줄어드는 것은 아닙니다.

캐시 클록: 작업 단위로 운영하기

프롬프트 캐싱은 재전송 비용을 절감하는 핵심 요소입니다. 접두사를 읽을 때 기본 입력 요금의 0.1배가 부과되며, 이를 작성할 때는 1.25배, 1시간 수명 동안 작성할 때는 2배가 부과됩니다. 캐시를 사용할 때마다 추가 비용 없이 항목이 갱신되므로, 캐시 유효 시간은 마지막 사용 시점부터 다시 계산됩니다. 이러한 배율은 청구서의 비중을 결정할 뿐 실제 금액을 의미하지는 않으므로, 백만 토큰당 실제 비용을 함께 계산하여 전체 컨텍스트 윈도우의 달러 단위 비용을 산출해야 합니다.

캐시 수명은 인증 방식에 따라 달라지며, "캐시가 5분 뒤에 만료된다"는 식의 일괄적인 설명은 정확하지 않습니다.

• Claude 구독을 사용하는 경우, Claude Code는 자동으로 1시간 수명을 요청합니다.
• 플랜 한도를 초과하여 사용량 크레딧을 차감하기 시작하면, 해당 사용량에 대해 요금이 청구되므로 수명은 5분으로 단축됩니다.
• API 키나 클라우드 제공업체를 사용하는 경우, 수명은 5분으로 유지됩니다. ENABLE_PROMPT_CACHING_1H=1은 1시간 수명을 선택하는 옵션이며, FORCE_PROMPT_CACHING_5M=1는 이를 다시 5분으로 강제하는 옵션입니다.

어떤 경우든 작업 방식에 대한 조언은 동일합니다. 연속적인 단위로 작업하십시오. 유효 시간이 지난 후 유휴 상태가 길어지면 다음 요청 시 누적된 접두사 전체를 다시 작성해야 하기 때문입니다. tmux에서 분리된 Claude Code 세션은 유휴 상태일 때 비용이 발생하지 않지만, 유휴 시간이 길어지면 캐시가 유지되지 않습니다.

모델 전환, 노력 수준 변경, 빠른 모드 활성화, MCP 서버 연결 또는 연결 해제, 플러그인 활성화 또는 비활성화, 전체 도구 거부, 압축, Claude Code 업그레이드와 같은 일부 작업은 작업 도중 캐시를 삭제합니다. /model은 흔히 발생하는 예상치 못한 상황인데, 각 모델은 고유한 캐시를 가지므로 내용이 동일하더라도 다음 요청 시 캐시 적중 없이 전체 기록을 다시 읽게 됩니다. 이 재읽기 작업은 대상 모델의 요금으로 청구되므로, 세션 도중 Fable로 전환하면 누적된 전체 기록이 Fable 5의 공시된 입력 요금으로 청구됩니다.

파일 편집, CLAUDE.md 편집, 기술 및 명령 호출, /recap 실행, 되감기, 서브 에이전트 생성은 캐시를 유지합니다. 캐시는 한 대의 머신과 하나의 디렉터리로 범위가 제한되므로, 서로 다른 디렉터리에서 실행되는 두 세션은 캐시를 공유하지 않습니다. 이 범위는 계정이 아닌 CLI를 따르므로, Linux에서 CLI와 별도로 설치되는 베타 버전인 Claude 데스크톱 앱으로는 캐시가 이전되지 않습니다.

캐시가 정상적으로 작동하는지 확인하려면 current_usage을 읽어보십시오. cache_creation_input_tokens는 캐시 작성 요금으로 기록되었으며, cache_read_input_tokens는 표준 입력 요금의 약 10분의 1 수준으로 제공되었습니다. 높은 읽기 대비 생성 비율은 캐시가 효율적으로 작동하고 있음을 의미합니다. 만약 매 턴마다 생성 비율이 높게 유지된다면, 접두사 내의 무언가가 계속 변경되고 있다는 뜻입니다.

더 큰 컨텍스트 윈도우가 이 문제를 해결합니까?

부분적으로는 그렇습니다. 현재 여러 모델이 100만 토큰의 컨텍스트 윈도우를 지원하며, 더 큰 제한 내에서도 압축 방식은 동일하게 작동합니다. 전체 프롬프트가 매번 다시 전송되고 매 턴마다 비용이 청구되므로 경제적 측면은 변하지 않습니다. 더 큰 윈도우는 사용자가 언제 행동을 취해야 할지 결정하게 해주지만, 비용은 데이터 관리 방식에 따라 결정됩니다. 만약 한계치보다 비용이 문제라면, 본인의 작업 방식에 맞는 Claude 플랜을 통해 실제 비용을 지불할지 아니면 플랜의 할당량을 사용할지 결정해야 합니다.

API에서의 컨텍스트 편집과 압축은 서로 다른 개념입니다

Messages API를 사용하여 직접 에이전트를 구축하는 경우, 슬래시 명령어가 존재하지 않으므로 직접 구현해야 합니다. API는 소액의 가입 크레딧 외에는 무료 티어를 제공하지 않으므로, 정리되지 않은 대화 기록의 모든 턴이 그대로 과금됩니다. 따라서 작업 초기부터 이를 예산에 반영해야 합니다. 어떤 공급자를 선택하느냐에 따라 트리밍이 발생하기 전의 연산 비용이 결정되므로, 선택의 여지가 있다면 단순히 토큰당 단가를 비교하기보다 두 API에서 동일한 워크로드의 비용을 산출해 보아야 합니다. 서버 측에는 이 작업을 수행하는 두 가지 기능이 있으며, 이들은 서로 다른 기능입니다.

컨텍스트 편집(Context editing)은 대화 기록이 늘어남에 따라 특정 내용을 선택적으로 삭제하고, 삭제된 각 결과물을 플레이스홀더 텍스트로 대체하여 Claude가 무언가 제거되었음을 인지하게 합니다. 이 기능은 베타 버전입니다. anthropic-beta: context-management-2025-06-27을 전송하고 context_management.edits 아래에서 전략을 구성하십시오. clear_tool_uses_20250919은 도구 결과를 삭제하며, clear_thinking_20251015는 사고 블록을 관리합니다. trigger의 기본값은 100,000 입력 토큰, keep은 최근 도구 사용 3회, clear_tool_inputs는 false으로 설정되어 있어 입력값은 유지되고 결과값만 삭제됩니다.

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

압축에는 에이전트의 동작을 예기치 않게 중단시킬 수 있는 핸드오프 규칙이 하나 있습니다. 응답은 요약을 담은 compaction 콘텐츠 블록으로 시작하며, 그 뒤에 일반 텍스트 블록이 이어집니다. 이후 요청 시 해당 블록을 반드시 다시 전달해야 하며, 그러면 API가 그 이전의 모든 콘텐츠 블록을 삭제합니다. 실제 구현 시에는 텍스트뿐만 아니라 response.content 전체를 추가하십시오.

Anthropic의 문서는 서버 측 압축을 장기 대화에서 컨텍스트를 관리하기 위한 기본 전략으로, 컨텍스트 편집을 삭제 대상에 대한 세밀한 제어를 위한 옵션으로 정의합니다. 먼저 모델 지원 여부를 확인하십시오. 현재 Opus, Sonnet, Fable 모델은 압축을 지원하지만, claude-haiku-4-5는 지원하지 않으며 압축 페이지에서 최신 목록을 확인할 수 있습니다. 이 두 베타 기능 모두 Claude Code 자체의 /compact을 구동하지 않으며, 해당 기능은 클라이언트가 전송하는 일회성 요약 요청이라고 문서에 명시되어 있습니다.

FAQ

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

모든 턴마다 전체 대화 내용이 다시 전송되기 때문입니다. 하루 종일 열려 있던 세션에서 한 줄짜리 질문을 던져도 그날의 모든 대화가 함께 전송됩니다. 프롬프트 캐싱(Prompt caching)을 사용하면 캐시가 유지되는 동안에는 기본 입력 비용의 0.1배 수준으로 저렴하게 처리할 수 있습니다. 하지만 턴이 캐시를 놓치면 동일한 접두사가 1.25배의 비용으로 다시 작성됩니다. /context을 실행하여 컨텍스트 창을 채우고 있는 내용을 확인하고, Claude Code 세션의 과금 방식을 읽어 상세 메커니즘을 파악하십시오.

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

/clear는 빈 컨텍스트로 새로운 대화를 시작합니다. 요청을 보내지 않으므로 비용이 발생하지 않으며, 서로 관련 없는 작업 간에 전환할 때 적합합니다. /compact은 동일한 대화를 유지하면서 기록을 요약본으로 대체하므로, 하나의 긴 작업 내에서 계속 진행할 때 적합합니다. /compact keep only the plan and the diff와 같이 요약의 초점을 지정하십시오. 어떤 내용을 남길지는 사용자의 지시에 따라 결정됩니다.

Claude Code 컨텍스트 창을 무엇이 차지하고 있는지 어떻게 확인합니까?

/context를 실행하거나, 항목별 전체 분석을 보려면 /context all을 실행하십시오. 시스템 프롬프트, 도구 정의, MCP 서버, 메모리 파일, 대화 기록이 색상별 그리드로 표시되며, 컨텍스트를 많이 차지하는 도구와 메모리 비대화에 대한 제안도 제공됩니다. 유료 플랜을 사용 중이라면 /usage을 통해 최근 사용량을 개별 스킬, 서브 에이전트, MCP 서버별로 분류하여 확인할 수 있습니다.

요약(compacting) 대신 100만 토큰 컨텍스트 창을 사용해야 합니까?

더 큰 창을 사용하는 것은 문제를 해결하는 것이 아니라 지연시키는 것뿐입니다. Opus 4.8과 Sonnet 5를 포함한 현재의 여러 모델이 100만 토큰 컨텍스트 창을 지원하지만, 요약 방식은 동일하게 작동합니다. 모든 턴마다 전체 프롬프트를 다시 전송하고 이에 대한 비용이 청구되므로, 40만 토큰 분량의 대화는 창에 들어가는지 여부와 상관없이 비용이 많이 발생합니다.

Claude API에서 컨텍스트 편집(context editing)과 요약(compaction)의 차이점은 무엇입니까?

컨텍스트 편집은 주로 도구 실행 결과와 같은 오래된 내용을 선택적으로 삭제하며, 삭제된 위치에 자리 표시자 텍스트를 남겨 Claude가 해당 내용이 제거되었음을 알 수 있게 합니다. 요약은 전체 기록을 요약본으로 생성하여 대체합니다. Anthropic의 문서는 요약을 장기 대화를 위한 주요 전략으로 정의하며, 컨텍스트 편집을 세밀한 제어가 필요한 경우의 선택지로 제시합니다. 두 기능 모두 베타 상태이며 각각 고유한 헤더를 사용하고, Claude Code의 /compact과는 별개로 작동합니다.