"프롬프트 캐시" 태그로 연결된 2개 게시물개의 게시물이 있습니다.

Claude Code 응답에서 제일 자주 걸러내고 싶은 게 뭘까요. 저는 "먼저 파일을 확인해 보겠습니다" 같은 예고 문장이었어요. v2.1.237에 그걸 기본으로 지워 주는 출력 스타일이 들어왔습니다.

이름은 Concise입니다. 변경 로그 한 줄은 이렇습니다.

Added built-in "Concise" output style: Claude leads with results, skips preamble/narration, works thoroughly

내장 스타일이 다섯 개가 됐다​

출력 스타일은 원래 Default에 Explanatory와 Learning 둘이 붙은 구성이었습니다. 지금은 Proactive와 Concise가 더해져 Default 외에 네 개입니다.

Concise를 두고 오해하기 쉬운 부분이 하나 있습니다. 짧게 답하라는 게 작업을 덜 하라는 뜻은 아닙니다. 공식 문서는 "doing the engineering work as thoroughly as in the Default style"이라고 적어 뒀습니다. 설명을 요청하면 그때는 길게 답합니다. 그리고 짧게 만들지 않는 예외가 정해져 있습니다. 오류 보고, 보안 경고, 파괴적 작업의 확인 문구는 내용을 온전히 유지합니다. 이 예외 목록이 있다는 게 스타일 설계에서 제일 중요한 부분이라고 봅니다. 짧게 쓰다가 위험 신호를 줄여 버리면 절약이 아니라 사고니까요.

Proactive는 성격이 좀 다릅니다. 톤이 아니라 행동 방침을 바꿉니다. auto mode보다 강한 자율 실행 지침인데, 권한 모드는 그대로 둡니다. 무엇을 물어보지 않고 실행할지는 여전히 권한 모드가 결정하고, Proactive는 "판단을 사용자에게 넘기지 말고 스스로 하라"는 쪽만 건드립니다.

스타일을 바꾸는 방법이 달라졌다​

여기서 한 번 헤맬 수 있습니다. /output-style 명령이 없어졌습니다. v2.1.73에서 deprecated 되고 v2.1.91에서 제거됐습니다. 지금은 두 가지 방법뿐입니다.

터미널에서는 /config를 실행해 Output style 항목에서 고릅니다. 선택 결과는 프로젝트 로컬 설정 파일에 저장됩니다.

.claude/settings.local.json

설정 파일을 직접 고쳐도 됩니다.

{
  "outputStyle": "Concise"
}

데스크톱 앱에서는 /config가 메뉴 대신 Settings 화면을 엽니다. 그래서 데스크톱에서는 위 필드를 직접 넣는 쪽이 확실합니다.

바꾼 뒤 바로 안 바뀐다고 당황하지 않아도 됩니다. 출력 스타일은 시스템 프롬프트의 일부이고, 시스템 프롬프트는 세션이 시작할 때 한 번 읽습니다. /clear를 실행하거나 새 세션을 열어야 적용됩니다.

CLAUDE.md와 어디서 갈라지나​

이게 문서에서 가장 값이 나가는 대목입니다. 둘 다 "Claude가 이렇게 행동하게 만드는 장치"인데 붙는 위치가 다릅니다.

출력 스타일은 시스템 프롬프트 끝에 붙습니다. CLAUDE.md는 시스템 프롬프트 뒤에 오는 user message로 들어갑니다. 이 차이가 실무에서 세 갈래 결과를 만듭니다.

첫째, 커스텀 출력 스타일은 기본 소프트웨어 엔지니어링 지침을 빼 버립니다. 변경 범위를 어떻게 잡고, 주석을 어떻게 쓰고, 작업을 어떻게 검증하라는 내장 지침 전체가 사라집니다. 그걸 유지하려면 frontmatter에 keep-coding-instructions: true를 넣어야 합니다. 기본값이 false라는 걸 모르고 커스텀 스타일을 만들면, 톤만 바꾸려던 게 코딩 행동까지 바꿔 버립니다.

둘째, 서브에이전트에는 적용되지 않습니다. 서브에이전트는 자기 시스템 프롬프트로 돕니다. 예외가 fork인데, fork는 부모의 시스템 프롬프트를 통째로 물려받기 때문입니다. Concise로 세션을 돌리면서 서브에이전트에게 요약을 맡겼는데 서브에이전트 응답이 장황한 이유가 여기 있습니다.

셋째, 프롬프트 캐시입니다. 시스템 프롬프트가 바뀌면 캐시 접두사가 깨집니다. 토큰 절약 가이드 글에서 모델과 effort를 세션 시작 시점에 고정하라는 권고를 다뤘는데, 출력 스타일도 같은 부류의 설정입니다. 세션 도중에 바꿀 값이 아닙니다.

커스텀 스타일은 파일 하나다​

내장 다섯 개로 부족하면 마크다운 파일을 만듭니다. 위치는 세 곳이고, 파일명이 스타일 이름이 됩니다. frontmatter에 name을 적으면 그쪽이 이깁니다.

~/.claude/output-styles/          # 사용자 전역
.claude/output-styles/            # 프로젝트

