270초 규칙: Claude Code API 비용을 90% 절감하는 스마트 방법

Source: Dev.to

번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.

Key Takeaways

• Anthropic의 프롬프트 캐시 TTL은 5분입니다.
• 오케스트레이터 루프가 270초보다 빨리 실행될 경우 전체 입력 토큰 비용의 약 10 %를 지불합니다.

What Changed — The Cache TTL You’re Probably Ignoring

Anthropic의 프롬프트 캐시는 5분 TTL (Time To Live)을 가집니다. 5 분(300 초)이 지나면 캐시 항목이 만료되고 다음 Claude API 요청에서 전체 컨텍스트를 다시 처리하기 위해 전체 입력 토큰 비용을 지불하게 됩니다.

Claude Code 사용자가 멀티‑에이전트 시스템이나 오케스트레이션 루프를 구축할 경우, 이는 모든 것을 바꿔 놓습니다:

• > 300 seconds – 매 반복마다 전체 컨텍스트 비용을 지불
• < 300 seconds – 캐시 창 안에 머무르며 기본 입력 비용의 약 10 %만 지불
• ≈ 300 seconds – 최악의 경우 – 예측할 수 없는 캐시 동작

중요 업데이트: 2026년 3월, Anthropic은 기본 캐시 TTL을 1시간에서 5분으로 변경했습니다. 3월 6일 이전에 캐싱을 설정했다면 가정이 잘못됐을 수 있습니다. 텔레메트리를 비활성화하면 1시간 TTL도 완전히 비활성화됩니다.

왜 정확히 270초인가

수식은 간단하지만 중요합니다:

• 5 분 = 300 초
• 처리 시간, 컨텍스트 조립, 시계 오차 등을 위해 약 30 초를 차감

270 초는 신뢰할 수 있는 버퍼를 제공하여 모든 오케스트레이터 틱이 캐시 창 안에 도착하고 캐시된 입력 요금을 적용받게 합니다.

소스 시스템에서는 오케스트레이터 호출이 하루에 약 391 K 토큰에 대해 $0.50–$1.20 /일을 절감했습니다. 이 절감 효과는 병렬 에이전트 전반에 걸쳐 복합적으로 증가하고 사용량에 따라 규모가 커집니다.

Claude Code 워크플로에 적용하는 방법

1. 현재 캐시 동작 확인하기

# 캐시 확인을 위해 Claude API 호출에 추가
response = client.messages.create(...)
print(f"Cache read tokens: {response.usage.cache_read_input_tokens}")
print(f"Cache creation tokens: {response.usage.cache_creation_input_tokens}")

두 번째 호출을 5 분 이내에 수행했을 때 cache_read_input_tokens가 0이면 캐시가 정상적으로 작동하지 않거나 TTL 경계에 도달한 것입니다.

2. 오케스트레이터 루프 조정하기

import time

TICK_INTERVAL = 270  # seconds — Anthropic 캐시 TTL에 버퍼를 두어 맞춤

def orchestrator_tick():
    # 여기서 Claude Code 오케스트레이션 로직을 구현:
    # 1. 에이전트 상태 확인
    # 2. 완료된 작업 처리
    # 3. 새로운 작업 디스패치
    # 4. 상태 업데이트
    pass

while True:
    orchestrator_tick()
    time.sleep(TICK_INTERVAL)

3. 캐시를 위한 컨텍스트 구조화

캐시는 동일한 프롬프트에 대해 작동합니다. 오케스트레이터 컨텍스트가 틱 사이에 최소한으로만 변하도록 구성하세요:

• 시스템 프롬프트에 정적 지시문 유지
• 동적 상태는 별도의 메시지 역할로 분리
• 에이전트 상태 보고서는 일관된 포맷 사용

4. 270초 틱을 사용하면 안 되는 경우

적용 가능한 경우

• 다중 에이전트 오케스트레이션 시스템
• 주기적인 상태 확인 루프
• 백그라운드 모니터링 에이전트

적용되지 않는 경우

• 인터랙티브 Claude Code 세션
• 실시간 코딩 지원
• 지연에 민감한 워크플로

The Broader Principle

The 270‑second tick exemplifies a critical principle: orchestration cadence should be derived from infrastructure constraints, not arbitrary responsiveness goals.

An initial instinct to tick every 60 seconds (“responsive enough”) leads to paying ~4.5× more for the orchestrator context window when agents take minutes to complete work.

이것이 당신의 Claude 코드 프로젝트에 의미하는 바

• 기존 루프 감사: 주기적인 Claude 호출을 식별합니다.
• 캐시 모니터링 추가: 검증 체크를 로깅에 통합합니다.
• 에이전트 세분화 고려: 더 적고 장시간 실행되는 에이전트가 많은 짧은 체크 에이전트보다 비용 효율적일 수 있습니다.
• TTL 가정 문서화: 특히 인프라 변경 후 팀이 현재 캐시 동작을 알 수 있도록 합니다.

원문 기사에서 언급된 무료 리소스(예: whoffagents.com 아키텍처 및 GitHub 퀵스타트)는 이 최적화의 혜택을 받을 수 있는 멀티‑에이전트 시스템을 위한 구체적인 구현 패턴을 제공합니다.

원본은 gentic.news에서 발행되었습니다.