🔥 AWS 블로그의 4줄 셋업 밑에 숨은 풍경 — Claude Code × Bedrock 프롬프트 캐싱

#Claude Code#Amazon Bedrock#프롬프트 캐싱#AWS#MCP

1907자

21분

강의 목차

왜 Bedrock인가
4줄 셋업, 2026년 4월 버전
프롬프트 캐싱이 Bedrock에서 실제로 어떻게 생겼나
1H TTL — Bedrock에서도 드디어 GA
AWS 블로그가 흘려 말한 "Guidance"의 실체
TPM/RPM 계산, 실제로 해보면
MCP, 특히 AWS 공식 MCP 서버
같이 쓰면서 추천하는 `.claude/settings.json` 한 장
실제로 쓸 만한가
참고 자료

Claude Code와 Amazon Bedrock 프롬프트 캐싱 1h/5m TTL 레이어 다이어그램

어제 Claude Code 2.1.108의 ENABLE_PROMPT_CACHING_1H 플래그 글을 쓰면서 참고용으로만 걸어뒀던 AWS 블로그를 오늘 다시 읽어봤다. Supercharge your development with Claude Code and Amazon Bedrock prompt caching. 제목부터 마케팅 냄새가 꽤 나서 처음엔 스쳐 지나갔는데, 다시 보니 이 글이 제시한 "설치 4줄"과 "실제 엔터프라이즈 배포" 사이의 간극이 꽤 흥미롭다.

블로그의 핵심 셋업은 이렇게 끝난다.

bash

npm install -g @anthropic-ai/claude-code
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-20250514-v1:0'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'
claude

bash

npm install -g @anthropic-ai/claude-code
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-20250514-v1:0'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'
claude

네 줄. 이게 전부라고 믿고 팀에 도입했다가는 2주 뒤에 보안팀과 재무팀이 동시에 문을 두드리는 경험을 하게 될 가능성이 높다. 이 글은 2025년 6월에 나와서 2025년 9월에 한 번 업데이트됐는데, 2026년 4월 현재 기준으로 다시 읽으면 "맞는데 이제 이게 전부는 아니다"가 된다. 그 간극을 메우는 게 이 글의 목적이다.

왜 Bedrock인가

내 일상 Claude Code는 Anthropic API 키로 돈다. 개인 프로젝트니까 그게 편하다. 그런데 회사 규모로 Claude Code를 굴리는 조직은 거의 예외 없이 Bedrock으로 간다. 이유는 기술보다 조직 경제학 쪽이다.

첫째, 결제 채널. AWS Enterprise Discount Program(EDP)으로 이미 묶인 회사는 AI 토큰 비용을 EDP 커밋 안에서 소화할 수 있다. 별도 벤더 계약 없이 기존 AWS 청구서로 들어온다는 뜻이고, 이건 재무팀이 엄청 좋아한다.

둘째, 데이터 거버넌스. Anthropic 직접 API를 쓰려면 회사 법무팀이 한 번 더 검토한다. 반면 Bedrock은 이미 회사가 통과시킨 AWS BAA/DPA 체계 안에 있다. 법무를 한 번 더 통과시키지 않아도 된다는 건 도입 속도에 결정적이다.

셋째, 네트워킹. VPC 엔드포인트, PrivateLink, KMS — 기업 내부 컴플라이언스가 요구하는 것들이 Bedrock에서는 그냥 준비돼 있다. 외부 엔드포인트 하나 뚫어달라고 하면 보안팀이 6주를 쓴다. 기존 VPC 안에서 처리한다고 하면 당일 끝난다.

문제는 이 세 가지 장점이 전부 "조직 레벨"에서 발생한다는 점이다. 개발자 개인의 DX는 어떤가? 그게 이 AWS 블로그가 보여주려고 한 부분이다. 4줄 export로 끝난다는 이야기. 그리고 그 주장이 기술적으로는 맞다. 다만 그 뒤의 숫자들이 꽤 바뀌었다.

