최종학 | Kyle Choi NotesFaith · AI · Learning
AI트렌드

Claude Code 한도가 빨리 닳을 때 바꿀 설정 두 줄

Kyle Choi · 2026년 9월 22일

오후 창빛이 드는 낡은 나무 책상 위, 왼쪽에는 놋쇠 워머 속 작은 촛불이 찻주전자를 계속 데우고 오른쪽에는 방금 스너퍼로 끈 초 한 자루에서 연기 한 줄이 오르는 정물 사진 — 필요한 곳은 오래 데워 두고 안 쓰는 불은 끄는 두 설정을 나타냄

이번 주 Reddit r/ClaudeAI 상위 글에는 사용 한도가 예전보다 빨리 닳는다는 불만이 많았습니다. 그 가운데 원인을 직접 재 보고 설정 한 줄을 제안한 글이 두 편 있었습니다. 하나는 서브에이전트의 캐시 수명이고, 다른 하나는 입력창에 뜨는 회색 제안 문구입니다. 두 설정 모두 공식 설정 문서에 키 이름과 값이 그대로 나와 있습니다.

다만 두 글이 내놓은 숫자는 작성자가 자기 사용 기록으로 잰 값입니다. 공식 문서는 제안 문구를 끄면 한도가 얼마나 남는지 말하지 않고, 1시간 캐시는 오히려 쓰기 단가가 더 높다고 적습니다. 설정은 공식으로 확인되지만, 효과는 작업 모양에 따라 달라집니다.

이 글은 Claude Code를 쓰는 분이 오늘 바로 확인해 볼 설정 두 가지를 증상, 설정 방법, 효과가 있는 조건, 작성자 계측 순서로 정리했습니다. 공식 문서로 확인한 내용과 사용자 계측은 나눠 적었습니다.

1. 서브에이전트의 캐시는 구독에서도 5분입니다

증상: 서브에이전트에게 테스트나 빌드처럼 오래 걸리는 일을 맡겼더니, 한 일에 비해 한도가 크게 줄어듭니다.

Claude Code는 매 요청마다 지금까지의 대화 전체를 다시 보냅니다. 프롬프트 캐싱은 앞부분이 같으면 이미 처리한 내용을 싸게 다시 읽게 해 주는 장치이고, 일정 시간 요청이 없으면 캐시가 사라집니다. 그 시간이 캐시 수명(TTL)입니다.1

공식 문서는 요청을 두 묶음으로 나눕니다. 직접 주고받는 메인 대화와, 서브에이전트·워크플로·대화 압축·세션 제목 같은 그 밖의 요청입니다. Claude 구독 요금제 한도 안에서 쓰면 메인 대화는 1시간 캐시를 받지만, 그 밖의 요청은 서버가 정하는 일부 보조 요청을 빼면 5분입니다. 문서에는 서브에이전트가 “구독에서도 5분”을 받는다는 문장이 따로 적혀 있습니다.1

그래서 서브에이전트가 5분 넘게 걸리는 명령 안에 머물러 있으면, 명령이 끝났을 때 캐시가 이미 사라져 있습니다. 그다음 요청은 서브에이전트가 지금까지 읽고 한 일 전체를 캐시에 다시 씁니다. 9월 18일 이 문제를 정리한 r/ClaudeAI 작성자는 서브에이전트 하나가 약 59만 토큰의 맥락을 하루 여덟 번 다시 썼다고 기록했습니다(작성자 계측).2

2. 1시간으로 바꾸는 한 줄 — 5분 넘게 기다리는 긴 작업일 때만

설정 방법: 사용자 설정 파일 ~/.claude/settings.json에 아래 한 줄을 넣습니다. 테스트·빌드처럼 5분 넘게 걸리는 명령이 서브에이전트 작업에 끼는 긴 작업일 때 쓰는 설정입니다. 몇 분 안에 끝나는 짧은 작업이면 이득이 없고 오히려 비용이 늘 수 있습니다(3절).

