코딩 에이전트의 매 턴(turn)마다 저장소 컨벤션 (repository conventions), 도구 스키마 (tool schemas), 보안 규칙 (security rules), 의존성 스냅샷 (dependency snapshots), 그리고 긴 작업 이력 (task history)과 같은 동일하고 비용이 많이 드는 자료를 다시 전송할 수 있습니다. 만약 이러한 안정적인 컨텍스트 (context)가 도구 호출 (tool call)마다 처음부터 다시 처리된다면, 에이전트는 유용한 다단계 작업을 시작하는 바로 그 시점에 더 느려지고 더 많은 비용을 발생시키게 됩니다.

**AI 코딩 에이전트를 위한 프롬프트 캐싱 (Prompt Caching)**은 실질적인 해결책이지만, 단순히 켜두기만 하면 끝나는 스위치가 아닙니다. 캐시는 안정적인 요청 접두사 (request prefix)를 설계하고, 계속 변하는 데이터를 접두사에서 제외하며, 실제 요청이 캐시에 제대로 적중(hit)하고 있는지 측정할 때만 도움이 됩니다.

이 가이드는 모든 요청을 실수로 캐시 미스 (cache miss)로 만들지 않으면서, **LLM 프롬프트 캐싱 (LLM prompt caching)**을 사용하여 AI 에이전트의 비용과 지연 시간 (latency)을 줄이는 방법을 보여줍니다.

유용한 사고 모델: 안정적인 접두사, 휘발성 꼬리 (stable prefix, volatile tail)

대부분의 제공업체(provider) 캐시는 요청의 일치하는 접두사 (prefix)를 재사용합니다. 코딩 에이전트의 경우, 각 요청을 두 영역으로 나누십시오:

원칙은 간단합니다: 공통적이고, 크며, 천천히 변하는 컨텍스트를 먼저 배치하고, 요청마다 달라지는 데이터를 마지막에 배치하십시오. OpenAI의 문서는 캐싱을 일치하는 접두사 메커니즘 (matching-prefix mechanism)으로 설명합니다. Google 역시 암시적인 캐시 적중률을 높이기 위해 크고 공통된 콘텐츠를 프롬프트의 시작 부분에 배치할 것을 권장합니다. 특정 제공업체가 특정 요청 형태를 캐싱할 것이라고 가정하기 전에 OpenAI의 프롬프트 캐싱 가이드와 Google의 컨텍스트 캐싱 가이드를 읽어볼 가치가 있습니다.

코딩 에이전트가 유독 캐싱에 적합한 후보인 이유

채팅 앱은 짧은 시스템 프롬프트 (system prompt)를 가질 수 있습니다. 하지만 실제 서비스되는 코딩 에이전트는 훨씬 더 많은 반복적인 입력을 포함하는 경우가 많습니다:

• 저장소 맵 (repository map) 및 언어 관례 (language conventions)
• 검색, 테스트, git, 이슈 트래킹을 위한 도구 스키마 (tool schemas)
• 쓰기 및 셸 (shell) 작업에 대한 승인 정책 (approval policy)
• 원하는 계획(plan) 또는 패치(patch) 형식의 예시
• 여러 단계에 걸쳐 유지되는 작업별 워킹 세트 (task-specific working set)

이는 반복적인 워크로드 (workload)를 생성합니다. 첫 번째 요청이 캐시를 생성하거나 워밍업 (warm)할 수 있으며, 이후의 요청들은 공유 접두사 (shared prefix)가 호환성을 유지하는 한 이를 재사용할 수 있습니다. 이는 한 세션 내에서 계획을 세우고, 파일을 검사하고, 테스트를 실행하며, 패치를 수정하는 에이전트에게 특히 유용합니다.

이것은 더 나은 컨텍스트 선택 (context selection)을 위한 대체재가 아닙니다. 관련 없는 100 KB의 저장소 텍스트를 캐싱하는 것은 여전히 모델이 관련 없는 자료를 바탕으로 추론하게 만듭니다. 먼저 컨텍스트를 작업에 필요한 내용으로 줄인 다음, 안정적인 부분을 캐싱하십시오.

캐시 히트 (cache hits)를 보호하는 요청 구조

프롬프트 조립 (prompt assembly)을 단순한 문자열 연결 작업이 아닌 하나의 인터페이스 (interface)로 취급하십시오. 안정적인 접두사 (stable prefix)에 버전을 매기고, 그 뒤에 동적인 입력값들을 추가하십시오.

