Claude Code 5시간 제한이 빨리 소진되나요? 서브 에이전트의 5분 프롬프트 캐시를 확인하세요

해결 방법

{
  "subagentPromptCacheTtl": "1h"
}

이걸 ~/.claude/settings.json에 넣거나, 환경 변수 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h를 설정해. Claude Code v2.1.242 버전 이상이 필요하니까 구버전이면 업데이트부터 해. API에서 제공하는 최대 시간이 1시간이라(수명 주기가 딱 두 개뿐이라 더 늘릴 순 없어) 이게 최선이야. 만약 플랜 제한을 넘겨서 사용량 크레딧으로 돌리고 있다면 메인 대화도 5분으로 줄어드는데, 이때는 "promptCacheTtl": "1h"를 추가해서 1시간으로 유지할 수 있어.

한 가지 함정이 있는데, 에이전트 정의 자체에 수명(experimental: cacheTtl: 5m, v2.1.248 이상 버전의 frontmatter)을 설정할 수 있긴 하지만, 위에서 언급한 설정이 우선순위가 더 높아서 이 설정을 켜두면 개별 에이전트의 5m 설정은 무시돼. 만약 대부분의 서브 에이전트는 1시간으로 두고, 읽기 전용인 몇몇 에이전트만 5분으로 설정하고 싶다면, 저 설정을 끄고 settings.json의 env 블록에 ENABLE_PROMPT_CACHING_1H=1을 넣으면 돼. 이건 에이전트 정의 값보다 우선순위가 낮아서, 5m으로 지정한 곳은 그대로 5분이 적용되고 나머지는 1시간으로 유지되거든.

확인 결과

오후 중간쯤에 서브 에이전트 3개가 작업 중인 상태에서 설정을 적용해 봤어. 다음 요청부터 바로 1시간짜리 필드로 넘어가더라(각각 마지막으로 전체 쓰기를 한 번씩 해서 1시간짜리 버킷으로 이동한 뒤, 그 이후로는 전체 캐시 읽기를 기반으로 작은 쓰기만 발생함). 그 뒤에 비슷한 서브 에이전트 5개를 돌려봤는데, 530턴 정도 돌면서 캐시 쓰기 300만 토큰을 썼어. 큰 쓰기는 각 에이전트의 첫 번째 작업에서만 발생했고, 검토용 서브 에이전트는 80분 동안 147턴을 돌았는데 재쓰기가 아예 없었어. 수정 전에는 서브 에이전트 4개만으로 5시간짜리 윈도우 할당량이 2%에서 100%까지 찼었는데, 수정 후에는 4개 돌려도 0%에서 22%밖에 안 차더라.

트레이드오프

1시간짜리 쓰기는 1.25배가 아니라 2배 비용이 들어. 그래서 재쓰기를 절대 안 할 짧은 서브 에이전트는 컨텍스트 비용을 4분의 3 정도 더 내게 돼. 하지만 재쓰기를 두 번 이상 할 에이전트라면 무조건 이득이지. 테스트를 돌리는 에이전트라면 당연히 이득이고. 어디선가 "서브 에이전트는 빨리 끝나니까 5분으로 유지하라"는 조언을 볼 수도 있는데, 긴 테스트 명령어를 실행하는 상황이라면 그건 완전히 틀린 말이야. 지금 우리가 다루는 상황이 딱 그거거든.

설정만으로는 해결되지 않는 나머지 절반

아무리 1시간이라도 긴 작업을 돌리면 결국 만료돼. 서브 에이전트가 툴 호출 상태로 몇 분 이상 머물게 하지 마. 긴 작업은 백그라운드에서 돌리고 결과를 파일로 저장한 다음, 에이전트가 몇 분마다 그 파일을 확인하게 해. 아니면 작업 시간을 대충 안다면 딱 그 시점에 한 번만 깨우는 게 불필요한 깨우기를 줄이는 방법이야. 확인할 때마다 캐시 읽기가 발생해서 캐시가 계속 유지되거든. 내가 모든 서브 에이전트에게 주는 지침에도 이 내용을 넣었어.

측정해 본 사람들을 위한 질문 하나: 위에서 말한 1.25배, 2배, 0.1배는 API에 공개된 캐시 가격이야. 구독 모델의 5시간 및 주간 윈도우에서 1시간짜리 쓰기를 정확히 2배로 계산하는지, 아니면 다른 방식으로 계산하는지는 어디를 찾아봐도 안 나오더라. 내 윈도우는 쓰기가 중요하고 읽기는 거의 영향이 없는 것처럼 작동했는데, 정확한 가중치는 모르겠어.

1시간 수명으로도 해결 안 되는 문제 하나: 백그라운드 서브 에이전트가 작업을 끝낸 뒤 첫 메시지를 보낼 때, 컨텍스트 거의 전체를 다시 써버려(내가 측정한 두 사례에서는 각각 243K, 399K 토큰의 캐시 쓰기가 발생했고, 유휴 시간은 1시간 이내인 49분, 54분이었음). API는 이 누락을 messages_changed라고 표시하는데, 수명 문제는 아니라는 거지. 측정 데이터, 버전 기록, 그리고 본인 트랜스크립트 확인 방법은 별도 게시물에 정리해 뒀어: https://www.reddit.com/r/ClaudeAI/s/UU9dt6F2Dq. 만약 같은 패턴을 확인했다면, 본인의 Claude Code 버전, 모델, 관련 발견 사항을 거기 링크된 업스트림 이슈에 추가해 줘. 그래야 Anthropic이 수정할 근거가 생기지.

도움이 됐으면 좋겠네. 에이전트가 테스트를 돌리거나 긴 폴링 호출을 기다리는 동안 윈도우가 바닥난다면, 십중팔구 이 문제일 거야.

문서랑 내가 언급한 블로그 포스트는 첫 번째 댓글에 링크 달아둘게.