서브에이전트가 기본값으로 5분 캐시를 쓴다고?! 🤦🏻♂️
Subagents use a 5-min cache by default?!? 🤦🏻♂️
핵심 요약
Claude Code의 서브에이전트 기본 캐시 TTL 설정이 비용에 미치는 영향과 최적화 방법을 공유합니다.
- 캐시 설정 문제 — 서브에이전트의 5분 캐시 TTL이 만료되면 전체 컨텍스트를 재처리하여 비용이 급증함
- 설정 변경 주의 — 1시간 캐시로 변경 시 쓰기 비용이 증가하므로 사용 패턴에 따라 신중히 결정해야 함
- 비용 최적화 팁 — 루프를 활용해 캐시를 유지하거나, 오케스트레이션 에이전트 위주로 캐시를 최적화하는 것이 유리함
- 로그 분석 권장 — 캐시 미스 원인을 파악하고 자신의 워크플로우에 맞는 TTL 설정을 찾는 것이 중요함
다들 주목해라. 이미 누가 얘기했는데 내가 놓친 걸 수도 있는데, 만약 그렇다면 너희들도 많이들 놓쳤을 거 같아서 글 쓴다.
며칠 전에 긴 작업 돌리다가 보니까 주간 예산이 생각보다 훨씬 빨리 녹아내리더라고. 좀 파보니까 Claude Code의 서브 에이전트들이 기본적으로 5분짜리 캐시를 쓰더라. 메인 세션은 구독하면 1시간 유지되길래 서브 에이전트도 당연히 그런 줄 알았지. 근데 아니었음.
이게 왜 문제냐면, 서브 에이전트가 5분 넘게 놀다가 Claude가 다시 호출하면 캐시가 날아가서 전체 컨텍스트를 처음부터 다시 처리해야 함. Opus 5.5 기준으로 캐시된 거 읽는 것보다 비용이 25배나 더 든다. 긴 작업 돌리면 이게 계속 반복되면서 니들 한도 야금야금 다 갉아먹는 거임.
해결법은 설정에 딱 한 줄 추가하면 된다:
"subagentPromptCacheTtl": "1h"
(Claude Code 2.1.242 버전 이상이어야 함.)
그렇다고 무지성으로 바꾸지는 마라. 1시간짜리 캐시 쓰기가 5분짜리보다 비용이 더 드니까, 서브 에이전트가 호출 사이에 좀 쉬다가 재사용되는 경우에만 이득임. 금방 끝나는 작업들이면 그냥 기본값 써라.
참고용으로 API 캐시 가격(백만 토큰당) 적어둔다:
Opus 5.5: $4 입력 · $5 (5분 쓰기) · $8 (1시간 쓰기) · $0.20 (캐시 읽기)
Fable 5.1: $10 입력 · $12.50 (5분 쓰기) · $20 (1시간 쓰기) · $0.25 (캐시 읽기)
이거 보고 다들 주간 예산 좀 아꼈으면 좋겠네 🙂