4줄 셋업, 2026년 4월 버전

AWS 블로그가 제시한 모델 ID는 us.anthropic.claude-sonnet-4-20250514-v1:0이다. 이 ID는 여전히 유효하지만, 2026년 2월에 Claude Sonnet 4.6이 Bedrock에 올라왔고 대부분의 조직이 이걸 쓰고 싶어 한다. 오늘 기준으로 셋업은 이렇게 된다.

bash

npm install -g @anthropic-ai/claude-code
 
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5'
 
claude

bash

npm install -g @anthropic-ai/claude-code
 
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5'
 
claude

AWS_REGION이 하나 추가됐다. Claude Code 공식 Bedrock 문서를 보면 이제 리전을 명시적으로 지정해야 하는 케이스가 대부분이다. 안 적으면 AWS SDK 기본 체인을 따라가는데, ~/.aws/config가 다른 리전을 가리키고 있으면 조용히 엉뚱한 엔드포인트로 붙는다.

더 재미있는 변화는 로그인 흐름이다. 그냥 claude를 처음 실행하면 이제 위저드가 뜬다. "Which provider?" 질문에서 Amazon Bedrock을 선택하면 사용 가능한 모델을 체크하고 설정 파일(~/.claude/settings.json)의 env 블록에 자동으로 박아준다. 즉 env var export를 안 해도 된다. CI나 도커 이미지 같은 비대화형 환경에서는 여전히 환경변수가 필요하지만, 개발자 PC에서는 위저드가 더 편하다.

그리고 AWS_BEARER_TOKEN_BEDROCK이라는 새 옵션이 있다. 장기 토큰 하나로 Bedrock에 붙는 방식. AWS CLI 설정 없이도 쓸 수 있다. 보안팀 입장에서는 이걸 좋아하지 않는다(정적 키 안티패턴). 개인 실험용이라면 편하지만, 팀 도입 시에는 다음 장의 IAM Identity Center / OIDC 쪽으로 넘어가야 한다.

프롬프트 캐싱이 Bedrock에서 실제로 어떻게 생겼나

AWS 블로그에서 가장 아쉬웠던 건 "cache checkpoint"라는 단어만 던져놓고 구조를 안 보여준 점이다. 공식 Bedrock 문서를 파 보면 실제 페이로드는 이렇게 생겼다.

json

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "{큰 코드베이스 컨텍스트, 수만 토큰}",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        },
        {
          "type": "text",
          "text": "이 함수를 리팩토링해줘"
        }
      ]
    }
  ]
}

json

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "{큰 코드베이스 컨텍스트, 수만 토큰}",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        },
        {
          "type": "text",
          "text": "이 함수를 리팩토링해줘"
        }
      ]
    }
  ]
}

핵심은 cache_control 객체다. type은 항상 "ephemeral"(다른 옵션 없음), ttl은 "5m" 또는 "1h". 이 마커가 붙은 content block 직전까지의 모든 토큰이 캐시 체크포인트로 저장된다. 다음 요청에서 정확히 같은 prefix가 들어오면 Bedrock이 저장된 모델 state를 로드해서 재계산을 건너뛴다.

몇 가지 규칙이 있다.

최소 토큰 수. Claude Sonnet 4.6/4.5 기준 1,024 토큰이 최소 체크포인트 크기다. 이 밑으로 떨어지면 cache_control을 붙여도 캐시가 만들어지지 않는다. 재미있는 건 모든 4.x 모델이 같은 하한선을 쓰지 않는다는 점이다. Claude Haiku 4.5와 Opus 4.5는 4,096 토큰이 최소치다. 작은 Haiku는 오히려 하한이 높고, 큰 Opus도 4,096. 체크포인트 하나 만들려면 4천 토큰 이상이 쌓여야 한다는 뜻이니, 짧은 대화에서는 이 두 모델에서 캐싱이 아예 안 걸린다.

