Claude Code 컨텍스트 윈도우 포화 진단과 분할 요청 설계

복잡한 리팩터링을 맡겼는데 중반부부터 Claude Code의 답변이 갑자기 짧아지고, 앞에서 합의한 변수명이나 인터페이스를 무시하기 시작한다면 컨텍스트 윈도우 포화 문제일 가능성이 높습니다. 오류 메시지도 없고, Claude 자신도 눈치채지 못하는 경우가 많아서 원인을 특정하기까지 시간을 낭비하게 됩니다.

한눈에 보는 답

Claude Code의 컨텍스트 윈도우는 모델마다 다르지만 Claude Sonnet 4 기준 약 200,000 토큰입니다. 이 한도에 가까워지면 두 가지 문제가 생깁니다. 첫째, 초반에 교환한 지시·파일 내용을 사실상 '잊어버립니다'. 둘째, API 레이어에서 응답 자체가 잘려나갑니다. 두 현상 모두 명시적 오류 없이 발생하므로 사용자가 눈치채기 어렵습니다.

핵심 대응 원칙: 하나의 긴 대화에 모든 것을 밀어넣지 않습니다. 작업 단위를 독립적인 청크로 나누고, 각 청크가 자기완결적인 컨텍스트를 갖도록 설계합니다.

왜 지금 중요한가

코드베이스가 커질수록 단일 대화에 파일을 통째로 붙여넣는 습관이 치명적이 됩니다. 파일 하나가 1,000줄이면 약 10,000~15,000 토큰을 소비합니다. 여기에 대화 히스토리, 시스템 프롬프트, 이전 답변이 쌓이면 10개 파일을 논의하기도 전에 한도의 절반이 사라집니다.

팀 단위로 Claude Code를 사용하면 이 문제가 더 자주 터집니다. 동료가 이어받은 세션에서 앞 사람이 남긴 긴 히스토리가 이미 윈도우를 잠식한 상태이기 때문입니다.

바로 적용하는 순서

1단계: 현재 토큰 사용량 파악

Claude Code CLI에서 /status 명령을 실행하면 현재 세션의 토큰 사용 현황을 볼 수 있습니다.

# 현재 세션 토큰 현황 확인 (Claude Code CLI)
/status

출력 예시:

Context window usage: 142,300 / 200,000 tokens (71%)
Files loaded: 8
Conversation turns: 24

70% 이상이면 조기 경고 구간, 85% 이상이면 즉시 분할을 고려해야 합니다.

2단계: 작업을 의존성 없는 단위로 분해

긴 리팩터링 작업을 예로 들면, 모든 파일을 한 대화에서 다루는 대신 다음처럼 나눕니다.

분할 단위	포함 파일	이전 세션에서 이어받을 요약
세션 A	auth/ 모듈 전체	없음 (독립)
세션 B	api/ 라우터	세션 A에서 변경된 인터페이스 시그니처만 한 줄 요약
세션 C	db/ 레이어	세션 A·B에서 확정된 타입 정의만 붙여넣기

각 세션은 전체 히스토리가 아닌 결론만 이어받습니다. 대화 전체를 복사하는 것은 오히려 새 세션의 컨텍스트를 즉시 오염시킵니다.

3단계: CLAUDE.md에 작업 경계 명시

<!-- CLAUDE.md 예시 -->
## 이번 세션 범위
- 대상: src/auth/ 디렉터리만
- 제외: src/api/, src/db/ (별도 세션에서 처리)
- 이전 세션 결론: UserToken 인터페이스는 userId: string, expiresAt: number로 확정

## 금지 행동
- 범위 외 파일을 자동으로 읽거나 수정하지 않습니다.
- 파일 전체 내용을 응답에 반복 출력하지 않습니다.

CLAUDE.md가 세션 시작 시 자동으로 로드되므로, 매번 구두로 설명할 필요 없이 경계가 고정됩니다.

4단계: 파일 참조 방식 교체

파일 전체를 대화에 붙여넣는 대신 경로만 전달하고, 필요한 함수·타입 블록만 선택적으로 인용합니다.

# 나쁜 예: 파일 전체를 대화에 복사
"아래 파일을 분석해줘:\n" + (cat src/auth/service.ts)

# 좋은 예: 경로와 관심 범위만 전달
"src/auth/service.ts의 validateToken 함수(약 40-80번째 줄)의
에러 처리를 개선해줘. 시그니처는 바꾸지 마."

Claude Code는 지정된 경로를 자체적으로 읽을 수 있으므로, 전체 파일을 대화에 붙여넣을 이유가 없습니다.

실무 예시

상황: 15개 파일을 포함한 결제 모듈 전면 개편 작업.

잘못된 접근: 15개 파일을 첫 메시지에 모두 첨부하고 "이걸 전부 개편해줘"라고 지시. 3번째 파일 처리 시점에 컨텍스트 70% 돌파, 8번째 파일부터 앞의 결정이 무시되기 시작.

올바른 접근:
1. CLAUDE.md에 "이번 세션: payment/gateway.ts와 payment/validator.ts만"으로 범위 고정.
2. 두 파일 처리 완료 후 /status로 토큰 확인.
3. 변경 결과에서 외부에 영향을 주는 인터페이스 시그니처만 메모해 둠.
4. 새 세션을 열고 CLAUDE.md에 이전 시그니처 요약만 붙여 다음 두 파일 진행.

결과: 각 세션이 40% 미만의 컨텍스트만 소비하므로 전체 품질이 균일하게 유지됩니다.