{
  "subagentPromptCacheTtl": "1h"
}
  • 값은 "5m"과 "1h" 두 가지뿐이고, 그 밖의 값은 무시됩니다. 기본값은 비어 있어서 요청마다 기본 수명을 받습니다.3
  • 이 키는 서브에이전트·워크플로와, 압축·세션 제목 같은 Claude Code의 백그라운드 요청에 모두 적용됩니다.3
  • 한 세션에만 적용하려면 환경변수 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h를 씁니다. 우선순위는 FORCE_PROMPT_CACHING_5M(두 묶음 모두 5분 강제) → 이 환경변수 → 이 설정 순입니다.3
  • 메인 대화 쪽 키는 따로 있습니다(promptCacheTtl). 두 키를 모두 정해야 Claude Code의 모든 요청에 수명이 정해집니다.3
  • 필요한 버전은 공식 문서 기준 v2.1.242 이상입니다. 변경 기록에는 v2.1.243 항목에 이 설정이 추가됐다고 적혀 있습니다. 두 버전 모두 2026년 8월 24일(UTC)에 배포됐습니다.4 터미널에서 claude --version으로 먼저 확인하세요.

메인 대화의 캐시 적중률은 /usage의 「Prompt cache (main)」 줄에서 볼 수 있습니다(v2.1.251 이상).1 이 줄은 메인 대화 기준입니다. 서브에이전트는 작성자가 소개한 방법대로 ~/.claude/projects/ 아래 서브에이전트 기록 파일에서 cache_creation_input_tokens 값이 긴 명령 뒤마다 크게 반복되는지를 보면 확인할 수 있습니다(작성자 안내).2

3. 1시간이 늘 이득은 아닙니다

공식 문서는 1시간 캐시가 쓰기 단가를 더 높게 받는다고 분명히 적습니다. 그리고 한 문장을 덧붙입니다. “5분 넘게 쉬는 일이 없는 짧은 작업에서는 더 비싸다. 높은 쓰기 단가는 붙는데 긴 수명은 쓰이지 않기 때문이다.”1

얼마나 비싼지는 API 요금 기준으로만 공식 수치가 있습니다. Claude API 가격표에서 5분 캐시 쓰기는 기본 입력 단가의 1.25배, 1시간 캐시 쓰기는 2배, 캐시 읽기는 보통 0.1배(Fable 5.1·Mythos 5.1은 0.025배)입니다. API 요금 기준으로 1시간 캐시 쓰기는 5분 캐시 쓰기의 1.6배입니다.5 구독 요금제에서 이것이 한도를 얼마나 줄이는지는 공식 문서에 수치가 없습니다.

한 가지 더 있습니다. 구독 요금제 한도를 넘어 추가 사용량(usage credits)으로 쓰기 시작하면 Claude Code는 메인 대화도 5분 캐시로 내립니다. 그때도 1시간을 유지하려면 promptCacheTtl을 "1h"로 직접 정해야 합니다.1

작성자의 계측은 이렇습니다. 설정을 바꾼 뒤 같은 종류의 일에서 캐시 쓰기가 약 75% 줄었고, 서브에이전트 네 개로 5시간 한도가 2%에서 100%까지 찼던 작업이 설정 뒤에는 0%에서 22%까지만 찼다고 적었습니다. 모두 작성자 한 사람이 자기 기록으로 잰 값입니다. 같은 글의 댓글에는 자기 작업은 읽기가 많아 오히려 비용이 약 7.6% 늘 것으로 추정됐다는 반대 사례도 있습니다.2 읽기가 많고 캐시가 끊기지 않는 작업이면 1시간이 이득이 아닐 수 있습니다.

4. 입력창의 회색 글씨도 따로 도는 요청입니다

증상: Claude Code 입력창 끝에 “commit and push” 같은 회색 예측 문구가 뜹니다. 공식 설정 문서는 이것을 프롬프트 제안(prompt suggestions)이라 부르고, 기본값은 켜짐입니다.3

이 문구는 입력창이 혼자 만들어 내는 자동완성이 아닙니다. 공식 변경 기록 v2.1.257 항목은 프롬프트 제안을 대화 압축, /recap과 함께 Claude Code의 백그라운드 요청으로 적고 있습니다.4 사용자가 보낸 메시지와는 따로 모델에 가는 요청이라는 뜻입니다.

9월 21일 r/ClaudeAI에 이 제안을 끄자는 글을 올린 작성자는, 제안이 대화 맥락 전체를 캐시에서 읽어 들여 만들어진다고 설명했습니다. 작성자가 자기 사용 기록으로 잰 바로는 제안 하나에 드는 비용이 일반 프롬프트 비용의 중앙값 91%였고, 자기 주간 Fable 한도의 최대 10%까지 차지할 수 있었다고 적었습니다(작성자 계측).6 다만 공식 문서에는 제안이 한도를 얼마나 쓰는지에 대한 수치가 없습니다. 제안을 끈다고 한도가 몇 % 남는다고 말할 공식 근거는 없습니다.