const stablePrefix = [
  'agent-policy:v3',
  REPOSITORY_CONVENTIONS,
...

정확한 필드 이름과 제어 방식은 제공자 (provider)마다 다릅니다. Anthropic은 cache_control을 통해 자동 캐싱 (automatic caching)과 명시적 캐시 중단점 (explicit cache breakpoints)을 지원합니다. Anthropic의 문서는 최소 캐싱 가능 길이, TTL 선택, 가격 책정, 그리고 명시적 중단점의 제한 사항도 설명하고 있습니다. Anthropic의 공식 프롬프트 캐싱 문서를 참조하세요.

API가 포터블 (portable)하지 않더라도 아키텍처는 포터블하게 유지할 수 있습니다:

1. 하나의 결정론적인 (deterministic) 안정적 접두사를 구축합니다.
2. 이를 작업 및 도구 결과 데이터 앞에 배치합니다.
3. 의도적으로 버전을 관리합니다 (예: tool-schema:v7).
4. 제공자 응답에서 캐시 읽기 (cache-read) 및 캐시 쓰기 (cache-write) 사용량을 로그로 남깁니다.
5. 캐시 미스 (misses)를 조사할 때는 한 번에 한 레이어씩 변경합니다.

에이전트 하네스 (agent harnesses)에서의 세 가지 캐시 미스 함정

1. 앞부분에 위치한 동적 메타데이터 (Dynamic metadata at the front)

타임스탬프(Timestamp), UUID, 사용자별 인사말 또는 트레이스 ID(Trace ID)가 공유된 지침(Instructions) 앞에 위치하면, 원래는 동일했을 요청들이 서로 달라질 수 있습니다. 관찰 가능성(Observability)을 위한 메타데이터는 애플리케이션 로그에 기록하거나 요청의 끝부분(Tail)에 배치해야 하며, 재사용하고자 하는 접두사(Prefix)에 넣어서는 안 됩니다.

2. 매 턴마다 도구 스키마를 재구축하는 경우 (Rebuilding tool schemas every turn)

도구 정의(Tool definitions)가 의미론적으로는 동일하더라도 직렬화(Serialized)되는 순서가 다르면, 접두사 기반 캐시(Prefix-based cache)가 일치하지 않을 수 있습니다. 순서를 정형화(Canonicalize)하고, 스키마 버전을 고정하며, 실제 도구 계약(Tool contract)이 변경될 때만 안정적인 블록을 재생성하세요.

3. 장기 유지되는 정책과 빠르게 변하는 검색 결과의 혼합 (Mixing long-lived policy with rapidly changing retrieval)

저장소 전체에 적용되는 정책은 며칠 동안 안정적일 수 있습니다. 반면, 검색된 상위 10개의 코드 청크(Code chunks)는 매 턴마다 바뀔 수 있습니다. 이들을 별도의 레이어로 유지하세요. 정책과 내구성이 있는 저장소 요약(Repository summary)은 캐싱하고, 사용자 작업 직전에 신선한 검색 결과(Retrieval)를 추가하십시오. 비용이 많이 든다는 이유만으로 매 턴 발생하는 대규모 RAG 페이로드(Payload)를 안정적인 접두사(Stable prefix)에 강제로 밀어 넣지 마세요.

캐시된 토큰뿐만 아니라 결과(Outcomes)를 측정하세요

높은 캐시 읽기(Cache-read) 횟수는 고무적이지만, 그것이 비즈니스 지표는 아닙니다. 에이전트 실행을 평가하는 데 사용하는 동일한 트레이스(Trace)에 캐시 필드를 추가하세요:

agent_run_id
model
prompt_version
...

그런 다음 안정적인 워크로드에 대해 캐시 적중률(Cache-hit rate), p50/p95 지연 시간(Latency), 그리고 **완료된 작업당 비용(Cost per completed task)**을 비교하십시오. 이는 자연스럽게 '트레이스-회귀(Trace-to-regression)' 워크플로로 연결됩니다. 만약 프롬프트 리팩토링(Refactor)이 캐시 미스를 증가시키거나 작업 완료 성능을 악화시킨다면, 배포 전에 이를 포착할 수 있습니다. 저는 Stop Replaying Coding-Agent Bugs by Hand에서 해당 평가 루프를 다루었습니다.

또한 캐싱을 동시성 제어(Concurrency control)와 분리하여 관리하세요. 저렴한 캐시된 요청이라도 수백 개의 하위 에이전트(Subagents)로 확산(Fan out)될 수 있습니다. 캐시 텔레메트리(Telemetry)를 예산 및 큐 제한(Queue limits)과 결합하십시오. 이는 Claude Code 2.1.212: Put Hard Budgets on Agent Fan-Out Before Costs Run Away에서 설명된 접근 방식과 같습니다.

프롬프트 캐싱 (Prompt Caching)이 적용되지 않는 경우

프롬프트 캐싱은 다음과 같은 상황에서는 적합하지 않습니다:

• 각 요청에 반복되는 입력이 거의 없는 경우
• 공유되는 접두사 (prefix)가 제공업체의 캐싱 가능 임계값 (cacheability threshold)보다 낮은 경우
• 모든 요청마다 정책 (policy), 도구 목록 (tool list), 또는 검색된 컨텍스트 (retrieved context)가 변경되는 경우
• 일회성 배치 작업 (one-off batch task)이 캐시 쓰기 (cache-write) 또는 저장 비용을 회수할 만큼 컨텍스트를 충분히 재사용하지 않는 경우
• 보안 모델이 관련 데이터 유지 (retention) 동작을 금지하는 경우

캐싱을 만능 할인 수단으로 취급하기보다는 제공업체의 데이터 유지 (retention), 데이터 처리 (data-handling), TTL (Time-to-Live), 그리고 가격 책정 세부 사항을 확인하십시오. 예를 들어, OpenAI는 최신 모델 제품군에 대해 캐시 유지 (cache retention) 및 캐시 쓰기 (cache-write) 계산을 문서화하고 있으며, Anthropic은 별도의 쓰기/읽기 가격 책정 및 TTL 옵션을 문서화하고 있습니다. Google은 모델별 암시적 캐시 임계값 (implicit-cache thresholds)을 문서화하고 캐시된 토큰 사용량 (cached-token usage)을 공개합니다.

지금 해야 할 일

1. 작업당 여러 번의 도구 호출 (tool calls)을 수행하는 PR-fix 에이전트와 같이 반복이 많은 워크플로 (workflow)를 하나 선택합니다.
2. 안전한 테스트 워크로드에 대해 전체 요청 구조를 로그로 기록한 다음, 각 부분을 안정적 (stable) 또는 휘발성 (volatile)으로 분류합니다.
3. 안정적인 내용을 결정론적 접두사 (deterministic prefix)로 이동하고 해당 접두사에 버전을 부여합니다.
4. 제공업체가 지원하는 캐싱 메커니즘을 활성화하거나 구성합니다.
5. 트레이스 (traces)에 캐시 읽기 (cache-read), 캐시 쓰기 (cache-write), 지연 시간 (latency), 그리고 작업 완료당 비용 (cost-per-completed-task) 필드를 추가합니다.
6. 대표적인 작업들에 대해 소규모 카나리 (canary) 테스트를 실행하고 이를 캐싱되지 않은 베이스라인 (baseline)과 비교합니다.
7. 도구 실패 (tool failure)나 안전하지 않은 동작 (unsafe action)에 대해 수행하는 것과 마찬가지로, 알려진 캐시 미스 (cache miss)에 대한 회귀 케이스 (regression case)를 추가합니다.

멀티 에이전트 시스템 (multi-agent systems)의 경우, 코디네이터 경계 (coordinator boundary)에서 이 계약 (contract)을 명시적으로 만드십시오. 동일한 정책 (policy)과 도구 계약 (tool contract)을 재사용하는 것은 잘 정의된 범위의 팀이 임시방편적인 서브 에이전트 (subagents)의 집합보다 운영하기 쉬울 수 있는 이유 중 하나입니다. Claude Code Agent Teams: When Shared Context Beats More Subagents를 참조하십시오.

출처

• OpenAI API: 프롬프트 캐싱 (Prompt caching)
• Anthropic: 프롬프트 캐싱 (Prompt caching)
• Google Gemini API: 컨텍스트 캐싱 (Context caching)

현재 귀하의 코딩 에이전트가 매 단계마다 다시 전송하는 가장 비용이 많이 드는 안정적인 컨텍스트(stable context)는 무엇입니까: 도구 스키마 (tool schemas), 저장소 가이드 (repository guidance), 아니면 다른 것입니까?