Claude Code의 상주 컨텍스트를 62% 절감한 이야기 — prompt caching 시대의 하네스 설계

서론

결론부터 말씀드리겠습니다.

Claude Code의 상주 컨텍스트(resident context)를 635행에서 239행으로 줄였더니, 매 세션의 비용은 물론 버그를 찾아내는 방식까지 바뀌었습니다.

저는 1인 기업을 운영하고 있으며, 실무의 상당 부분을 Claude Code에 맡기고 있습니다. 요컨대 「1인 + AI COO」 체제입니다.

Claude Code를 업무에 깊이 활용하다 보면, CLAUDE.md나 .claude/rules/에 규칙들이 쌓여갑니다.

실수가 발생할 때마다 내용을 추가합니다. 이 피드백 루프 자체는 제대로 작동합니다.

하지만 어느 날 문득 실측을 해보았습니다.

매 세션 자동으로 주입되는 상주 컨텍스트(CLAUDE.md + .claude/rules/) —— 합계 635행 / 65KB.

솔직히, 못 본 척하고 싶어졌습니다.

이 기사에서는 이를 239행(▲62%) / 16KB(▲75%)까지 깎아낸 절차를 기술합니다. 근거는 prompt caching입니다. 덤으로, 다음 날 조용한 위음성(false negative) 버그까지 하나 찾아냈습니다.

과제: 「키워온 규칙」이 매 세션의 고정비가 되다

CLAUDE.md 자체는 51행의 포인터형(상세 내용은 각 파일로의 링크만 포함)으로 억제해 두었습니다.

여기까지는 우등생입니다.

문제는 링크된 대상이었습니다.

.claude/rules/가 조용히 비대해지고 있었던 것입니다.

common-mistakes.md 278행 — 그중 188행은 시계열 실수 로그 상세(경위·원인·대책의 풀 로그)
harness-review.md 99행 — 월 1회밖에 사용하지 않는 월간 리뷰 체크리스트
session-hygiene.md 62행 — 운영 규칙과 배경 해설이 혼재
commands.md 47행 — 커맨드 목록표와 복합 태스크 판정표

하지만 진짜 문제는 행수가 아닙니다.

업데이트 빈도입니다.

「실수가 발생하면 common-mistakes.md에 추가한다」는 운영 방식이기에, 상주 파일 중에서 가장 큰 파일이 가장 빈번하게 편집됩니다.

이것이 prompt caching과 최악의 상성이었습니다.

prompt caching의 원리: 편집 = 캐시 파괴

왜 최악인가.

Anthropic의 공식 블로그 「Lessons from building Claude Code: Prompt caching is everything」(2026-04-30)의 요점은 3가지입니다.

캐시는 prefix 일치 — 프롬프트 시작 부분부터 완전히 일치하는 범위만 캐시 히트(cache hit)가 발생한다
정적 → 동적 순서가 철칙 — system prompt·rules 등 안정적인 부분을 앞에, 대화 등 변동하는 부분을 뒤에 배치한다
편집은 그 이후를 전부 파괴 — 상주 파일을 단 1행이라도 편집하면, 그 위치 이후의 prefix가 무효화되어 다음 세션부터 해당 부분을 일반 요율(raw rate)로 재처리한다

즉 「실수가 있을 때마다 상주 rules에 추가한다」는 저의 운영 방식은, 가장 빈번하게 편집되는 파일을 매 세션의 prefix에 두는 안티 패턴이었던 것입니다.

규칙을 충실히 만들수록 캐시가 깨지는 빈도와 재처리되는 양이 동시에 늘어납니다.

좋은 의도로 내용을 추가할수록 고정비가 불어나는 구조입니다.

input 단가가 높은 프론티어 모델(frontier model)을 사용할수록, 이 차이는 상시적인 비용으로 작용합니다.

설계 원칙: 상주는 「정적·안정」이 정의

여기서 도출한 설계 원칙은 단 한 줄입니다.

상주시켜도 좋은 것은 「정적(저빈도 업데이트)·안정·모든 세션과 관련됨」의 3가지 조건을 만족하는 것뿐입니다.

반대로 조건을 결여하는 것에는 퇴피처(대피 장소)를 정합니다.

성질	퇴피처
고빈도로 추가됨 (실수 로그 등)	knowledge 측의 아카이브 파일 (상주 외)
...

시도해 본 4가지 분리

이 원칙으로 상주 rules를 분해했습니다.

작업 시간은 1~2시간. 해보니 그 정도였습니다.

1. 실수 로그 → 아카이브 분리

common-mistakes.md에서 시계열 실수 로그 및 퇴역된 섹션을 assets/knowledge/mistake-log-archive.md로 이동. 상주 측에는 현역 규칙 약 50행만을 남기고, 아카이브로의 링크를 배치했습니다.

2. 월간 체크리스트 → skill(스킬)화

99행의 harness-review.md를 .claude/skills/harness-review/로 이동했습니다. skill은 description(발화 키워드)만 상주하며, 본문은 호출되었을 때 로드됩니다. "한 달에 한 번 쓰는 절차서가 매 세션마다 포함되어 있는" 상태를 해소한 것입니다.

3. 해설 → knowledge(지식) 분리