5. 회색 제안을 끄는 방법 두 가지

설정 방법:

  • Claude Code 안에서 /config를 열고 Prompt suggestions를 끕니다.3
  • 또는 ~/.claude/settings.json에 아래 한 줄을 넣습니다.3 작성자는 바꾼 뒤 재시작이 필요하다고 적었습니다(작성자 안내).6
{
  "promptSuggestionEnabled": false
}

두 설정을 함께 쓰려면 새 파일을 따로 만들지 말고, 기존 settings.json의 중괄호 하나 안에 쉼표로 이어 넣습니다. 이미 다른 설정이 있으면 그 사이에 줄만 추가합니다.

{
  "subagentPromptCacheTtl": "1h",
  "promptSuggestionEnabled": false
}

주의할 점이 하나 있습니다. 환경변수 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION이 설정돼 있으면 그 세션에서는 이 환경변수가 설정 키보다 우선합니다.3 설정을 바꿨는데도 제안이 계속 뜨면 이 환경변수부터 확인하세요.

공식 문서가 적은 조건도 있습니다. 프롬프트 제안은 claude.ai 또는 Console 계정에 텔레메트리가 켜져 있어야 동작합니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry를 쓰거나 텔레메트리를 끈 환경에서는 이 키가 아무 효과가 없고, 환경변수를 1로 둘 때만 제안이 켜집니다.3 이런 환경에서는 기본적으로 제안이 꺼져 있습니다. 다만 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1로 켜 두었다면 그 환경변수 설정을 확인하세요. 이 경우 settings.json의 키만 바꿔서는 꺼지지 않습니다.

제안을 끄면 잃는 것은 편의 하나입니다. 다음에 칠 말을 예측해 주던 문구가 사라지고, 매번 직접 입력하게 됩니다.

6. 91%와 10%는 한 사람이 잰 숫자입니다

두 글의 숫자는 커뮤니티에서 크게 퍼졌지만, 모두 작성자 한 사람의 계측입니다. 읽을 때 붙여야 할 단서가 작성자 글 안에 이미 있습니다.

프롬프트 제안 글의 91%는 일반 대화 턴만 모은 중앙값입니다. 작성자는 모델이 도구를 부르고 파일을 쓰는 작업 단계는 이 계산에 넣지 않았고, 제안을 끈다고 쓸 수 있는 양이 두 배가 되지는 않는다고 직접 적었습니다. 댓글에서는 맥락이 클수록 차이가 커지고, 검색·코드 작성처럼 단계가 많은 작업에서는 절감 비율이 크게 줄어든다고 설명했습니다. 같은 글에 “내 경우는 3~4% 정도”라는 댓글도 달렸습니다.6

서브에이전트 글의 75%는 작성자의 작업 모양에서 나온 숫자입니다. 작성자는 서브에이전트가 한 번에 30초에서 40분까지 걸리는 테스트를 계속 돌리는 환경이었고, 서브에이전트가 몇 초 만에 파일만 고치고 돌아오는 작업이면 이 현상을 훨씬 덜 보게 된다고 적었습니다. 구독 요금제의 한도 계산 방식은 공식적으로 공개되지 않았고, 작성자가 인용한 단가 비교도 커뮤니티 계측이라고 밝혀 두었습니다.2

그러니 두 숫자는 “나도 이만큼 된다”가 아니라 **“내 작업이 이 모양이면 한번 재 볼 만하다”**로 읽는 것이 맞습니다.

7. 모델과 effort는 세션 첫머리에 정하세요

이번 주 신기능은 아니지만 같은 흐름에서 다시 화제가 된 원칙이 하나 있습니다. 공식 캐싱 문서에 따르면 대부분의 모델은 effort 수준마다 캐시를 따로 가지고 있어서, 세션 중간에 effort를 바꾸면 다음 요청이 대화 전체를 캐시 없이 다시 읽습니다. 모델을 바꿀 때도 마찬가지입니다. 예외로 Fable 5.1을 API 키나 Claude 구독으로 쓰면 effort를 바꿔도 캐시가 유지됩니다(v2.1.260 이상).1 그래서 문서는 모델과 effort를 세션 첫머리에 고르고 대화 압축(/compact)은 작업과 작업 사이에 하라고 권합니다.1 effort는 생각하는 시간만이 아니라 파일을 몇 개 읽고 몇 단계를 진행할지까지 정한다는 설명은 Anthropic이 7월 7일 공식 블로그에 쓴 글에 있습니다.7

