모델 선택과 컨텍스트 예산 관리

에이전트 작업에서는 어떤 모델을 쓸지를 초반에 정하게 됩니다. Claude 모델군은 비용·응답 속도·성능이 저마다 다르게 맞춰져 있어서, 어떤 모델을 고르는지가 가격과 속도의 바닥선을 정하고, 이후의 모든 결정은 그 바닥선 안에서 움직입니다.

현재 Claude 모델군은 네 층으로 나뉘고, 각각 비용·응답 속도·성능의 균형점이 다릅니다.

• Sonnet — 대부분의 프로덕션 작업에 균형이 잘 잡힌 기본값입니다.
• Haiku — 자기 성능 범위에 맞는 과제에서 속도와 비용 효율을 위해 만들어졌습니다.
• Opus — Sonnet의 범위를 넘어서는 까다로운 작업을 다룹니다.
• Fable — Anthropic이 만든 가장 성능이 높은 모델로, 복잡한 추론·고난도 코딩·리서치 종합·정교한 에이전트 작업처럼 최대한의 지능이 우선인 가장 까다로운 작업을 위해 만들어졌습니다.

모델 라인업과 식별자는 바뀔 수 있으니, 실제로 쓸 때는 빌드 시점에 platform.claude.com/docs에서 현재 목록을 확인하는 것이 좋습니다.

기본 시작점은 Sonnet입니다. Opus로 올리는 것은 평가셋(eval set)이 "Sonnet으로는 품질 기준을 못 맞춘다"고 알려 줄 때만 합니다. Haiku로 내리는 것도 마찬가지로, 단지 비용을 아끼려는 게 아니라 평가셋이 "이 과제에서는 품질이 조금 떨어져도 괜찮다"고 확인해 줄 때만 내립니다. 모델을 옮기는 결정은 늘 재 보고 내리는 것이 좋습니다.

모델이 정해지면 다음 제약은 컨텍스트 창입니다. 컨텍스트 창은 모델이 한 번에 받아들이는 텍스트 전체를 가리킵니다 — 프롬프트, 지금까지의 대화, 그리고 모든 도구 결과가 여기 들어갑니다. Claude가 돌려주는 도구 결과는 컨텍스트 창에 계속 쌓이고, 세션이 끝날 때까지 그대로 남습니다.

한 번만 주고받는 프롬프트라면 이게 잘 드러나지 않습니다. 하지만 도구를 열 번, 스무 번 호출하는 에이전트 세션에서는 창이 금세 차오르고, 일단 차면 에이전트는 내용을 압축하면서 세부를 잃거나 과제를 끝내기 전에 멈춰 버립니다. 그래서 에이전트 작업에서는 무엇을 컨텍스트 창에 넣고, 무엇을 요약해서 내보내고, 무엇을 아예 넣지 않을지를 미리 정해 두는 일이 중요해집니다. 이 선택의 묶음이 컨텍스트 엔지니어링입니다.

컨텍스트 창은 Claude가 작업하며 붙들고 있을 수 있는 공간이라고 생각하면 됩니다. 보내는 메시지, 돌려받는 도구 결과, 끼워 넣는 문서, Claude가 만들어 내는 응답 하나하나가 이 공간을 차지합니다.

요청이 이미 컨텍스트 창보다 크면, Messages API는 생성을 시작하기 전에 검증 오류로 요청을 거절합니다. 요청은 들어맞았는데 생성 도중에 한계에 닿으면, 현재 모델들은 그때까지 만든 출력을 model_context_window_exceeded 중단 사유와 함께 돌려줍니다. 어느 쪽도 오래된 내용을 소리 없이 잘라내지는 않습니다. 그래서 창 한계를 넘겨서도 세션을 이어 가려면, 다음 요청을 보내기 전에 애플리케이션이 직접 기록을 줄이거나 요약해서 관리하게 됩니다.

