클로드 코드 서브에이전트 프롬프트 캐시를 1시간으로 늘리는 설정법

클로드 코드(Claude Code)에서 서브에이전트·워크플로·백그라운드 작업은 메인 대화와 다른 캐시 수명(TTL) 구간에 속한다. 구독 요금제라도 따로 정하지 않으면 5분이다. 오래 도는 서브에이전트가 모델 호출 사이에 5분 넘게 쉬면 캐시가 만료돼 다음 호출에서 프롬프트를 처음부터 다시 처리한다.

~/.claude/settings.json에 다음을 넣는다.

{
  "subagentPromptCacheTtl": "1h"
}

값은 5m과 1h 두 가지만 받고 다른 값은 무시한다. 환경변수 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h로도 정할 수 있고, 환경변수가 설정보다 먼저 적용된다. 메인 대화는 promptCacheTtl(환경변수 CLAUDE_CODE_PROMPT_CACHE_TTL)로 따로 정한다. 모두 v2.1.242 이상에서 동작한다.

1시간 캐시 쓰기는 더 비싼 요율로 계산된다. 몇 분 안에 끝나는 짧은 서브에이전트라면 비용만 늘 수 있으니 호출 간격이 긴 작업에만 쓴다. FORCE_PROMPT_CACHING_5M=1이 켜져 있으면 이 설정보다 우선해 5분으로 돌아간다.