prefix는 정적이어야 한다. 첫 번째 토큰부터 체크포인트 직전까지 단 하나의 토큰이라도 달라지면 cache miss. 이게 실무에서 가장 자주 발목 잡는 지점이다. 시스템 프롬프트에 타임스탬프를 넣는다든지, user ID 같은 가변값을 앞쪽에 꽂는다든지 하면 캐시가 매번 쓸려 나간다. Claude Code 내부 구현이 이걸 잘 처리하는지가 사실 캐시 히트율의 99%를 결정한다.

5m과 1h를 섞어 쓸 수 있다. 단, 긴 TTL이 먼저. 요청 안에 여러 개의 cache_control을 둘 수 있는데, 순서 규칙이 있다. "1h" 마커가 항상 "5m" 마커보다 앞에 나와야 한다. 역순으로 넣으면 Bedrock이 에러를 낸다. 이 규칙 때문에 Claude Code는 "CLAUDE.md 같은 장기 불변 컨텍스트 → 1h", "방금 읽은 파일 → 5m" 같은 식으로 레이어를 나눠서 붙이는 구조를 쓴다.

체크포인트 위치. messages, system, tools 필드 어디에나 붙일 수 있다. 큰 tool 정의를 쓰는 MCP-heavy 환경에서는 tools 필드 캐싱이 의외로 크게 작용한다.

이 구조를 알고 나면 Claude Code의 /cost 출력에서 Cache creation과 Cache read 라인이 왜 그렇게 분리돼 있는지 자연스럽게 읽힌다. 전자는 1.25× 또는 2× 구간, 후자는 0.1× 구간이다.

1H TTL — Bedrock에서도 드디어 GA

이 지점이 어제 쓴 글과 직결된다. 2026년 1월 26일, Amazon Bedrock이 1-hour TTL을 GA로 발표했다. 대상 모델은 Claude Sonnet 4.5, Haiku 4.5, Opus 4.5. 커머셜 리전과 GovCloud(US) 전역에서 쓸 수 있다.

이게 왜 큰 일인가. 그 전까지 Bedrock에서는 오직 5m TTL만 쓸 수 있었다. 반면 Anthropic 직접 API는 오래전부터 1h를 제공했다. 같은 Claude Code 바이너리를 쓰는데 프로바이더만 다르면 캐시 경제학이 완전히 다르게 돌아갔다는 얘기다. GitHub Issue #32671에 쌓인 민원이 이 불균형을 정확히 가리키고 있었다.

1월 GA 이후 Claude Code 2.1.108의 ENABLE_PROMPT_CACHING_1H가 추가된 건 이 변화를 클라이언트 쪽에서 받아내기 위한 마지막 퍼즐이었다. Bedrock API가 1h를 받을 준비가 됐고, Claude Code가 그 TTL로 요청을 만들어 보낼 플래그가 열렸다. 이 순서다.

숫자로 확인해 보자. 5m TTL은 write가 1.25×, 1h TTL은 2×. read는 둘 다 0.1×. 내가 한 시간짜리 리팩토링 세션을 돌리면서 CLAUDE.md + 프로젝트 구조 + 여러 파일의 맥락 총 50,000 input 토큰을 계속 쓴다고 치자. 세션 중 API 요청이 40번 나간다.

5m TTL로는 1시간 동안 약 12번 캐시가 만료된다. 매 만료마다 50,000 토큰을 1.25×로 재적재. 읽기 40회 중 28회가 히트. 러프하게 쓰면:

write: 50,000 × 12 × 1.25 = 750,000 토큰 등가
read: 50,000 × 28 × 0.1 = 140,000 토큰 등가
합계: 890,000 토큰 등가

1h TTL로는 만료가 1번. write 1회 2×, 읽기 40회 모두 히트:

write: 50,000 × 1 × 2 = 100,000 토큰 등가
read: 50,000 × 40 × 0.1 = 200,000 토큰 등가
합계: 300,000 토큰 등가