개발 단계에서는 테스트 입력이 작고 세션이 짧아 창이 좀처럼 차지 않습니다. 반면 프로덕션에서는 도구 출력이 테스트용보다 세 배에서 다섯 배까지 길어지고 세션도 더 여러 턴 이어져서, 쉰 번째 턴이 아니라 여덟 번째 턴에서 창이 차기도 합니다. 이걸 미리 대비하지 않으면 프로덕션 장애로 이어집니다.

컨텍스트 창 밖으로 상태(state)를 덜어 내야 하는 이유는 결국 예산입니다. 창에 들어간 토큰 하나하나가 입력 비용으로 돈이 들고 응답에 지연을 더하는데, 세션이 길어지면 이 둘이 함께 불어납니다. 아래 네 가지 전략은 그 예산을 관리하는 구체적인 방법이고, 저마다 다른 모양의 대화에 맞습니다.

FOUR STRATEGIES — 대화 모양별로 골라 쓰는 네 가지

네 전략은 컨텍스트 창에 무엇이 들어가는지를 관리합니다. 여기에 더해, 이미 창에 들어와 있는 것에 드는 비용을 줄여 주는 API 기능이 두 가지 있습니다.

프롬프트 캐싱(prompt caching)은 요청에서 잘 바뀌지 않는 앞부분(prefix)에 대해 처리해 둔 작업을 저장해 두었다가, 이어지는 요청이 같은 토큰을 다시 처리하지 않고 재사용하게 해 줍니다. 첫 요청이 그 앞부분을 캐시에 기록하고, 그 지점까지 같은 내용을 보내는 뒤이은 요청은 원래 비용의 일부만 냅니다. 가장 좋은 후보는 턴마다 거의 바뀌지 않는 부분입니다 — 긴 시스템 프롬프트, 큰 도구 정의 묶음, 반복해서 조회하는 참고 문서. 캐시하려는 마지막 블록에 ephemeral 타입의 cache_control 필드로 캐시 중단점(breakpoint)을 표시하면 켜집니다. 중단점은 최대 네 개까지 둘 수 있습니다. 시스템 프롬프트와 도구 스키마가 안정된 멀티턴(여러 턴을 주고받는) 세션이라면, 이 앞부분들을 한 번 캐시해 여러 턴에서 재사용하는 것이 가장 효과가 큰 비용 절감입니다.

토큰 세기(token counting)는 요청이 실패한 뒤가 아니라 나가기 전에 컨텍스트 압박을 재 볼 수 있게 해 줍니다. count_tokens 엔드포인트는 Messages 호출과 같은 요청 본문을 받아, 추론을 실행하지 않고 토큰 수만 돌려줍니다. 개발 중에는 컨텍스트 예산에 대한 가정이 테스트용이 아니라 실제 도구 출력에도 들어맞는지 확인하는 데 쓰고, 프로덕션에서는 창을 넘길 요청이 오류를 내기 전에 미리 걸러내는 데 씁니다.

검색으로 문서를 가져와 프롬프트에 넣는 경로, 곧 RAG는 세 군데에서 어긋날 수 있습니다 — 청킹, 임베딩 매칭, 그리고 프롬프트로 합치는 단계입니다.

• 청킹(chunking) — 문서를 검색 단위로 쪼개는 일입니다. 무엇을 검색 가능한 한 조각으로 볼지 정합니다. 너무 잘게 쪼개면 한 조각만으로는 주변 맥락이 없어 쓸모가 떨어지고, 너무 크게 쪼개면 한 조각에 관련 없는 텍스트가 섞여 매칭이 흐려집니다. 문장 단위나 절 단위로 약간 겹치게 쪼개는 것이 무난한 기본값입니다. 겹침이 중요한 이유는, 경계를 가로지르는 사실이 그러지 않으면 둘로 갈라져 찾아내기 어려워지기 때문입니다.
• 임베딩 매칭(embedding match) — 어떤 조각을 돌려줄지 정합니다. 의미가 가까운 것끼리 찾는 유사도 검색을 쓰기 때문에, 이게 늘 필요한 정확한 단어가 든 조각은 아닙니다. 특정 식별자를 찾는 질의는, 의미상 더 비슷한 결과가 앞 순위를 차지하면 정작 관련 조각을 놓칠 수 있습니다. 그래서 의미 검색 옆에, 정확한 단어를 맞추는 어휘 검색(lexical match)을 함께 돌리기도 합니다.
• 합치는 단계(assembly) — 가져온 조각들이 프롬프트가 기대하는 구조로 모델에 도착해야 하는 자리입니다. 그러지 않으면 모델은 가져온 텍스트가 아니라 자기 기억으로 답합니다.

