Anthropic제품 블로그Agents
Claude 플랫폼으로 비용 절감과 성능 향상, 동시에 달성하기
프롬프트 캐싱(prompt caching), 지시문, 처리 강도를 세밀하게 조정하면 애플리케이션 성능 저하 없이 Claude 사용 비용을 효과적으로 낮출 수 있다.
성능과 비용은 흔히 트레이드오프 관계로 여겨진다. 비용을 줄이려면 성능을 희생해야 한다는 것이다. 하지만 실제로는 Claude 플랫폼을 사용하는 많은 애플리케이션이 세 가지 방법으로 성능 저하 없이 비용을 절감할 수 있다는 사실을 확인했다. 프롬프트 캐시 히트율을 최대화하고, 최신 Claude 모델로 업그레이드할 때 프롬프트의 안티패턴(anti-pattern)을 제거하고, 작업에 맞게 처리 강도를 조정하는 것이다. 이 가이드는 claude-api 스킬에 담았다. 이 글에서는 claude-api skill 을 활용한 Claude Code가 성능을 유지하거나 높이면서 비용을 줄이는 방법을 어떻게 찾아내는지 살펴본다.
프롬프트 캐시
Claude가 응답을 생성하기 전에, 먼저 프롬프트를 내부 작업 상태로 처리한다. 프리필(prefill)이라 부르는 이 단계가 입력 처리에서 비용이 가장 많이 드는 부분이다. 프롬프트 캐싱은 이 상태(키-값, 즉 KV 캐시)를 저장해둔다. 요청이 동일한 접두사로 시작되면 Claude는 이를 다시 계산하는 대신 저장된 값을 그대로 읽어온다. 캐시 읽기는 전체 입력 가격의 일부만 청구된다.
프롬프트 캐시를 효과적으로 활용하려면 몇 가지 사항을 고려해야 한다. 첫째, 프롬프트 캐시는 특정 모델에 고정된다. 둘째, 프롬프트 캐시 읽기는 프롬프트 접두사 전체에서 바이트 단위로 정확히 일치해야 한다. 마지막으로, 프롬프트 캐시에는 제한된 유효 기간(TTL)이 있다.
이를 염두에 두고 몇 가지 실용적인 팁을 소개한다.
- 대화 중간에 처리 강도 설정을 변경할 때는 주의가 필요하다. 이 설정은 콘텐츠보다 앞에 렌더링되어 캐시된 접두사의 일부가 된다. Opus 5와 Fable 5.1을 포함한 일부 Claude 모델에서만 캐시를 깨뜨리지 않고 대화 중간에 처리 강도를 변경할 수 있다.
- 접두사에 변동 값을 포함하지 말 것. 시스템 프롬프트에 동적 타임스탬프나 ID가 있으면 모델 호출마다 값이 달라져 캐시가 깨질 수 있다.
- 순서가 바뀌는 툴 정의는 피할 것. Claude Messages API를 사용할 때 프롬프트는 정해진 순서로 조립되며, 툴 정의가 맨 위에 렌더링된다. 툴 정의에 변경이 생기면 캐시가 깨진다.
- 대화를 분기할 때는 주의가 필요하다. 서브에이전트(subagent)와 브랜치는 분기의 접두사가 바이트 단위로 동일하고, 같은 모델을 사용하며, 같은 처리 강도를 유지할 때만 부모의 캐시를 공유한다.
해결 방법
프롬프트 캐시 관리에 대해 축적된 몇 가지 교훈이 있다.
- 프롬프트 캐시 히트율을 꼼꼼히 모니터링할 것. Claude Console과 캐시 진단 API는 프롬프트 캐시 미스 원인(그림 1)과 두 요청이 정확히 어디서 달라졌는지 등 프롬프트 캐시 진단 정보를 제공한다.
프롬프트 캐시 히트율을 꼼꼼히 모니터링할 것. Claude Console과 캐시 진단 API는 프롬프트 캐시 미스 원인(그림 1)과 두 요청이 정확히 어디서 달라졌는지 등 프롬프트 캐시 진단 정보를 제공한다.
프롬프트 캐시 히트율을 꼼꼼히 모니터링할 것. Claude Console과 캐시 진단 API는 프롬프트 캐시 미스 원인(그림 1)과 두 요청이 정확히 어디서 달라졌는지 등 프롬프트 캐시 진단 정보를 제공한다.
- 자주 사용하지 않는 툴은 지연 로드할 것. 모든 툴을 미리 선언하되, 드물게 쓰는 것은 defer_loading으로 표시하면 된다. 이렇게 하면 해당 툴이 캐시된 접두사에 포함되지 않고, Claude가 툴 검색으로 찾을 때만 대화에 추가되므로 캐시가 유지된다.
- 시스템 프롬프트 업데이트는 메시지로 적용할 것. Claude 플랫폼은 시스템 프롬프트를 직접 편집하는 대신 대화 중간에 시스템 지시문을 메시지로 추가할 수 있으며, 이렇게 하면 캐시가 유지된다.
- 안정적인 부분이 유지되도록 요청 구조를 구성할 것. 정적 콘텐츠(툴 정의와 시스템 프롬프트)를 먼저 배치하고, 늘어나는 대화 내용을 그 뒤에 붙인다(그림 2).
- 프롬프트 캐시가 이미 깨질 시점에 모델이나 처리 강도를 변경할 것. 컴팩션(compaction)과 같은 특정 작업은 이미 캐시(대화 내용)의 많은 부분을 재작성한다. 어차피 캐시 미스 비용을 지불하는 상황이므로, 이 시점이 모델이나 처리 강도를 전환하기에 적합하다.
- 대화가 길어질수록 캐시 중단점을 이동할 것. Claude 플랫폼에서는 자동 캐싱을 설정하여 캐시 중단점이 마지막으로 캐시 가능한 블록에 자동으로 적용되도록 할 수 있다.
- 캐시를 미리 워밍업할 것. 지연 시간을 줄이려면 max_tokens: 0과 명시적 캐시 중단점을 설정한 요청을 보내면 된다. 이렇게 하면 아무것도 생성하지 않고 프롬프트를 처리해 캐시에 저장한다. 세션 시작 시(예: 사용자가 타이핑하는 동안) 이 작업을 실행해두면 첫 번째 실제 요청이 웜 캐시에 접근하게 된다.
- 프롬프트 캐시 TTL을 초과하지 말 것. 5분짜리 캐시 TTL은 요청 시작 시점부터 카운트된다. 에이전트가 5분 이상 걸리는 툴 호출이나 서브에이전트 요청을 기다리는 동안, 결과가 돌아오기 전에 부모의 캐시가 만료될 수 있다. 이런 경우에는 접두사에 1시간 TTL을 설정하는 방법을 고려해보자.
지시문
프롬프트에는 모델의 취약점을 보완하기 위한 지시문이 쌓이기 마련이다. 이러한 지시문은 시간이 지남에 따라 최신 Claude 모델의 실제 성능과 맞지 않게 될 수 있다. 다음은 최신 Claude 모델의 성능을 저해하고 비용을 불필요하게 늘릴 수 있는 대표적인 프롬프팅 "안티패턴"이다.
- 검증 반복. "작업을 다시 확인하세요"나 "답하기 전에 두 번 검증하세요" 같은 지시문은 최신 모델이 문자 그대로 따르는 경향이 있어 토큰을 낭비할 수 있다.
- 철저함 강조 표현. "최대한 철저하게," "CRITICAL: YOU MUST ALWAYS…" 같은 표현은 최신 모델에서 장황한 응답과 불필요한 툴 호출로 이어질 수 있다.
- 고정된 절차와 스크래치패드 틀. 고정된 단계별 프로세스(예: "스크래치패드에 단계별로 생각하세요")나 추론 템플릿은 최신 모델에는 필요 없는 절차적 틀이다. 이런 구조는 모델의 기본 추론 위에 덧붙여져 불필요한 토큰을 소비할 수 있다.
- 낡은 예시. 이전 모델의 오류 패턴에 맞게 조정된 퓨샷(few-shot) 예시는 최신 모델이 굳이 필요하지 않은 요청에서도 긴 추론 과정을 모방하도록 가르칠 수 있다.
- 모순된 규칙. 최신 모델은 지시 따르기 능력이 한층 뛰어나다. "항상 정책 내에서 환불하라"와 "에스컬레이션 없이는 절대 환불하지 말라" 같은 모순된 지시를 최신 모델이 더 문자 그대로 따르다 보니 오히려 성능이 저하될 수 있다.
- 오래된 설정. 이전 Claude 세대에 맞게 작성된 설정(예: 수동 thinking 예산)은 최신 모델로 업그레이드할 때 Claude 플랫폼에서 거부될 수 있다.
해결 방법
이러한 안티패턴을 감지하는 새 명령어를 claude-api 스킬에 추가했다. Claude Code에서 프롬프트, 스킬, 또는 툴 설명을 대상으로 /claude-api prompt-audit을 실행하면 된다. 이 감사는 작업 디렉터리 내의 모든 항목을 대상으로 하며, Claude API를 호출하는 애플리케이션 코드와 Claude Code의 자체 설정(예: CLAUDE.md나 스킬)도 포함된다.
예를 들어, 고객 지원 벤치마크에서 Opus 4.8에서 Opus 5로 모델을 마이그레이션하는 테스트를 진행했다. 깔끔한 프롬프트에서 시작해 안티패턴을 하나씩 심었다. 지원 종료된 thinking 설정, 모순된 환불 규칙 한 쌍, 수동 스크래치패드, "두 번 검증하세요", "최대한 철저하게", 6단계 의무 절차로, 총 여섯 개의 레거시 프롬프트를 만들었다.
각 프롬프트를 Opus 4.8에서, 모델 ID만 변경한 Opus 5에서, 그리고 프롬프트별로 /claude-api prompt-audit을 한 번 실행한 후의 Opus 5에서 테스트했다(그림 3은 여섯 개 결과의 평균을 보여준다).
그림 3 | Opus 4.8에서 Opus 5로 모델 마이그레이션 시 프롬프팅 안티패턴의 영향.
Opus 5에서 검증 반복("두 번 검증")은 모든 환불 처리마다 주문 조회를 중복 실행해 불필요한 토큰을 소비했다. 철저함 강조 표현("최대한 철저하게")은 불필요한 지식 베이스 검색을 수십 회나 발생시켰다.
/claude-api prompt-audit을 실행하면 안티패턴이 제거되어 평균적으로 비용이 14.6% 줄고 정확도가 5.3% 높아졌다. 불필요한 툴 호출과 중복 추론이 사라지면서 비용이 낮아졌다. 정확도 향상에는 세 가지 이유가 있다. 지원 종료된 thinking 설정으로 인해 API가 모든 라우팅 요청을 거부했다. 모순된 환불 규칙 때문에 Opus 5가 정당한 환불 네 건을 고객에게 확인을 요청하며 보류했다. 그리고 수동 스크래치패드가 Opus 5의 내장 thinking과 충돌하여, 세 건의 티켓에서 툴 호출을 추론 과정 안에 작성하고 실제로는 실행하지 않았다.
처리 강도
처리 강도(Effort)는 Claude에게 "얼마나 열심히 작업할지"를 알려준다. 처리 강도가 낮으면 Claude는 일반적으로 더 빠르게 결론에 도달한다. 처리 강도가 높으면 Claude는 답하기 전에 깊이 고민하고, 검증하고, 대안을 탐색한다.
단일 모델에서 처리 강도에 따른 비용 대 성능 비율은 다양하게 나타날 수 있다. 예를 들어, Claude Fable 5는 FrontierCode Diamond(가장 어려운 50개 작업)에서 낮은 처리 강도로 작업당 $5.35에 11.5% 점수를 기록한다. 최대 처리 강도에서는 Fable 5가 작업당 $19.00에 30.9%를 달성한다. 처리 강도를 높이면 비용이 약 3.5배 늘어나는 대신 점수가 약 2.7배 향상된다(+19점, 그림 4).
Claude Fable 5.1에서 Humanity's Last Exam(툴 미사용)은 가파른 상승 곡선을 보이다 마지막 단계에서 수익이 급격히 감소한다. 낮은 처리 강도에서는 문항당 약 $0.30에 약 53% 점수를 기록하고, 최대 처리 강도에서는 약 $2.23에 약 61%를 달성한다. 최대 처리 강도까지 올리는 마지막 단계에서는 비용이 46% 더 드는 반면 점수는 약 0.5점 상승에 그친다. 이 정도 향상은 벤치마크의 실행 간 노이즈 범위 안에 들어, 측정 가능한 성과 없이 더 많은 비용을 지불하는 셈이다.
처리 강도는 양방향으로 잘못 조정될 수 있다.
- 높을수록 항상 좋다는 가정. 처리 강도가 높으면 과도한 사고로 이어질 수 있다. Claude가 작업에 필요한 수준 이상으로 오래 고민하면 비용과 지연 시간이 늘어나고 답변 품질이 저하될 수 있다. 심층 고민은 아직 찾지 못한 증거가 있을 때만 도움이 된다.
- 낮은 처리 강도에 치우치기. 너무 낮게 설정하면 Claude가 충분한 증거를 확보하기 전에 멈춰버린다. 툴 호출이 줄어들고, 세 번째 검색 결과 대신 첫 번째 결과만으로 답할 수 있다. 어려운 단계에서 덜 고민하고, 스스로라면 실행했을 검증 과정을 건너뛴다. 답변이 완성된 것처럼 보이지만 실제로는 불완전한 정보에 기반한 결과다.
해결 방법
처리 강도를 조정하는 데 유용한 방법이 몇 가지 있다.
- 더 강한 모델을 낮은 처리 강도로 테스트할 것. 낮은 처리 강도의 더 강한 모델이 높은 처리 강도의 약한 모델보다 저렴할 수 있다. 예를 들어, CursorBench 3.2에서 낮은 처리 강도의 Claude Fable 5.1은 높은 처리 강도의 Fable 5와 동등한 성능을 3분의 1 비용으로 달성한다(그림 5). 새 모델이 더 저렴한 데는 두 가지 이유가 있다. 낮은 처리 강도에서 작업당 연산량이 적고, Fable 5.1의 프롬프트 캐시 읽기 가격이 백만 토큰당 $0.25로 Fable 5의 $1.00보다 훨씬 저렴하다. Fable 5 가격 기준으로 계산해도 낮은 처리 강도의 Fable 5.1은 약 40% 저렴하다.
- 작업의 특성을 파악할 것. 다양한 처리 강도 범위에 걸쳐 애플리케이션 성능을 측정하면 특정 작업의 비용 대 성능 트레이드오프를 이해하는 데 유용하다. 포화되지 않은 평가에서 처리 강도별 비용-성능 곡선이 평탄하게 나타난다면, 해당 작업은 thinking 연산에 제약받지 않는 것이므로 처리 강도를 높여도 효과가 없다.
이 조정 작업은 대개 여러 모델과 처리 강도에 걸쳐 평가를 실행하는 과정을 포함한다. Claude Code에서 /claude-api hillclimb는 이 탐색을 자동으로 수행한다. 평가 데이터를 학습 세트와 테스트 세트로 나누고, 설정 변경을 제안하며, 실패한 학습 사례를 읽어 발견된 문제를 수정한다.
고객 지원 벤치마크에서 기본(높은) 처리 강도의 Opus 4.8을 시작점으로 이 기능을 테스트했다. 힐클라이머는 먼저 낮은 처리 강도의 Opus 5를 시도했고, prompt-audit을 적용하여 의무적 툴 호출 절차, 스크래치패드 단계, 모순된 규칙을 제거했다. 그 결과 학습 정확도 98.9%로 Opus 4.8 기준선을 넘어섰고 티켓당 비용도 2.6센트로 줄었다.
이후 낮은 처리 강도의 Sonnet 5로 단계를 낮췄고, 티켓당 1센트로 비용은 더 줄었지만 정확도가 88.9%로 떨어졌다. Claude는 실패한 학습 티켓을 읽고 프롬프트에 라우팅 규칙과 환불 한도 상호 참조를 추가하여, 같은 비용에 Sonnet 5의 정확도를 98.9%로 회복시켰다.
탐색에서 한 번도 보지 못했던 14개의 보류 티켓에서, 최종 설정은 기존 구성의 78.6%에 비해 90.5% 점수를 기록했으며 비용은 약 5분의 1 수준이었다.
비용 절감 자동화
프롬프트 캐싱, 지시문, 처리 강도는 비용 절감의 주요 레버다. 더 많은 내용은 문서에서 확인할 수 있다. Claude API를 사용하는 애플리케이션 코드의 비용을 종합적으로 감사하기 위해 /claude-api cost-optimize를 추가했다. 이 명령어는 지출이 집중되는 부분을 파악하고, 비용 절감을 적용하며, 평가를 제공하면 절감액과 성능의 트레이드오프를 보여준다.
cost-optimize는 먼저 토큰이 어디에 사용되는지 파악한다. Claude Admin API 키가 있으면 조직의 사용량 및 비용 리포트를 활용하고, 애플리케이션이 각 API 응답의 usage 객체를 로깅하면 이를 사용한다. 둘 다 없으면 요청 생성 코드를 읽고 추정한다.
이후 프롬프트 캐싱을 시작으로 활용 가능한 절감 방안을 순위별로 정리한다. 각 요청에 포함되는 내용 축소(prompt-audit 포함), 출력 제한, 자동화 작업 일괄 처리가 이에 포함된다. 평가를 제공하면 처리 강도와 모델 선택에 따른 비용 및 성능을 추가로 계산한다.
Sonnet 5를 기준선으로 삼아 네 개의 공개 벤치마크에서 이를 실행했다(그림 7):
- LegalBench(비용 약 58% 절감): cost-optimize는 작업 간 공유 접두사 캐싱, 낮은 처리 강도 설정, 배치(Batch) API 처리를 제안했다. Thinking 토큰이 102,779개에서 8,284개로 줄었지만 통과율은 노이즈 범위 내에서 유지되고 비용은 약 58% 감소했다.
- tau2-bench retail(비용 약 73% 절감): 명시적 중단점을 지정한 프롬프트 캐싱을 구현하여 cost-optimize가 통과율을 유지하면서 비용을 73% 절감했다.
- OfficeQA Pro(비용 약 52% 절감): cost-optimize가 일괄 처리와 문서 캐싱을 추가하여 비용을 $136.20에서 $64.87로 줄였다.
- SWE-bench Verified(비용 약 55% 절감): cost-optimize는 기본 설정이 이미 올바르게 캐싱되고 있음을 확인했다. 절감은 처리 강도를 중간으로 설정하고 에이전트 출력을 몇 문장으로 제한하는 데서 비롯됐다. 작업당 중간 단계 수는 29에서 17로 줄었고 프롬프트 토큰은 75.2M에서 33.7M으로 감소했다.
시작하기
최신 Claude 모델로 마이그레이션한 후 기존 프롬프트를 점검하고 싶다면 /claude-api prompt-audit으로 시작하자. 작업 디렉터리의 프롬프트, 스킬, 툴 설명을 스캔하며, Claude API를 호출하는 애플리케이션 코드와 Claude Code의 설정(CLAUDE.md, 스킬)이 대상이 된다. 최신 모델의 성능을 저해하는 일반적인 안티패턴을 제거한다.
Claude API를 사용하는 애플리케이션의 비용을 감사하고 싶다면 /claude-api cost-optimize를 활용하자. 토큰 지출을 분석한 뒤 다양한 레버를 테스트한다. prompt-audit을 적용하는 것은 물론, 프롬프트 캐싱, 자동화 작업 일괄 처리, 출력 제한을 통한 비용 절감 방법을 점검한다. 평가를 제공하면 처리 강도와 모델 선택의 트레이드오프도 측정한다.
비용과 성능에 대한 반복적 탐색에는 /claude-api hillclimb를 사용하자. 평가 데이터를 입력하면 Claude가 학습 세트와 테스트 세트로 나눈 뒤, 기준 성능을 유지하면서 비용을 줄이는 방향으로 애플리케이션 업데이트를 제안한다. Claude는 실패한 학습 사례를 읽어 탐색을 안내하고, 최종 설정은 보류된 테스트 세트로 평가된다.
더 알아보기:
