클로드 코드 팁: 테스트·빌드 대기 서브에이전트에 1시간 캐시 지정하기

X(트위터)의 Vox(@Voxyz_ai)가 공유한 Claude Code 서브에이전트 프롬프트 캐싱 최적화 팁입니다. 긴 테스트 스위트 실행이나 빌드 완료를 기다리느라 작업 중간에 유휴 상태가 발생하는 서브에이전트에 한해 개별적으로 1시간 캐시(cacheTtl: 1h)를 부여하는 설정법을 다룹니다.

이미지 출처: X @Voxyz_ai

기본적으로 Claude Code 서브에이전트의 프롬프트 캐시는 아무런 활동이 없으면 5분 뒤에 만료됩니다. 만약 서브에이전트가 테스트 스위트를 구동하거나 빌드 출력을 기다리는 동안 5분 이상 대기 상태에 머무르면, 다음 단계를 실행할 때 전체 컨텍스트를 처음부터 다시 처리(reprocessing)해야 합니다. 이는 캐시된 컨텍스트를 즉시 읽는 것보다 속도가 느릴 뿐 아니라 토큰 사용량 한도도 더 많이 소모하게 만듭니다.

하지만 모든 서브에이전트를 무조건 1시간 캐시로 전환해서는 안 됩니다. 공식 문서 기준 1시간 캐시 쓰기 비용은 기본 입력 가격의 2배(API 기준)이며, 기본 5분 캐시 쓰기는 1.25배입니다. 중간 멈춤 없이 곧바로 작업을 이어가 몇 분 안에 완료되는 일반 서브에이전트는 긴 캐시의 이점을 얻지 못하고 쓰기 비용만 더 지불하게 됩니다.

작업 특성에 따른 캐시 수명 설정 기준

서브에이전트의 역할과 대기 패턴에 따라 캐시 수명을 차등 적용해야 합니다.

• 5분 이상 유휴 대기가 발생하는 서브에이전트: 테스트 실행, 로컬 빌드, CI 완료 대기 등으로 중간에 5분 넘게 대기하거나 나중에 다시 재개할 서브에이전트는 파일 상단에 experimental: 블록을 두고 그 아래 cacheTtl: 1h를 추가합니다.
• 연속 실행되어 빠르게 완료되는 서브에이전트: 별도 대기 없이 몇 분 안에 모든 작업을 끝내는 서브에이전트는 기본값인 5분을 그대로 유지합니다.
• 전역 설정(subagentPromptCacheTtl) 우선순위 주의: 만약 설정 파일에 subagentPromptCacheTtl을 이미 등록해 두었다면, 개별 서브에이전트 파일의 설정보다 전역 설정이 우선 적용(override)되며 워크플로우와 컨텍스트 압축(compaction) 동작에도 영향을 미칩니다. 개별 서브에이전트 단위로 세밀하게 제어하려면 이 전역 설정을 먼저 제거해야 합니다.
• 메인 세션의 캐시 고려: API 키, 클라우드 제공업체, 또는 플랜 한도를 초과해 사용 크레딧을 소모 중인 구독 환경에서는 메인 세션 역시 기본 캐시 수명이 5분으로 제한됩니다. 작업 중간에 자리를 자주 비우는 사용자라면 메인 세션 설정에 promptCacheTtl: 1h 지정을 검토할 수 있습니다.
• Opus 5.5 등 100만 토큰(1M) 모델의 압축 시점 조정: 1M 컨텍스트 모델은 기본적으로 약 967K 토큰에 도달할 때까지 컨텍스트를 압축하지 않으므로, 그전까지는 매 메시지마다 전체 대화 기록이 그대로 전달됩니다. 터미널에서 /autocompact 400k 명령을 한 번 실행해 두면 400K 시점에서 자동 압축이 수행됩니다.

개별 서브에이전트 설정 요구사항 및 코드

개별 서브에이전트에 cacheTtl을 지정하려면 Claude Code 버전 2.1.248 이상이 필요합니다.

사용자 전역 서브에이전트 경로(~/.claude/agents) 또는 프로젝트 전용 서브에이전트 경로(.claude/agents)의 대상 파일 상단에 아래 설정을 추가합니다:

experimental:
  cacheTtl: 1h

이미 파일 헤더에 experimental: 블록이 정의되어 있다면 중복으로 생성하지 말고 기존 블록 아래에 cacheTtl: 1h를 들여쓰기하여 추가합니다.

자동 설정 지시 프롬프트

Opus 5.5 모델을 실행 중인 Claude Code 세션에 공식 문서 링크와 함께 아래 프롬프트를 전달하여 환경을 점검하고 설정을 자동화할 수 있습니다:

"Read this doc, plus the subagent docs it links to, and set up my cache lifetimes by job:
1. First run claude --version. Setting cacheTtl on a single subagent needs 2.1.248 or later. If mine is older, tell me. Don't upgrade it yourself.
2. List every subagent in ~/.claude/agents and .claude/agents. For ones that might sit idle for more than 5 minutes partway through (running tests, builds, waiting on CI), or that I'll resume later, add these two lines at the top of the file:
experimental:
  cacheTtl: 1h
If there's already an experimental block, add cacheTtl under it. Don't write a second one. Leave the ones that run straight through and finish in a few minutes on the default. Give one line of reasoning for each.
3. Check ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json (including their env blocks) and my current environment variables for subagentPromptCacheTtl, CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL or FORCE_PROMPT_CACHING_5M. If any of them is set, tell me it overrides the per-subagent settings and ask whether to remove it.
4. Ask me whether I'm on a subscription, an API key or a cloud provider. Don't read any keys yourself. Unless I'm on a subscription within its plan usage, ask whether I often step away for more than 5 minutes mid-session, and if I do, set promptCacheTtl to 1h.
Show me what you'll change first, and don't write anything until I confirm."

원문 출처

• Vox (@Voxyz_ai) X 게시글: https://x.com/Voxyz_ai/status/2109056129884123370