8. 오늘 해 볼 것 세 가지

  • 터미널에서 claude --version을 쳐서 v2.1.243 이상인지 확인합니다.
  • 서브에이전트에게 5분 넘게 걸리는 테스트·빌드를 맡기는 편이라면 "subagentPromptCacheTtl": "1h"를 넣고, 며칠 동안 한도가 줄어드는 속도를 전과 비교합니다. 짧은 작업 위주라면 넣지 않습니다.
  • 회색 제안 문구를 거의 받아 쓰지 않는다면 /config에서 Prompt suggestions를 끄고, 한 주 동안 체감을 비교합니다.

두 설정 모두 되돌리기 쉽습니다. 설정 파일에서 그 줄을 지우거나 /config에서 다시 켜면 됩니다. 효과는 사람마다 작업마다 다르니, 남의 숫자보다 내 한도 줄어드는 속도를 기준으로 판단하시기 바랍니다.

이 글은 2026년 9월 15일부터 22일까지 공개된 커뮤니티 게시물과, 9월 22일에 조회한 Claude Code 공식 문서·변경 기록·Claude API 가격표를 바탕으로 정리했습니다. 커뮤니티의 숫자는 작성자 개인의 계측이고, 구독 요금제의 한도 계산 방식은 공식적으로 공개되지 않았습니다.

참고자료(검증 출처)

Footnotes

  1. Claude Code Docs · How Claude Code uses prompt caching · 2026-09-22 16:53:34 KST 조회(사본 수집 시각 실측 기록 기준) · 17:18 KST 재조회로 핵심 문자열 재확인 — 요청 묶음별 기본 수명 표, 서브에이전트 5분, 1시간 쓰기 단가·짧은 작업 손해 문장, 추가 사용량 전환 시 메인 5분, /usage 캐시 줄, effort·모델 변경과 캐시, Fable 5.1 예외 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7

  2. Reddit r/ClaudeAI · Sub-agents burning your Claude Code 5-hour window? Check their 5-minute prompt cache · 2026-09-18 04:55 KST 게시 · 작성자 계측(캐시 쓰기 약 75% 감소, 5시간 한도 2%→100% vs 0%→22%, 약 59만 토큰 8회 재기록)과 확인 방법 · 댓글의 반대 추정(+7.6%) 포함 · 1차 출처 아님 ↩ ↩2 ↩3 ↩4

  3. Claude Code Docs · All settings · 2026-09-22 16:53:34 KST 조회(사본 수집 시각 실측 기록 기준) · 17:18 KST 재조회로 핵심 문자열 재확인 — subagentPromptCacheTtl(값·기본값·적용 범위·우선순위·v2.1.242), promptSuggestionEnabled(기본 true·/config 토글·환경변수 우선·텔레메트리 조건) ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9

  4. Claude Code CHANGELOG · 2026-09-22 17:17:33 KST 조회 — v2.1.243 설정 추가 항목, v2.1.257 백그라운드 요청(압축·/recap·프롬프트 제안) 항목 · 배포 시각은 npm 배포 기록(2.1.242 = 2026-08-24T19:16:14Z, 2.1.243 = 2026-08-24T23:10:45Z) ↩ ↩2

  5. Claude API Docs · Prompt caching · Pricing · 2026-09-22 17:18 KST 조회(사본 저장 17:18:39) — 5분 쓰기 1.25배·1시간 쓰기 2배·읽기 0.1배(Fable 5.1·Mythos 5.1 읽기는 0.025배) · API(종량) 요금 기준이며 구독 한도 환산 수치 아님 ↩

  6. Reddit r/ClaudeAI · 프롬프트 제안 비용에 관한 사용자 계측 글 · 2026-09-21 18:50 KST 게시 · 작성자 계측(중앙값 91%·주간 Fable 한도 최대 10%, 일반 턴만 집계)과 댓글 설명·재시작 안내 · 댓글 반론(3~4%) 포함 · 1차 출처 아님 ↩ ↩2 ↩3

  7. Claude 블로그 · Claude Code effort level and model selection · 2026-07-07 게시(이번 주 글 아님) · 2026-09-22 조회 ↩