약 3배 차이가 난다. 물론 이건 러프 추정이고 실제 세션 패턴에 따라 달라지지만, 방향성은 명확하다. 한 시간 넘게 도는 세션이라면 1h TTL이 거의 항상 이긴다.

AWS 블로그가 흘려 말한 "Guidance"의 실체

AWS 블로그 말미에 "Consider implementing Guidance for Claude Code with Amazon Bedrock for large enterprise deployments"라는 문장이 던져져 있다. 클릭하기 전에는 그냥 마케팅 링크인 줄 알았는데, 실제 Solutions Library 페이지와 GitHub 레포를 열어보니 꽤 본격적인 레퍼런스 구현이다.

핵심 권장 아키텍처는 이렇다.

OIDC federation 우선. 회사가 이미 쓰는 Okta, Azure AD, Auth0, Cognito를 IdP로 두고, 거기서 발급된 토큰을 AWS IAM과 연결해 임시 credential로 변환한다. 개발자가 aws sso login 한 번 치면 끝나는 UX에 사용자별 감사 로그가 따라온다.
IAM Identity Center는 "쓸 수 있지만 한계 있음". 기존 SSO 인프라를 재활용할 수 있어 간편하지만, 사용자별 세부 모니터링이 제한된다. 즉 누가 얼마나 썼는지 추적이 거칠다. 감사·컴플라이언스가 중요한 조직에서는 OIDC 직결 쪽을 권한다.
배포에 2-3시간. QUICK_START.md에 단계가 다 적혀 있는데, IdP 연동이 제일 오래 걸린다.

여기서 중요한 건 "4줄 export"가 개인 개발자용이지 조직 배포용이 아니라는 걸 AWS가 이 Guidance로 인정하는 셈이라는 점이다. 조직은 IdP 통합 + 정책 적용 + 모니터링이 다 엮여야 하고, 그건 2-3시간 셋업이 최소 단위다.

TPM/RPM 계산, 실제로 해보면

AWS 블로그는 "200명이면 20k TPM per dev = 4M total TPM" 같은 숫자를 던진다. 합리적인 출발점이지만 두 가지 함정이 있다.

첫째, Bedrock의 output burndown rate. 공식 문서에 따르면 Claude 3.7 이상 모델은 output 1 토큰이 TPM 쿼터에서 5 토큰으로 차감된다. Claude Code는 코드 생성 워크로드라 output 비중이 꽤 높다. "개발자당 20k TPM"을 실제로 풀면 input 15k + output 1k 수준에서 이미 20k를 채워버린다(1k × 5 = 5k → 합계 20k).

프롬프트 캐싱이 들어가면 input 쪽 부담이 확 줄어서 output이 병목이 된다. 한 가지 더 중요한 디테일: Bedrock 공식 문서에 따르면 CacheReadInputTokens는 TPM/TPD burndown 계산에 포함되지 않는다. 즉 cache hit으로 읽히는 토큰은 쿼터 차감 자체가 없다. 캐싱이 활성화된 환경에서 실제 쿼터 병목은 "output + cache miss 구간의 input"이 된다. 이 뒤집힘이 AWS 블로그에는 한 줄도 안 나온다.

둘째, burst 패턴. 개발자 40명이 오전 10시에 다 같이 Claude Code를 열면 그 순간 TPM이 꺾인다. AWS re:Post에 LangGraph 병렬 워크플로우로 TPM 피크가 튄 사례가 올라와 있는데, Claude Code도 본질은 비슷하다. 평균이 아니라 피크 기준으로 쿼터를 잡아야 한다.

실무 계산은 보통 이렇게 한다. "평균 개발자 × 1.5배 버퍼 × output burndown 5× → 실제 요청 TPM". 이 계산이 AWS 블로그의 4M보다 꽤 크게 나온다. 쿼터 증설 요청은 리드 타임이 있어서 처음부터 넉넉하게 잡아두는 게 낫다.

MCP, 특히 AWS 공식 MCP 서버