한 번에 가져오는 방식(fetch-once)은 동작을 따져 볼 수 있는 시스템입니다. 어떤 질의에 어떤 조각이 검색됐는지 들여다보고, 그 검색을 직접 시험할 수 있습니다. 대신 인프라 비용이 듭니다 — 인덱스를 만들고, 저장하고, 자료가 바뀔 때마다 맞춰 갱신하고, 어디에 두든 보호해야 합니다. 여러 라운드에 걸쳐 검색하는 방식(search-across-rounds)은 그 인프라와, 거기서 오는 낡음(staleness)을 없앱니다. 모델이 질의 시점에 현재 파일을 직접 읽기 때문입니다. 대신 질의마다 토큰과 시간이 더 들고, 과정을 들여다보기가 어렵습니다.

그래서 안정된 참고 자료를 단순 조회로 쓴다면 인덱스를 갖출 값어치가 있고, 자주 바뀌는 자료나 여러 단계를 거치는 질문이라면 질의당 비용이 더 들더라도 반복 검색이 대체로 더 단순한 시스템입니다. 참고로, 단일 에이전트의 반복 검색이 검색 인덱스보다 성능이 낫다고 보고된 수치가 있지만 이 수치는 특정 버전에 묶여 있습니다. 이 모듈에 적힌 숫자에 기대기보다, 빌드 시점에 참고 문서에서 확인하는 것이 좋습니다.

앞의 네 전략 가운데 압축과 서브에이전트 넘기기는 실제로 쓸 때 결정이 하나 더 붙습니다. 무엇을 남길지가 결과를 크게 바꾸기 때문입니다.

Claude Code에서 /compact를 쓰면 무엇을 요약에 담을지 도구가 정합니다. API에서 문서로 안내되는 기본 방식은 서버 측 압축(server-side compaction, 베타)으로, 요청에 설정해 두면 플랫폼이 대신 대화를 요약합니다. 반면 API 세션에서 압축을 직접 구현하면 요약기(summarizer) 프롬프트를 스스로 쓰게 되는데, 이 프롬프트가 다음 턴들에서 에이전트가 무엇을 알고 있을지를 정합니다.

SUMMARIZER — 요약기에 뭐라고 쓰는지가 남는 것을 정한다

서브에이전트 넘기기 — 긴 호흡의 과제 다루기. 과제가 컨텍스트 창 하나에 담기엔 너무 클 때, 창을 키우는 건 해법이 아닙니다. 해법은 과제를 쪼개서 각 서브에이전트에 관련된 맥락만 넘기는 것입니다. 서브에이전트는 범위가 정해진 과제와, 필요한 최소한의 맥락(직접 관련된 앞 단계 결과), 과제를 끝내는 데 필요한 도구, 그리고 분명한 종료 조건을 받습니다. 부모 에이전트가 그 결과를 모읍니다. 이 방식은 턴당 비용을 낮게 유지하고, 긴 호흡의 과제를 다룰 수 있게 만듭니다.

압축이나 잘라내기처럼 서브에이전트 넘기기도 구현 부담을 더합니다. 그러니 컨텍스트 비용이 실제로 문제가 되는 곳에만 적용하는 것이 좋습니다 — 단순한 한 번짜리 프롬프트나 짧은 작업 흐름에는 필요하지 않습니다.

지금까지의 전략은 컨텍스트 예산이 압박받고 있다는 걸 이미 알고, 그걸 관리할 도구를 고르는 상황을 가정합니다. 그런데 정작 어려운 부분은, 세션이 깨지기 전까지는 그 압박이 있다는 걸 모르는 경우가 많다는 점입니다. 개발에서 모든 테스트를 통과한 작업이 프로덕션에서 실패하는 이유는 하나입니다 — 도구 출력이 더 커지고 세션이 더 길어져서, 스무 턴을 깔끔히 담던 컨텍스트 창이 이제 여덟 턴에서 차 버리는 겁니다.

