이 페이지의 목차
확인 2026-10-18근거 자료 12건갱신 2026-10-26언급 29곳
이 페이지의 목차
확인 날짜 안내

확인 날짜가 섞인 페이지다. 공식 문서 부분(확장 기능 개요·메모리·스킬 문서, Claude Code 컨텍스트 창)은 원본 날짜 미상이라 수집일(2026-10-18) 기준의 Claude Code 동작이고, 공식 CLI 문서 Claude Code CLI 레퍼런스(원본 날짜 미상, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 부분은 2026-10-21, 블로그 Steering Claude Code 부분은 2026-06-18, 컨텍스트 엔지니어링 글 부분은 2025-09-29 기준이다. 섹션 제목에 기준일을 적었다. 컨텍스트 엔지니어링 글 부분(context rot, 가장 작은 고신호 토큰 집합)은 원칙이고, 표의 비용 등급과 훅 등급 Low는 "(블로그 평가)"라 날짜 계산에서 뺀다. 시스템 프롬프트 덧붙이기의 "그 실행에만"은 공식 CLI 문서와 달라 상충으로 나란히 두고 설명은 공식 기준으로 한다. 페이지 확인 날짜는 2026-10-18이다(가장 오래된 공식 문서 수집일). 표의 "세션 첫 요청 뒤 캐시"(덧붙이기의 프롬프트 캐싱)는 블로그에만 근거했으나, 2026-10-26 수집한 공식 Prompt caching 문서 Claude Code 프롬프트 캐싱(원본 날짜 미상, 서버 Last-Modified 2026-10-26)이 확인한다: 덧붙이기 텍스트 변경을 시스템 프롬프트 변경으로 다루고, 시스템 프롬프트 층은 다음 요청에서 캐시로 읽힌다(아래 표 뒤 문단). CLI 문서의 "records"는 세션에 기록한 프롬프트 텍스트를 다시 쓰는 동작이라 그 자체로는 캐싱 확인이 아니다.

정의#

확장 기능 하나하나가 Claude의 컨텍스트(용어 사전)를 얼마나, 언제 차지하는가다. 원본은 추가하는 모든 기능이 컨텍스트를 어느 정도 쓴다고 말한다. Claude Code 확장 기능 개요

왜 중요한가#

너무 많으면 두 가지 문제가 생긴다. Claude Code 확장 기능 개요

  1. 컨텍스트 창이 찬다.
  2. 잡음이 늘어 Claude가 덜 효과적이 된다. 스킬이 제대로 트리거되지 않거나, Claude가 관례를 놓칠 수 있다.

(편집자 연결) 두 번째 문제와 같은 방향으로 볼 수 있는 일반 원리를 Anthropic 엔지니어링 글이 설명한다(2025-09-29 기준). 컨텍스트 창의 토큰이 늘수록 정보를 정확히 떠올리는 능력이 떨어지고(context rot), 이는 모든 모델에서 나타난다. 그래서 컨텍스트는 한계 수익이 줄어드는 유한한 자원이며, 새 토큰마다 모델의 "attention budget"(주의력 예산)이 조금씩 깎인다. 다만 저하는 절벽이 아니라 기울기다. 효과적인 컨텍스트 엔지니어링 → 컨텍스트 엔지니어링

세션 하나에서 컨텍스트가 차는 모습 (2026-10-18 기준)#

공식 문서 Claude Code 컨텍스트 창은 인증 버그 하나를 고치는 세션을 시뮬레이션으로 재생해, 위 표의 비용이 실제 세션에서 어떻게 쌓이는지 보여 준다. 원본은 토큰 수가 예시이고 실제 값은 CLAUDE.md 크기, MCP 서버, 파일 길이에 따라 다르다고 밝힌다. 그래서 아래에는 순서와 성격만 옮긴다.

  • 입력 전에 이미 찬다. 시스템 프롬프트, 자동 메모리, 환경 정보, MCP 도구 이름, 스킬 설명, 전역·프로젝트 CLAUDE.md가 첫 프롬프트 전에 로드된다. 원본의 말로 프롬프트는 이미 로드된 것에 비해 아주 작고, Claude 컨텍스트의 대부분은 사용자의 말이 아니라 프로젝트 지식이다. Claude Code 컨텍스트 창
  • 파일 읽기가 가장 크다. 원본 팁: "File reads dominate context usage." 경로별 규칙은 맞는 파일을 읽을 때 따라 로드된다. Claude Code 컨텍스트 창
  • 보이는 것과 쓰이는 것이 다르다. 시작 때 로드되는 것과 훅 출력은 터미널에 보이지 않고, 파일 읽기·규칙·명령 출력은 한 줄로만 보이며, 전체가 보이는 것은 프롬프트와 Claude의 응답·diff 정도다. 터미널만 보고 컨텍스트 사용량을 짐작하면 적게 보게 된다는 뜻으로 읽을 수 있다(편집자 해석, 근거: 원본의 "content that never appears in your terminal"과 이벤트별 표시 구분). Claude Code 컨텍스트 창
  • 후속 요청은 같은 컨텍스트에 쌓인다. 앞의 모든 내용이 그대로 남는다. 리서치를 서브에이전트에 맡기면 파일 읽기가 서브에이전트 창에 남고 요약만 돌아온다. Claude Code 컨텍스트 창
  • 확인은 /context: 실제 사용량을 카테고리별로 보여 주고 최적화 제안을 낸다. Claude Code 컨텍스트 창

기능별 로드 시점과 비용#

기능언제 로드무엇이 로드컨텍스트 비용
메모리(CLAUDE.md)세션 시작전체 내용매 요청
출력 스타일세션 시작, 스타일을 바꿀 때 다시활성 스타일의 전체 지시. Default 스타일은 없음매 요청
스킬세션 시작 + 쓸 때시작 때 설명, 쓸 때 전체 내용낮음(설명은 매 요청)*
MCP 서버세션 시작도구 이름. 전체 스키마는 필요할 때도구를 쓰기 전까지 낮음
Code intelligence파일 편집 후, 필요할 때편집 후 진단, 조회 시 심볼 위치낮음. 다른 곳의 파일 읽기를 줄임
서브에이전트스폰할 때지정한 스킬을 담은 새 컨텍스트(포크는 부모 대화)메인 세션과 격리
훅트리거될 때없음(외부에서 실행)0. 훅이 추가 컨텍스트를 돌려주면 예외

(2026-10-18 기준) 공식 출력 스타일 문서가 출력 스타일 행을 더 적는다: 활성 스타일의 지시를 매 요청에 보내 입력 토큰이 늘지만 세션 첫 요청 뒤 프롬프트 캐싱이 비용을 줄인다. 출력 쪽은 내장 Explanatory·Learning이 설계상 Default보다 길어 출력 토큰이 늘고, Concise는 반대다. 세션 중 스타일을 바꾸면 다음 메시지부터 적용된다. Claude Code 출력 스타일 → 출력 스타일

* 스킬 frontmatter에 disable-model-invocation: true를 두면 설명이 컨텍스트에 들어가지 않는다. 직접 쓰지 않은 스킬은 설정의 skillOverrides로 같은 효과를 낸다.

근거: Claude Code 확장 기능 개요 (표는 원본 "Context cost by feature"를 옮긴 것이다)

지시 방법별 비용 등급과 컴팩션 뒤 (2026-06-18 기준)#

블로그 글은 같은 문제를 "컨텍스트 비용과 권위의 맞바꿈"으로 보고, 지시 방법마다 비용 등급과 긴 세션의 압축(컴팩션) 뒤 동작을 붙였다. 원본 표현 그대로 옮긴다. 등급(High·Medium·Low·Moderate)은 블로그 평가이고 제품 사양이 아니다. Steering Claude Code

방법컨텍스트 비용 (원본 등급과 이유, 등급은 블로그 평가)압축 후
CLAUDE.md (루트)High. 관련 여부와 상관없이 모든 줄이 토큰을 씀컴팩션 뒤 다시 읽음
CLAUDE.md (하위 디렉터리)Low. 그 하위 디렉터리를 작업할 때만다시 건드릴 때까지 사라짐
RulesMedium. 경로 범위가 없으면 항상 켜짐다시 주입
스킬Low. 호출 시에만 본문, 호출된 스킬들이 공유 토큰 예산을 나눔공유 예산까지 다시 주입, 오래된 것부터 빠짐
서브에이전트Low. 부르기 전까지 메인 컨텍스트 비용 0, 격리된 창최종 메시지만 돌아옴
훅Low. 설정은 메인 컨텍스트 밖, 일부 출력은 돌아올 수 있음컴팩션을 우회
출력 스타일High(요약표) / moderate(본문). 첫 요청 뒤 캐시압축되지 않음
시스템 프롬프트 덧붙이기Moderate. 세션 첫 요청 뒤 캐시압축되지 않음, 그 실행에만 (공식 문서와 다름, 아래 ‘원본끼리 달랐던 점’ 상자)

근거: Steering Claude Code. 시스템 프롬프트 덧붙이기 행은 공식 CLI 문서가 다르게 적는다(2026-10-21 기준): Claude Code는 첫 요청에서 플래그 텍스트를 반영해 시스템 프롬프트를 한 번 만들어 세션에 기록하고, 컴팩션 전까지 이후 모든 요청(--resume·--continue로 돌아온 나중 실행 포함)이 그 기록을 쓴다. 나중 실행에서 플래그를 바꾸거나 빼면 컴팩션 때나 새 대화에서 반영된다. 기본 동작이고, 기록하지 않는 예외는 아래 허브 페이지에 있다. 원본은 이 과정을 "캐시"라고 부르지 않고 "records"라고 쓴다. Claude Code CLI 레퍼런스 → Claude Code CLI 플래그

(2026-10-26 기준) 덧붙이기 행의 "세션 첫 요청 뒤 캐시"는 공식 Prompt caching 문서가 확인한다. 이 문서는 요청을 시스템 프롬프트(핵심 지시·도구 정의), 프로젝트 맥락(CLAUDE.md·자동 메모리·범위 없는 rules), 대화 순서로 쌓고, 시스템 프롬프트 층은 바뀌지 않으면 다음 요청에서 캐시로 읽힌다(층 표의 "바뀌는 때"는 흔한 예일 뿐 전부가 아니라고 원본이 밝힌다). 그리고 재개 때 다른 --append-system-prompt 텍스트를 주는 것을 시스템 프롬프트 변경으로 다룬다. 두 문장을 함께 읽으면 덧붙인 텍스트는 캐시되는 시스템 프롬프트 층에 들어간다(원본이 "덧붙이기가 캐시된다"를 한 문장으로 쓰지는 않는다). 출력 스타일을 세션 중 바꾸면 새 지시를 대화 메시지로 전달해 캐시가 유지된다(v2.1.251 이상). 무엇이 캐시를 깨고 지키는지 전체 목록은 프롬프트 캐싱. Claude Code 프롬프트 캐싱

원본끼리 달랐던 점(정리됨)--append-system-prompt 재개 동작
  • Steering Claude Code (2026-06-18): 시스템 프롬프트 덧붙이기는 "applies only to that invocation"(그 실행에만 적용), 압축되지 않는다("Never compacted").
  • Claude Code CLI 레퍼런스 (수집 2026-10-21): 기본 동작으로 첫 요청에서 만든 시스템 프롬프트를 세션에 기록하고, 컴팩션 전까지 --resume·--continue로 돌아온 나중 실행에서도 쓴다. 나중 실행의 다른 플래그 텍스트(또는 플래그 없음)는 컴팩션 때나 새 대화에서 반영된다.
  • 설명과 실무는 공식 CLI 문서 기준. 블로그 문장은 출처와 함께 남긴다. 원문 인용·예외: Claude Code CLI 플래그

스킬 행의 컴팩션 동작은 공식 스킬 문서가 숫자로 확인한다(2026-10-18 기준): 스킬마다 가장 최근 호출의 앞 5,000토큰, 합계 25,000토큰, 최근 호출부터 채움. Claude Code 스킬 출력 스타일의 비용 등급은 원본 안에서 요약표와 본문이 다르다. 전체 비교는 Claude Code 확장 기능 고르기.

(2026-10-18 기준) 공식 서브에이전트 문서가 서브에이전트 비용의 조건을 더한다. (1) 설명(description)은 시작 때 컨텍스트를 차지해, 내장을 뺀 설명 합이 15,000토큰을 넘으면 시작 때 경고가 뜬다. 세부는 실행할 때만 로드되는 본문으로 옮긴다. (2) 서브에이전트는 자기 요청을 보내 메인 대화와 같은 사용량 한도에 잡히고, 많은 서브에이전트가 자세한 결과를 돌려주면 메인 컨텍스트도 많이 쓴다. (3) 포크는 부모의 프롬프트 캐시를 재사용해 같은 맥락이 필요한 일에서 새 서브에이전트보다 싸다. (4) MCP 서버를 서브에이전트 frontmatter에 인라인으로 두면 그 도구 설명이 메인 컨텍스트에 들지 않는다. Claude Code 서브에이전트 → 서브에이전트

원본이 짚은 비용 함정: Steering Claude Code

  • 공유 저장소의 CLAUDE.md는 주인 없는 설정 파일처럼 모든 팀이 덧붙이고 아무것도 지우지 않아 불어난다. 모든 줄이 모든 엔지니어의 모든 세션에 로드돼 토큰을 쓰고, 정말 중요한 지시의 준수를 희석한다. → CLAUDE.md 작성·구성
  • 범위(paths) 없는 규칙은 CLAUDE.md에 넣은 것과 기계적으로 같다. 항상 로드되고 항상 토큰을 쓴다.
  • 훅은 Claude에게 주는 지시가 아니라 하네스가 실행하는 코드라 비용이 낮다. 다만 차단 훅의 표준 오류처럼 일부 출력은 컨텍스트에 남는다. → 훅

스킬 쪽 세부 (2026-10-18 기준, Claude Code 스킬):

  • 목록 비용은 매 턴 든다. 스킬 이름과 설명 목록은 Claude가 쓰든 안 쓰든 매 턴 컨텍스트에 더해진다. 목록은 모델 컨텍스트 창의 1% 문자 예산에 맞춰지고(skillListingBudgetFraction), 넘치면 가장 덜 부르는 스킬의 설명부터 빠진다(이름은 남음). 스킬 하나의 description+when_to_use는 1,536자에서 잘린다.
  • 본문은 부른 뒤 계속 남는다. 호출된 스킬의 렌더된 내용은 이후 턴에도 대화에 남으므로, 남은 모든 줄이 반복되는 토큰 비용이다. 그래서 원본은 본문을 CLAUDE.md처럼 짧게 쓰라고 한다. 같은 내용을 다시 부르면 두 번째 사본 대신 짧은 메모만 붙는다.
  • 보조 파일은 필요할 때만. 큰 참고 문서·예시는 스킬 폴더의 별도 파일로 두면 스킬이 돌 때마다 로드되지 않고, 스크립트는 로드되지 않고 실행된다.
  • 확인과 정리: /doctor는 스킬 목록의 컨텍스트 비용과 큰 기여 항목을 추정하고, /context의 Skills 행은 예산 적용 뒤 크기를 보여 준다. /skill-doctor(v2.1.252 이상)는 스킬별 비용과 사용 빈도를 보여 주고 한 번도 호출되지 않은 스킬을 표시한다. 끌 때는 비용이 큰 것부터. 우선순위 낮은 스킬은 skillOverrides에서 "name-only"로 설명을 빼고, 사용자만 부를 스킬은 disable-model-invocation: true로 설명도 싣지 않는다.

세부와 대처 순서: 스킬 문제 해결

메모리 쪽 세부 (2026-10-18 기준, Claude Code 메모리):

  • 작업 디렉터리와 그 위의 CLAUDE.md는 시작 때, 하위 디렉터리의 CLAUDE.md는 그 디렉터리 파일을 다룰 때 로드된다. paths가 없는 .claude/rules/ 파일은 시작 때, paths가 있는 규칙은 맞는 파일을 다룰 때 로드된다.
  • @path import는 비용을 줄이지 않는다. 가져온 파일도 시작 때 로드된다.
  • 블록 단위 HTML 주석은 컨텍스트에 넣기 전에 지워져 토큰을 쓰지 않는다.
  • 자동 메모리(Auto memory)는 색인 MEMORY.md의 앞 200줄 또는 25KB까지만 시작 때 로드되고, 주제 파일은 필요할 때 읽는다. CLAUDE.md는 4 MiB까지 전부 로드된다.

비용을 줄이는 원본의 방법#

비용을 줄이는 블로그 글의 방법 (2026-06-18 기준)#

  • CLAUDE.md는 200줄 이하로, 팀별 관례는 경로별 rules로, 절차는 스킬로 옮겨 관련 있을 때만 로드되게 한다. Steering Claude Code
  • 모노레포에서는 팀 디렉터리마다 하위 디렉터리 CLAUDE.md를 두어 각 팀이 자기 관례만 로드하게 하고, 개발자는 claudeMdExcludes로 손대지 않는 팀의 파일을 건너뛴다. Steering Claude Code
  • 중간 결과로 메인 대화를 어지럽힐 곁가지 작업은 서브에이전트로 돌린다. 메인 세션에는 최종 메시지만 돌아온다. Steering Claude Code → 서브에이전트

기능 밖에서 줄이는 방법 (컨텍스트 엔지니어링) (2025-09-29 기준)#

확장 기능 설정과 별개로, 에이전트가 쓰는 컨텍스트 자체를 줄이는 원칙과 기법이다. 효과적인 컨텍스트 엔지니어링