AWS 블로그는 MCP를 언급만 하고 지나간다. 근데 Bedrock을 쓰는 조직이라면 awslabs/mcp 레포를 반드시 한번 봐야 한다. AWS가 공식으로 관리하는 MCP 서버 번들이다.

이 중 특히 유용한 것들:

awslabs.aws-api-mcp-server — AWS CLI 호출을 MCP 툴로 변환. 개발자가 "이 Lambda의 로그 보여줘"라고 말하면 Claude Code가 실제 CLI를 호출해서 가져온다.
awslabs.aws-documentation-mcp-server — 공식 AWS 문서 검색. 환각 줄이기에 꽤 도움된다.
awslabs.cdk-mcp-server — CDK/CloudFormation 베스트 프랙티스 주입.

설치는 claude mcp add로 한 줄이다.

bash

claude mcp add --scope project aws-api \
  uvx awslabs.aws-api-mcp-server@latest

bash

claude mcp add --scope project aws-api \
  uvx awslabs.aws-api-mcp-server@latest

중요한 건 이 MCP 서버들이 만들어내는 context도 prompt cache 안으로 들어간다는 점이다. tool 정의가 수천 토큰씩 되는데, 매 요청마다 재전송되면 돈이 아깝다. Claude Code의 캐시 레이어가 tools 필드까지 체크포인트 대상에 포함시켜야 이득이 실제로 쌓인다. 2.1.86에서 Bedrock/Vertex/Foundry의 dynamic content를 제거해 캐시 히트율을 개선한 변경이 정확히 이 지점을 손본 것이다.

같이 쓰면서 추천하는 `.claude/settings.json` 한 장

프로젝트 루트에 체크인해서 팀 전체가 같은 설정으로 시작하게 하는 게 실용적이다.

json

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL": "us.anthropic.claude-haiku-4-5",
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}

json

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL": "us.anthropic.claude-haiku-4-5",
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}

이 한 장으로 앞에서 이야기한 모든 환경변수가 한 곳에 모인다. AWS 자격증명은 여전히 aws sso login으로 개별 셋업해야 하지만, 최소한 "어떤 모델로, 어떤 TTL로 돌지"는 팀원 전원이 같은 그림을 보게 된다. Bedrock으로 옮길 때 가장 어려운 건 기술이 아니라 이런 일관성을 만드는 일이라는 걸 프로젝트 몇 번 돌려보면 안다.

실제로 쓸 만한가

정직하게 말하면 내 현재 개인 환경에는 Bedrock이 오버엔지니어링이다. Anthropic API 키 하나로 끝나는데 VPC 엔드포인트 그릴 이유가 없다. 그런데 팀에 10명 이상이 Claude Code를 쓰는 순간, 비용 가시성·감사 로그·네트워크 통제 요구가 동시에 올라오고, 그 시점에서 Bedrock이 "더 무거워 보이지만 실은 더 단순한" 선택이 된다.

AWS 블로그가 못 보여주는 트레이드오프는 세 가지다. 모델 이름이 빠르게 낡는다(2025년 6월 글이 이미 1년 안에 구버전이 됐다), TPM 계산이 output burndown 때문에 단순 산수로 안 된다, 그리고 진짜 조직 배포는 4줄이 아니라 OIDC 통합 2-3시간이다.

그래도 1H TTL이 GA로 들어오면서 Bedrock 쪽의 마지막 큰 불편이 풀렸다는 건 확실하다. 어제 글에서 ENABLE_PROMPT_CACHING_1H를 .zshrc에 박아둔다고 했는데, Bedrock 팀 프로젝트라면 그 한 줄을 settings.json에 박아야 한다. 개인 튜닝이 팀 기본값으로 승격되는 순간이다. 그 승격을 고민하고 있다면 AWS 블로그의 4줄을 그대로 복붙하지 말고, 이 글에서 정리한 settings.json 한 장과 Guidance 레포를 같이 펴두고 시작하는 걸 추천한다.