도구 출력도 프롬프트나 파일 읽기와 똑같이 컨텍스트를 씁니다. 컨텍스트 창은 한 턴에 Claude가 봐야 할 모든 것 — 시스템 프롬프트, 대화 기록, 그때까지 쌓인 모든 도구 호출과 결과 — 을 담는 고정된 예산입니다. 도구 출력이 짧으면 턴마다 이 합계에 조금씩 더해져 예산이 오래 갑니다. 도구 출력이 커지면 같은 합계에 더 많이 더해져 예산이 더 빨리 줄어듭니다. 창 자체가 바뀐 게 아니라, 턴마다 창을 얼마나 쓰는지가 바뀐 겁니다.

POSTMORTEM — 프로덕션 도구 출력으로 예산을 재 본 적이 없던 사례

한 팀이 판매 영수증을 처리하는 에이전트를 만들면서, 컨텍스트 예산을 4만 토큰으로 잡았습니다. 이건 모델의 한계가 아니라, 에이전트가 쓰는 컨텍스트에 비용을 통제하려고 팀이 스스로 정한 상한입니다. 모델 자체는 훨씬 여유가 있었습니다. 현재 Claude API 모델들은 적어도 20만 토큰의 컨텍스트 창을 갖고 있고, 가장 최신 플래그십 모델은 Fable을 포함해 기본으로 100만 토큰을 제공합니다. 그러니 4만이라는 숫자는 모델이 강제한 한계가 아니라, 팀이 일부러 정한 예산이었습니다.

개발에서는 영수증 스무 장짜리 테스트 묶음을 썼고, 각 도구 결과가 대략 800토큰이었습니다. 스무 턴 세션 전체가 약 1만 8천 토큰을 썼으니, 팀의 4만 토큰 예산 안에 넉넉히 들어왔습니다.

프로덕션에서는 영수증에 거래 기록이나 주고받은 문서 같은 첨부 자료가 딸려 왔습니다. 도구 출력 평균이 호출당 약 3,200토큰으로 커졌습니다. 도구 출력만 여덟 턴이면 약 2만 5,600토큰이고, 여기에 시스템 프롬프트와 사용자·어시스턴트 메시지가 얹히자 합계가 팀의 4만 예산 상한에 닿았습니다. 에이전트는 분석을 끝내기도 전인 여덟 번째 턴에서 그 상한에 부딪혔습니다. 겉보기 증상은 도구 선택이 나빠진 것처럼 보였습니다 — 엉뚱한 도구를 고르고 불완전한 분석을 내놓기 시작했으니까요. 그런데 진짜 원인은 달랐습니다. 시스템 프롬프트와 초반 지시가, 쓰고 나서도 잘라내지 않고 쌓인 도구 출력에 밀려나 있었고, 에이전트는 처음에 받았던 안내가 더는 남아 있지 않은 컨텍스트 창 위에서 판단하고 있었습니다.

DEV vs PRODUCTION — 같은 예산, 달라진 것은 도구 출력 크기

아래 세션 기록은 도구 선택이 점점 나빠지는 멀티턴 에이전트 실행입니다. 어느 턴에서 실패가 시작됐는지 찾고, 그 원인(메커니즘)을 짚은 다음, 세 보기 중 한 줄짜리 해법을 골라 보세요.

SESSION TRACE — 도구 호출과 결과 크기 기록

네 번째 턴이 마지막으로 올바른 선택입니다. 이 시점에 이미 큰 도구 결과 네 개(합쳐서 9,600토큰)가 컨텍스트 창에 자리 잡아, 다음에 어떤 도구를 써야 하는지 알려 주는 지시를 밀어내고 있습니다.

정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.

이어서 본문을 되짚는 문항 두 개입니다. 같은 방식으로, 답을 떠올린 뒤 골라 보세요.