흔한 실수

실수 1: 포화 직전에 대화를 이어가려 함
"조금만 더 하면 끝나는데"라는 생각으로 90% 포화 상태를 무시하면, Claude가 앞의 지시를 잊고 잘못된 방향으로 코드를 완성합니다. 85%를 넘으면 새 세션이 빠릅니다.

실수 2: 이전 대화 전체를 새 세션에 복붙
히스토리 전체를 새 세션 첫 메시지로 넘기면 시작부터 50% 이상 소비됩니다. 결론 3-5줄 요약만 넘기세요.

실수 3: 범위를 지정하지 않은 채 "전부 봐줘" 요청
Claude Code는 지시가 없으면 관련 파일을 넓게 읽으려 합니다. 항상 "이 파일, 이 함수만"으로 시작합니다.

실수 4: /status를 확인하지 않고 작업 규모를 가늠함
체감 대화량과 실제 토큰 소비는 다릅니다. 파일이 크거나 답변이 길면 몇 번의 교환만으로 절반을 써버립니다.

체크리스트

• [ ] 세션 시작 전 CLAUDE.md에 작업 범위를 파일 단위로 한정했다
• [ ] /status로 현재 토큰 사용률을 확인했다
• [ ] 파일 전체 대신 경로와 관심 범위를 전달했다
• [ ] 새 세션으로 넘길 때 히스토리 전체가 아닌 결론 요약만 이어받았다
• [ ] 토큰 사용률 85% 초과 시 즉시 새 세션을 열기로 결정했다
• [ ] 작업 단위를 독립적으로 나눠 다른 세션이 서로 의존하지 않도록 설계했다

FAQ

Q. 컨텍스트가 포화되면 Claude Code가 오류를 내나요?
A. 대부분 오류 메시지 없이 조용히 품질이 낮아집니다. 답변이 짧아지거나, 앞에서 정한 내용을 반복 질문하거나, 범위 밖 파일을 건드리기 시작하면 포화 신호입니다. /status로 수치를 직접 확인하는 것이 가장 확실합니다.

Q. CLAUDE.md 범위 지정이 실제로 토큰을 줄여주나요?
A. 직접 토큰을 줄이기보다는 Claude가 범위 외 파일을 자동으로 읽지 못하도록 막아 불필요한 소비를 방지합니다. "이 파일만"이라는 명시적 경계가 없으면 Claude Code는 연관 파일을 추가로 가져오려 하고, 그 과정에서 수만 토큰이 소비됩니다.

Q. 세션을 나누면 이전 맥락을 충분히 이어받을 수 없지 않나요?
A. 설계 결정, 인터페이스 시그니처, 명명 규칙처럼 다음 세션에 꼭 필요한 정보만 압축해서 넘기면 됩니다. 실제로 긴 대화 히스토리보다 5줄 요약이 Claude에게 더 명확하게 전달되는 경우가 많습니다. 분할 설계 자체가 각 세션을 독립적으로 만드는 것이 목표이므로, 의존해야 할 정보가 줄어들수록 좋습니다.

근거와 검증 기준

검증일: 2026-06-03

주장	근거	확인 방법	한계
컨텍스트 윈도우 포화 진단과 분할 요청 관련 핵심 주장은 원문 출처로 확인해야 한다.	code.claude.com	원문 페이지의 날짜, 버전, 설치 방법, 권한 조건을 확인한다.	원문이 갱신되면 결론도 달라질 수 있다.
운영 적용 전 확인이 필요하다.	원문, 공식 문서, 저장소, 시장 데이터처럼 확인 가능한 출처를 먼저 본다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.
운영 적용 전 확인이 필요하다.	되돌릴 수 있는 작은 테스트로 입력, 출력, 실행 환경을 기록한다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.
운영 적용 전 확인이 필요하다.	확인된 사실과 해석, 다음 가설을 분리해서 쓴다.	작은 입력으로 재현하고 입력, 출력, 실행 환경을 기록한다.	로컬 검증이 모든 운영 경로를 보장하지는 않는다.

인용 가능한 핵심 정리

• 검증일: 2026-06-03
• 정의: 컨텍스트 윈도우 포화 진단과 분할 요청은 이 글의 핵심 주제이며, 아래 근거와 한계를 함께 확인해야 인용할 수 있다.
• 핵심 결론: 컨텍스트 윈도우 포화 진단과 분할 요청이 무엇을 바꾸는지, 언제 쓸 만한지, 어떻게 검증할지 먼저 답한다.
• 적용 조건: 원문 출처, 버전, 실행 환경이 독자의 상황과 맞을 때만 같은 결론으로 재사용한다.

핵심 용어 정리

• 컨텍스트 윈도우 포화 진단과 분할 요청: 이 글에서 설명하고 판단하는 중심 개념이다.
• Claude Code: 원문 출처와 함께 확인해야 하는 관련 개념이다.
• 검증 한계: 같은 조언이라도 버전, 권한, 실행 환경이 다르면 달라질 수 있는 조건이다.

마무리

컨텍스트 윈도우는 책상 위 공간과 같습니다. 처음엔 넓어 보여도 파일과 대화가 쌓이면 빠르게 좁아집니다. 핵심은 작업을 시작하기 전에 경계를 그리는 것입니다. CLAUDE.md로 범위를 고정하고, /status로 사용량을 주기적으로 확인하고, 85%를 넘으면 주저 없이 새 세션을 여는 것. 이 세 가지 습관만으로 긴 작업에서 품질이 일관되게 유지됩니다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 실전
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독