Claude Code 서브 에이전트 캐시 TTL 설정으로 재작성 비용 절감

Claude Code 구독 플랜에서 서브 에이전트(sub-agent)의 프롬프트 캐시 TTL이 기본 5분으로 설정되어 있어, 빌드나 테스트 등 5분 이상 소요되는 도구 호출 후 캐시가 만료되는 문제가 발생한다. 이로 인해 다음 요청 시 전체 컨텍스트를 비싼 요금으로 다시 작성(cache-write)해야 하며, 이는 5시간 사용 윈도우를 빠르게 소모시킨다.

비용 구조 및 문제 원인

Anthropic의 가격 정책에 따라 5분 캐시 write는 일반 input의 1.25배, 1시간 캐시 write는 2배의 비용이 발생한다. 서브 에이전트가 긴 도구 호출 대기 중 캐시가 만료되면 수십만 토큰 규모의 컨텍스트를 재작성해야 하므로 비용이 급증한다. 실제 사례에서 한 서브 에이전트가 하루 8회 재작성하며 약 540만 토큰의 cache write가 발생했다.

최적화 설정 및 효과

해결책으로는 ~/.claude/settings.json에 "subagentPromptCacheTtl": "1h"를 추가하거나 환경변수 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h를 설정하면 된다. (Claude Code v2.1.242 이상 필요)

• 비용 절감: 설정 변경 후 5개 서브 에이전트 기준 cache write가 300만 토큰 수준으로 유지되었으며, 대부분의 에이전트에서 첫 요청 이후 대규모 재작성이 발생하지 않았다.
• 사용량 개선: 5시간 윈도우 사용량이 수정 전에는 4개 서브 에이전트로 100%까지 소모되었으나, 수정 후에는 22%까지만 소모되어 크게 낮아졌다.
• 재작성 방지: 리뷰 서브 에이전트는 80분간 147턴 수행하며 재작성 0회를 기록했다.

주의 사항 및 한계

1시간 TTL 설정 시에도 긴 작업 중 만료될 수 있으므로, 긴 작업은 background로 실행하고 파일로 결과를 저장한 뒤 주기적으로 확인(check)하도록 지시하여 캐시를 warm 상태로 유지해야 한다. 또한, 짧은 서브 에이전트는 1시간 설정으로 인해 약 0.75 context 분량의 추가 비용이 발생할 수 있어, 2회 이상 재작성이 예상되는 경우에만 유리하다.