Claude Code 서브 에이전트의 5분 프롬프트 캐시 문제: 긴 명령어로 5시간 사용 제한이 빠르게 소진될 수 있음
Claude Code sub-agents have a 5m prompt cache. Long commands can burn your 5-hour window.
핵심 요약
서브 에이전트의 짧은 프롬프트 캐시 TTL로 인해 발생하는 불필요한 컨텍스트 재작성 문제를 설정 변경으로 해결하는 방법입니다.
- 프롬프트 캐시 문제 — 서브 에이전트의 5분 캐시 만료로 인해 긴 작업 시 컨텍스트가 반복적으로 재작성됨
- 설정 해결책 — ~/.claude/settings.json에 subagentPromptCacheTtl을 1시간으로 설정하여 캐시 효율 개선
- 작업 최적화 — 긴 작업은 백그라운드에서 실행하고 주기적으로 폴링하여 캐시를 유지하는 것이 권장됨
- 주의 사항 — 1시간 TTL 설정 시 캐시 쓰기 비용이 소폭 상승할 수 있으므로 작업 특성에 맞춰 적용 필요
여기서 다들 겪는 사용량 제한 문제는 주간 프로모션 변경을 포함해서 여러 가지가 복합적으로 작용한 결과일 거야. 근데 5시간짜리 사용량 제한을 순식간에 날려버리는 특정 워크플로우가 하나 있는데, 이건 이미 문서화도 되어 있고 한 줄이면 해결 가능해. 바로 서브 에이전트가 기본값인 5분짜리 프롬프트 캐시보다 더 긴 시간 동안 차단(blocking) 명령어를 실행할 때 발생하는 문제야.
TL;DR: 서브 에이전트는 프롬프트 캐시 기본값이 5분인데, 메인 세션은 1시간이야. 서브 에이전트가 5분이 넘어가는 명령어를 실행하느라 멈춰 있으면, 그다음 요청을 보낼 때 캐시에서 읽어오는 게 아니라 쌓아둔 컨텍스트 대부분을 다시 써버리거든. 에이전트가 긴 명령어를 자주 돌린다면 ~/.claude/settings.json에 "subagentPromptCacheTtl": "1h"를 추가해. 내 테스트 위주의 워크플로우 기준으로 캐시 쓰기 작업이 75% 정도 줄었어.
메커니즘: Claude Code는 요청할 때마다 전체 내용을 다시 보내지 않으려고 Anthropic 쪽에서 대화 내용을 캐싱해. 메인 세션 캐시는 구독 중이면 1시간 동안 유지되는데, 서브 에이전트는 5분밖에 안 가. 서브 에이전트가 읽고 수행한 모든 게 컨텍스트에 담기는데, 실제 작업 좀 하다 보면 금방 300K에서 600K 토큰은 찍거든. 근데 얘가 툴 호출(테스트 스윕, 빌드, 깃 훅, 긴 폴링 호출 등) 때문에 5분 넘게 멍하니 있으면, 호출이 끝났을 때 캐시는 이미 증발해 있고 다음 요청에서 전체 컨텍스트를 다시 써버리는 거야. 테스트 6번 돌리면 6번 다 다시 쓰는 꼴이니 제한 시간은 순삭이지. 캐시 읽기는 제한에 거의 영향 안 주는데, 쓰기가 문제거든. 내 MAX 5x 측정 결과, 주간 사용량은 5시간 제한이랑 비교했을 때 같은 작업이라도 1/10 수준이었어. 즉, 5시간 제한을 다 쓴다는 건 내 일주일치 할당량의 1/10을 날린다는 소리야.
해결법:
{ "subagentPromptCacheTtl": "1h" }
이걸 ~/.claude/settings.json에 넣거나 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h 환경 변수로 설정해. v2.1.242 이상 버전이 필요해. API에서 제공하는 최대 시간이 1시간이라 15분 같은 옵션은 없어. 주의할 점은, 이 설정이 에이전트별로 설정하는 experimental: cacheTtl: 5m 프론트매터보다 우선순위가 높다는 거야. 만약 5분짜리 읽기 전용 에이전트를 몇 개 두고 싶다면, 이걸 설정하지 말고 env 블록 아래에 ENABLE_PROMPT_CACHING_1H=1을 넣으면 돼.
트레이드 오프: API 가격표를 보면 1시간짜리 쓰기가 5분짜리(1.25배)보다 2배 정도 비싸. 근데 구독제 사용량 측정 방식은 좀 달라. 5시간 제한이나 주간 제한이랑 비교해보면 5분짜리 쓰기가 1시간짜리의 0.9배 정도 비용이 들어. 캐시 읽기는 거의 공짜고. 그렇다고 1시간이 무조건 싼 건 아니야. 5분 넘게 멍 때릴 일이 없는 짧은 에이전트는 굳이 설정 안 하는 게 나을 수도 있어. 하지만 에이전트가 컨텍스트를 꽤 쌓고 5분 넘게 멈춰 있는 경우가 잦다면, 반복되는 대규모 캐시 재작성을 막는 게 훨씬 중요해.
비포 & 애프터: MAX 5x 환경에서 테스트 위주의 멀티 에이전트 워크플로우를 돌려봤어. 오케스트레이터 세션 하나에, 30초에서 40분까지 걸리는 테스트 스윕을 돌리는 서브 에이전트 몇 개를 썼지. 비포: 서브 에이전트 하나가 하루에 590K 정도 되는 컨텍스트를 8번이나 다시 써서 혼자서만 5.4M 토큰을 캐시 쓰기로 날렸어. 에이전트 5개 합치면 26번 재작성에 12.2M 토큰을 쓴 셈이지. 5시간 제한은 4개 에이전트에서 2%에서 100%까지 꽉 찼어. 애프터: 비슷한 서브 에이전트 5개가 530번 정도 턴을 돌면서 3.0M 토큰을 썼는데, 처음 한 번만 크게 쓰고 나머지는 거의 안 썼어. 5시간 제한도 0%에서 22% 수준으로 끝났지. 같은 작업인데 캐시 쓰기가 75%나 줄어든 거야.
서브 에이전트 기록은 여기 있어. 긴 툴 호출 뒤에 값이 똑같은 큰 숫자로 계속 반복되면 그게 재작성되고 있다는 증거야. 랑 값을 보면 각각 어디에 캐시가 저장됐는지 알 수 있어.