session-hygiene.md를 운영 규칙 10행 미만으로 압축하고, 배경 해설은 knowledge 측으로 옮겼습니다.

4. 커맨드 표 압축

커맨드 목록은 /help로 충분하기 때문에 삭제하고, 복합 태스크 판정표만 약 25행으로 남겨두었습니다.

결과는 다음과 같습니다.

지표	Before	After	절감
상주 컨텍스트 행수 (CLAUDE.md + .claude/rules/)	635행	239행	▲62%
상주 컨텍스트 크기 (CLAUDE.md + .claude/rules/)	65KB	16KB	▲75%

링크 5곳을 수정하고, 후크(hook)의 셀프 테스트가 모두 PASS 상태인 것을 확인한 뒤 commit했습니다.

실수 기록 운영도 변경: 상주는 규칙 1행 · 상세 내용은 아카이브

한 번 줄이고 끝낸다면 다시 비대해질 것입니다.

(다이어트와 같습니다...)

그래서 실수 기록의 운영 자체를 이층 구조로 변경했습니다.

• 아카이브 (상주 외): 새로운 실수의 상세 경위(무슨 일이 일어났는가 · 원인 · 대책 · 교훈)는 여기에 추가한다.
• 상주 규칙: 추상화된 재발 방지 규칙을 1행만 추가한다.

상세 내용을 쓰는 장소가 캐시(cache) 밖으로 나감으로써, 상주 rules의 편집 빈도가 급감하여 prefix(접두사)가 안정됩니다.

돌이켜 생각해보면—행수 절감은 단 한 번의 효과입니다. 하지만 편집 빈도의 절감은 매일 효과를 발휘합니다.

진정한 목적은 이쪽이었습니다.

다음 날, skill의 결정론적 스크립트가 사이런트 위음성(silent false negative)을 검출하다

여기서부터는 실패담입니다.

이번 재설계에서는 주간 보고 커맨드도 skill화하여, 사전 체크(공개 사이트의 생존 확인 curl · open PR의 gh 목록 취득)를 LLM의 수작업에서 결정론적 스크립트(deterministic script)로 교체했습니다.

그 파일럿 운영 2일 차.

스크립트 출력 결과, 어떤 리포지토리의 open PR이 빈 값으로 표시되었습니다.

저는 중간 보고에서 "0건이 되었다"라고 발언해 버렸습니다.

직후에 사실 관계를 확인하여 밝혀진 실태는 다음과 같습니다.

• 실제로는 25건의 PR이 open 상태였다.
• gh CLI가 간헐적으로 401을 반환하고 있었다 (3회 중 1회 실패하는 일시적 장애).
• 스크립트가 2>/dev/null로 에러를 묵살하고 있었으며, exit code(종료 코드)도 검사하지 않았다.

"실측했다"고 생각했지만, 실측의 실패 그 자체를 검지할 수 없는 구조였습니다.

이것은 솔직히 뼈아팠습니다.

즉시 다음과 같이 수정했습니다.

• gh 실패 시 1회 재시도하고, 그래도 실패하면 "❓ 불명 (0건이라고 쓰지 않음)"이라고 명시적으로 출력한다.
• 성공했는데 0건인 경우에는 "(open PR 없음)"을 명시적으로 표시하여, 빈 출력(empty output)과 취득 실패를 구분한다.

교훈은 한 마디입니다.

빈 출력 ≠ 0건.

실측 스크립트는 "성공한 실측"과 "실패한 실측"을 출력으로 구분할 수 없다면 의미가 없습니다.

다만, 다행스러운 점도 있었습니다.

수작업 그대로였다면 "어쩌다 못 보고 지나쳤다"며 넘겼을 실패가, 스크립트라는 구조가 됨으로써 버그로 특정할 수 있었고 영구적으로 수정할 수 있었습니다.

skill에 스크립트를 동봉하는 가치는 바로 여기에 있다고 느낍니다.

요약: 상주 컨텍스트 체크리스트

• 상주 파일은 "정적 · 안정 · 모든 세션 관련"이라는 3가지 조건을 만족하는가
• 빈번하게 추가되는 로그(실수 로그 · 작업 로그)가 상주 항목에 섞여 있지 않은가 → 아카이브로 분리
• 저빈도로만 사용하는 절차서(월간 체크리스트 등)가 상주하고 있지 않은가 → skill화
• 규칙과 해설이 혼재되어 있지 않은가 → 규칙만 상주, 해설은 knowledge로
• 추가 운영 방식이 "상주에는 규칙 1행 · 상세 내용은 캐시 외"로 되어 있는가
• 결정론적 스크립트는 "실패한 실측"을 출력으로 구분할 수 있는가 (빈 출력 ≠ 0건)
• 구모델 유래 규칙을 3~6개월마다 정리(inventory)하고 있는가?

규칙을 추가하는 것 자체는 올바른 피드백 루프 (feedback loop) 입니다.

다만 prompt caching (프롬프트 캐싱) 시대에는 "어디에 작성하느냐"에 따라 매 세션의 비용이 달라집니다.

우선 자신의 환경에서 상주하는 행 수 (resident lines) 를 직접 측정해 보는 것은 어떨까요?

숫자를 확인하는 순간부터 절감은 시작됩니다.

Discussion