공식 문서 예시가 성격을 잘 보여 줍니다.

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram
showing the structure, then explain in prose.

프로젝트 스타일은 작업 디렉터리부터 저장소 루트까지의 모든 .claude/output-styles/에서 읽습니다. 같은 이름이 여러 층에 있으면 작업 디렉터리에 가까운 쪽이 이깁니다. 플러그인도 output-styles/ 디렉터리로 스타일을 배포할 수 있는데, 플러그인 전용 필드인 force-for-plugin: true를 켜면 사용자의 outputStyle 설정을 덮어쓰고 강제 적용됩니다. 플러그인을 깔았는데 응답 톤이 갑자기 변했다면 이 필드를 의심해 볼 만합니다.

frontmatter 필드는 네 개입니다.

토큰은 어느 쪽으로 움직이나​

방향이 둘로 갈립니다. 입력 토큰은 스타일 지침이 시스템 프롬프트에 붙는 만큼 늘어납니다. 다만 첫 요청 이후에는 프롬프트 캐시가 이 비용을 상당히 덮습니다. 출력 토큰은 스타일이 결정합니다. Explanatory와 Learning은 설계상 응답이 길어지고, Concise는 반대로 갑니다.

그러니 Concise의 절약 효과는 출력 쪽입니다. 응답 길이가 짧아지는 만큼 출력 토큰이 줄고, 그 짧은 응답이 다음 턴의 입력으로 다시 들어가니 대화가 길어질수록 차이가 누적됩니다. 반대로 Learning 스타일로 긴 세션을 돌리면 그 반대 방향으로 누적됩니다. 제가 지금 이 글을 쓰는 세션이 Learning 스타일인데, 확실히 응답 길이가 기본보다 깁니다.

같은 주에 들어온 나머지​

Concise만 있던 주가 아닙니다. v2.1.234에 실무에서 체감될 항목이 둘 붙었습니다.

사용량 한도 자동 재개입니다. claude.ai 사용량 한도가 초기화되면 세션을 자동으로 이어서 진행합니다. /config에서 켜고 끕니다. 장시간 작업을 돌려 두고 자리를 비우는 사용 방식이라면 이 항목 하나로 흐름이 달라집니다. Routines처럼 사람이 안 보는 동안 도는 작업과 결이 같습니다.

GitLab merge request 배지도 들어왔습니다. GitLab remote가 걸린 저장소에서 glab으로 인증돼 있으면 MR !N 형태로 draft, pending, green 상태를 상태줄에 표시합니다. GitHub PR 배지만 있던 자리에 GitLab이 붙은 셈입니다.

이후 버전도 흐름이 이어집니다. v2.1.238에는 커스텀, 프로젝트, 플러그인 출력 스타일이 세션 도중에 기본 목소리로 되돌아가던 버그 수정이 들어갔습니다. 출력 스타일 자체를 손보는 작업이 한 주 내내 계속됐다는 뜻입니다. v2.1.239에서는 사용량 한도 안내가 세션, 주간, 월간 중 무엇이 초기화되는지 구분해 알려 주게 바뀌었습니다.

어떤 스타일로 쓸까​

정답은 작업 성격에 달렸습니다. 제 기준으로는 이렇게 갈립니다.

익숙한 코드베이스에서 반복 작업을 돌릴 때는 Concise가 맞습니다. 무엇을 할지 이미 알고 있으니 예고가 필요 없습니다. 처음 보는 코드베이스를 파악하는 중이라면 Explanatory가 낫습니다. "왜 이 파일을 골랐나"가 정보이기 때문입니다. 새 기술을 배우려고 붙었다면 Learning이 값을 합니다. TODO(human) 표시가 남으면 직접 손을 대야 하고, 그 지점이 대개 판단이 필요한 자리입니다.

Proactive는 조심스럽습니다. 권한 모드를 안 건드린다지만 "묻지 말고 판단하라"는 지침 자체가 리스크입니다. 되돌리기 쉬운 작업에만 쓰는 쪽이 안전합니다.

그리고 이 다섯 개는 서로 배타적입니다. 한 세션에 하나만 걸립니다. 작업 성격이 바뀌면 /clear하고 다시 고르는 게 정석입니다.

참고​

• Claude Code CHANGELOG
• Output styles 공식 문서
• Permission modes 공식 문서

같은 작업을 시켰는데 어떤 날은 사용량이 순식간에 닳고 어떤 날은 널널했던 경험, 있으실 거예요. 저도 한도에 일찍 닿은 날마다 모델 탓을 했는데, Anthropic이 8월 14일에 낸 공식 가이드를 읽고 나니 범인은 따로 있었습니다. 프롬프트 캐시를 깨는 습관입니다.

요금의 실체는 캐시 히트율​

Claude Code는 매 턴마다 지금까지의 대화 전체를 모델에 보냅니다. 대화가 길어질수록 매 요청의 입력이 커지는 구조인데, 이게 감당되는 이유가 프롬프트 캐시입니다. 직전 요청과 같은 prefix는 캐시에서 읽고, 캐시 읽기 요금은 정상 입력 가격의 0.1배입니다. 반대로 캐시에 새로 쓰는 비용은 최대 2배입니다.

즉 20배짜리 요금 격차가 대화 내내 작동합니다. 캐시가 살아 있으면 긴 대화도 턴당 비용이 낮게 유지되고, 캐시가 깨지면 대화 전체를 정상 가격으로 다시 보내며 다시 캐시 쓰기 할증까지 뭅니다. Claude Code의 캐시 유효 시간은 1시간입니다(API 직접 호출 기본은 5분).

캐시를 깨는 행동들​

가이드가 지목하는 캐시 무효화 요인은 네 가지입니다.

여기서 실무 결론이 나옵니다. 모델과 effort는 세션 시작 시점이나 /clear 직후에 정하고, 대화 중간에는 건드리지 않는 것입니다. 긴 대화 한가운데서 /model을 바꾸면 그 시점까지의 대화 전체가 새 모델 기준으로 재처리되고 재캐싱됩니다. "이 질문만 가볍게 다른 모델로" 하려던 절약이 실제로는 가장 비싼 행동이 되는 역설입니다.

한 시간 자리를 비울 때도 마찬가지입니다. 돌아와서 이어 쓰면 만료된 캐시를 처음부터 다시 씁니다. 가이드는 장시간 중단 전에 /compact를 실행하라고 권합니다. 캐시가 아직 유효할 때 요약해 두는 쪽이 싸기 때문입니다.

문맥 관리 명령 셋의 역할 분담​

/clear, /compact, /rewind가 비슷해 보여도 캐시 관점에서 역할이 다릅니다.

• /clear: 새 작업을 시작할 때. 이전 작업의 문맥은 다음 작업에서 전부 "돈 내고 실어 나르는 짐"이 되므로, 작업 사이에는 비우고 시작합니다
• /compact: 문맥은 이어가야 하는데 대화가 너무 길어졌거나, 장시간 자리를 비우기 직전에
• /rewind: 마지막 몇 턴만 무르고 싶을 때. 캐시를 무효화하지 않는 것이 장점입니다

저처럼 한 세션에서 이 일 저 일 이어 하던 사람에게는 /clear가 제일 아픈 항목입니다. "혹시 아까 맥락이 필요할지 몰라서" 남겨 둔 문맥이 매 턴 입력 토큰으로 청구되고 있었으니까요.

입력을 줄이는 잔기술​

캐시 다음으로 효과가 큰 항목은 문맥에 들어오는 양 자체를 줄이는 것입니다.

파일은 @멘션으로 첨부합니다. src/main.py 읽어 봐라고 쓰면 모델이 Read 도구를 호출하는 왕복이 생기는데, @src/main.py로 멘션하면 파일이 첫 요청에 바로 첨부됩니다. 도구 호출 한 번과 그 결과 처리가 통째로 절약됩니다.

시끄러운 명령 출력은 서브에이전트로 격리합니다. 30,000자를 넘는 명령 출력은 자동으로 파일로 저장되고 미리보기만 문맥에 남습니다만, 그 미만의 장황한 출력(테스트 로그, 빌드 로그)은 고스란히 문맥을 차지합니다. 로그를 뒤져야 하는 작업은 독립 문맥에서 도는 서브에이전트에 맡기면 메인 세션이 가벼워집니다.

자주 쓰는 명령은 CLAUDE.md에 조용한 플래그와 함께 적어 둡니다. 예를 들어 테스트를 verbose로 돌리는 습관이 있다면, CLAUDE.md에 quiet 플래그가 붙은 명령을 기록해 모델이 처음부터 조용한 버전을 실행하게 하는 식입니다.

가이드가 제시한 우선순위는 이렇습니다. 불필요한 파일 읽기 방지, 긴 세션 분할, 모델/effort 고정, 명령 출력 최소화 순입니다.

이 가이드가 나온 맥락​

읽다 보면 이 가이드는 절약 팁 모음이라기보다 과금 구조 설명서에 가깝습니다. 에이전트형 코딩 도구의 비용은 "몇 마디 나눴나"가 아니라 "문맥 몇 토큰을 몇 번 실어 날랐나"로 결정되는데, 사용자 대부분은 전자로 체감합니다. 그 간극에서 "왜 벌써 한도냐"는 불만이 나오고, 이 문서는 거기에 대한 공식 답변으로 보입니다.

도구 쪽 기본값도 같은 방향으로 움직이고 있습니다. 최근 릴리스에서 서브에이전트 포크가 캐시를 상속하게 된 것도, 포크할 때마다 문맥을 다시 캐싱하는 비용을 없애는 변경입니다. 캐시를 아끼는 방향으로 도구가 정렬되고 있으니, 사용자 습관만 따라가면 됩니다.

오늘부터 바꿀 것 하나만 고르라면 저는 "작업 끝나면 /clear"를 고르겠어요. 제일 쉽고, 제일 큽니다.

참고 자료​

• Maximizing the value of your Claude Code sessions - Claude Blog, 2026-08-14
• Claude API 프롬프트 캐싱 문서