04. 컨텍스트 윈도우 & 토큰 관리

핵심 명제: AI 네이티브 개발은 곧 컨텍스트 싸움이다. 한정된 컨텍스트 윈도우 안에서 꼭 필요한 정보만 정확하게 전달하는 것이 생산성의 본질이다.

---

목차

1. 토큰이란?
2. 토큰 누적 메커니즘
3. 컨텍스트 윈도우 = 대화 드럼통
4. 컨텍스트 관리 명령어
5. 컨텍스트 관리 워크플로우
6. 토큰 효율적 사용 4가지 전략
7. 컨텍스트를 차지하는 요소들
8. 핵심 메시지: AI 네이티브 개발 = 컨텍스트 싸움

---

1. 토큰이란?

1.1 기본 개념

토큰(Token)은 AI가 텍스트를 이해하는 최소 단위다. 사람이 글을 읽을 때 단어 단위로 인식하듯, AI 모델은 텍스트를 토큰이라는 조각으로 쪼개서 처리한다. 다만 토큰은 단어와 정확히 일치하지 않는다. 한 단어가 여러 토큰이 될 수도 있고, 여러 글자가 하나의 토큰이 될 수도 있다.

1.2 토큰 분해 예시

"안녕하세요"  → 약 5 토큰  (한글은 글자당 약 1토큰)
"네"          → 약 1 토큰
"Hello"       → 1 토큰     (영어 일반 단어는 보통 1토큰)
"indivisible" → 3~4 토큰   (긴 영단어는 여러 토큰으로 분해)
"function"    → 1 토큰     (코드에서 자주 나오는 키워드는 1토큰)
"getUserById" → 3~4 토큰   (카멜케이스는 여러 토큰으로 분해)

언어별 토큰 효율 차이:

언어	같은 의미의 문장	대략적 토큰 수
영어	"Please fix the login bug"	~6 토큰
한국어	"로그인 버그를 수정해 주세요"	~12 토큰
코드	if (user.isLoggedIn())	~8 토큰

한국어는 영어 대비 약 1.5~2배의 토큰을 소비한다. 이는 AI 모델의 토크나이저(tokenizer)가 영어 기준으로 학습되었기 때문이다. 한글 한 글자가 대체로 1토큰을 차지하는 반면, 영어는 한 단어가 1토큰인 경우가 많다.

1.3 토큰 = 비용 단위

Claude Code에서 토큰은 곧 비용이자 성능을 결정하는 핵심 지표다.

요청 토큰 (Input)  + 응답 토큰 (Output)  = 총 사용 토큰
───────────────────────────────────────────────────────
사용자가 보낸 것     AI가 생성한 것        과금 및 컨텍스트 소비 기준

• 요청 토큰(Input Token): 사용자의 질문, 이전 대화 기록, 시스템 프롬프트, 참조 파일 등 AI에게 전달되는 모든 텍스트
• 응답 토큰(Output Token): AI가 생성하는 답변, 코드, 설명 등

요점: 토큰을 아끼는 것은 단순히 비용 절감이 아니다. 한정된 컨텍스트 윈도우를 효율적으로 사용해야 AI가 정확한 답변을 할 수 있다.

---

2. 토큰 누적 메커니즘

Claude Code는 대화 맥락을 유지하기 위해 매번 이전 대화 전체를 함께 전송한다. 이것이 토큰이 기하급수적으로 누적되는 핵심 원인이다.

2.1 누적 과정 시각화

2.2 누적 계산 상세

순서	사용자 입력	전송되는 양	AI 응답	이번 요청 총 토큰	누적 대화 크기
1번째	5토큰	5토큰	1토큰	6토큰	6토큰
2번째	3토큰	6 + 3 = 9토큰	4토큰	13토큰	13토큰
3번째	3토큰	13 + 3 = 16토큰	20토큰	36토큰	36토큰
4번째	5토큰	36 + 5 = 41토큰	15토큰	56토큰	56토큰
5번째	3토큰	56 + 3 = 59토큰	10토큰	69토큰	69토큰

핵심 포인트:

• 사용자가 보내는 것은 겨우 3~5토큰이지만, 이전 대화 전체가 매번 함께 전송된다.
• 5번째 요청 시점에서 사용자가 타이핑한 것은 총 19토큰이지만, 누적 대화 크기는 69토큰이다.
• AI가 코드처럼 긴 응답을 생성하면 누적 속도가 급격히 빨라진다.
• 대화가 길어질수록 같은 질문이라도 훨씬 많은 토큰을 소비한다.

2.3 왜 이전 대화를 매번 보내는가?

AI 모델은 상태를 기억하지 못한다(stateless). 매 요청이 독립적이다. "3번째 요청에서 언급한 함수를 수정해 줘"라고 말하려면, 3번째 요청의 내용도 함께 보내야 AI가 맥락을 이해한다. 이것이 LLM의 근본적인 설계 방식이다.

일반적 오해:  AI가 이전 대화를 "기억"한다
실제 동작:    매번 처음부터 전체 대화를 읽고 답변한다

---

3. 컨텍스트 윈도우 = 대화 드럼통

3.1 컨텍스트 윈도우란?

컨텍스트 윈도우(Context Window)는 AI 모델이 한 번에 처리할 수 있는 토큰의 최대 용량이다. 드럼통에 비유하면, 대화 내용이 물이고 컨텍스트 윈도우는 드럼통의 크기다.

3.2 모델별 컨텍스트 윈도우

모델	컨텍스트 윈도우	비유	적합한 작업
Haiku	200K 토큰	책 1권	간단한 질문, 코드 포맷팅, 빠른 응답
Sonnet	200K 토큰	책 1권	일반적인 코드 작성, 디버깅, 리팩토링
Opus	200K 토큰	책 1권	복잡한 설계, 아키텍처 결정, 어려운 디버깅
Sonnet[1m]	1,000K 토큰	책 5권	대규모 코드베이스 분석, 장기 작업
Opus[1m]	1,000K 토큰	책 5권	대규모 설계, 전체 시스템 리뷰

3.3 드럼통이 차오르면 벌어지는 일

컨텍스트 윈도우의 사용률에 따라 AI의 성능이 달라진다. 이것은 매우 중요한 개념이다.

3.4 성능 저하의 구체적 증상

60~80% 구간 (주의):

• AI가 앞서 합의한 설계 방향을 잊고 다른 방식으로 구현
• 이전에 수정한 파일을 다시 수정하려는 시도
• 응답 길이가 불필요하게 길어짐 (핵심에서 벗어남)

80% 이상 구간 (위험):

• 이미 짠 코드를 다시 개발: 10분 전에 완성한 함수를 처음부터 다시 작성
• 환각(hallucination) 증가: 존재하지 않는 API, 라이브러리, 파일 경로를 자신있게 언급
• 맥락 혼동: 파일 A의 내용을 파일 B의 것으로 착각
• 토큰 대량 낭비: 이미 해결한 문제를 반복 시도하며 토큰만 소비
• 반복 루프: 같은 에러를 고치려고 같은 시도를 반복

실무 팁: 컨텍스트가 60%를 넘으면 "AI가 이상한 소리를 하기 시작한다"는 느낌이 온다. 이 느낌이 올 때가 바로 /compact 또는 /clear를 실행할 타이밍이다.

---

4. 컨텍스트 관리 명령어

Claude Code는 컨텍스트 관리를 위한 3가지 핵심 슬래시 명령어를 제공한다.

4.1 /clear - 대화 기록 완전 초기화

/clear

동작:

• 현재 대화의 모든 기록을 삭제한다.
• 컨텍스트 윈도우를 0%로 리셋한다.
• CLAUDE.md 등 시스템 프롬프트는 유지되지만, 대화 내용은 완전히 사라진다.

사용 시점:

• 새로운 기능 개발을 시작할 때 (가장 중요!)
• 이전 작업과 무관한 새로운 작업을 시작할 때
• AI가 맥락을 심하게 혼동할 때
• 컨텍스트 사용량이 80%를 넘었을 때

주의:

• /clear 후에는 이전 대화에서 합의한 내용, 결정 사항 등이 모두 사라진다.
• 중요한 결정이나 맥락은 /clear 전에 CLAUDE.md나 메모에 기록해 두자.

실무 패턴:
  1. 기능 A 작업 완료
  2. 중요한 결정 사항을 CLAUDE.md에 기록
  3. /clear 실행
  4. 기능 B 작업 시작

4.2 /compact - 대화 기록 압축

/compact
/compact [커스텀 압축 지시]

동작:

• AI가 현재까지의 대화를 읽고, 핵심 내용만 추려서 요약본으로 교체한다.
• 코드 변경 이력, 결정 사항, 현재 진행 상황 등을 보존하면서 토큰을 줄인다.
• 대략 대화 크기를 40~60% 수준으로 줄여 준다.

사용 시점:

• 컨텍스트 사용량이 60~80%일 때
• 현재 작업을 이어서 해야 하지만, 컨텍스트 여유가 필요할 때
• 긴 디버깅 세션 중간에

커스텀 압축 지시 활용:

/compact 현재 작업 중인 파일 목록과 각 파일의 수정 내역을 중심으로 압축해 줘
/compact 에러 해결 과정과 최종 해결책만 남기고 압축해 줘
/compact API 설계 결정 사항만 남기고 나머지는 제거해 줘

커스텀 지시를 주면 AI가 어떤 정보를 우선적으로 보존할지 결정하는 데 도움이 된다.

4.3 /context - 현재 컨텍스트 사용량 확인

/context

동작:

• 현재 컨텍스트 윈도우의 사용량을 시각적으로 보여준다.
• 어떤 요소가 얼마나 차지하고 있는지 그리드 형태로 표시한다.

출력 예시:

Context Window Usage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
System prompt     ████░░░░░░░░░░░░░░░░  12%
CLAUDE.md         ██░░░░░░░░░░░░░░░░░░   5%
MCP tools         █░░░░░░░░░░░░░░░░░░░   3%
Conversation      ████████████░░░░░░░░  45%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total                                   65%

활용:

• 작업 시작 전에 현재 여유 공간을 확인
• /compact 실행 전후로 비교하여 압축 효과 확인
• 어떤 요소가 컨텍스트를 많이 차지하는지 파악하여 최적화

4.4 명령어 비교 요약

명령어	목적	대화 기록	컨텍스트 효과	사용 빈도
/clear	완전 초기화	전부 삭제	0%로 리셋	작업 전환 시
/compact	압축	요약으로 교체	40~60%로 축소	작업 도중
/context	확인	변경 없음	영향 없음	수시로

---

5. 컨텍스트 관리 워크플로우

5.1 실전 워크플로우 플로차트

5.2 워크플로우 규칙 정리

규칙 1: 새 기능 시작 시 반드시 /clear

기능 A 완료 → /clear → 기능 B 시작

이전 기능의 맥락이 남아있으면 새 기능 개발에 간섭한다. 변수명, 설계 방향, 파일 구조 등이 이전 작업에 끌려갈 수 있다.

규칙 2: 주기적으로 /context 확인

5~10번 대화마다 /context 확인

체감상 "대화가 좀 길어졌다" 싶으면 확인한다. 습관처럼 실행하는 것이 좋다.

규칙 3: 60%를 넘으면 /compact

/context → 65% → /compact → /context → 42% → 작업 계속

/compact 후에 반드시 /context로 압축 효과를 확인한다.

규칙 4: /clear 전에 중요 정보 보존

/clear 전 체크리스트:
  [ ] 합의한 설계 결정을 CLAUDE.md에 기록했는가?
  [ ] 현재 진행 상황을 어딘가에 메모했는가?
  [ ] 미완료 작업이 있다면 다음 프롬프트를 미리 준비했는가?

---

6. 토큰 효율적 사용 4가지 전략

전략 1: 프롬프트 최적화 - 범위를 제한하는 표현 사용

AI에게 요청할 때 범위를 명확히 제한하면 토큰을 크게 절약할 수 있다.

나쁜 예 (범위가 넓음 = 토큰 낭비):

이 프로젝트의 인증 시스템을 개선해 줘.

• AI가 프로젝트 전체를 탐색하고, 관련 파일을 모두 읽고, 긴 응답을 생성
• 탐색 과정에서 수많은 파일 내용이 컨텍스트에 적재됨

좋은 예 (범위가 좁음 = 토큰 절약):

src/auth/login.ts 파일의 validateToken 함수에서
만료 시간 검증 로직만 수정해 줘.
JWT 만료 시간을 1시간에서 30분으로 변경하는 것에 한해서만 수정.

• AI가 정확히 해당 파일, 해당 함수만 읽고 수정
• 최소한의 파일만 컨텍스트에 적재됨

범위 제한에 유용한 표현들:

표현	효과
"~만 수정해 줘"	수정 범위를 특정 부분으로 한정
"~에 한해서"	작업 영역을 명시적으로 제한
"~파일의 ~함수만"	정확한 위치 지정
"다른 파일은 건드리지 마"	불필요한 탐색 방지
"설명 없이 코드만"	응답 토큰 절약
"3줄 이내로 요약"	출력 길이 제한

전략 2: 적절한 모델 선택

모든 작업에 가장 비싼 모델을 쓸 필요가 없다. 작업 성격에 따라 모델을 바꾸면 토큰 효율이 극대화된다.

작업 유형	추천 모델	이유
간단한 질문, 문법 확인	Haiku	빠르고 저렴, 단순 작업에 충분
코드 포맷팅, 린팅 수정	Haiku	패턴 기반 작업은 작은 모델로 충분
일반적인 코드 구현	Sonnet	비용 대비 성능 최적, 대부분의 작업에 적합
복잡한 디버깅	Sonnet/Opus	문제 복잡도에 따라 선택
시스템 설계, 아키텍처	Opus	깊은 사고와 장기적 관점이 필요
대규모 코드베이스 분석	Sonnet[1m]/Opus[1m]	많은 파일을 한꺼번에 분석할 수 있음

모델 전환 방법:

/model sonnet       # Sonnet으로 전환
/model opus         # Opus로 전환
/model haiku        # Haiku로 전환
/model sonnet[1m]   # Sonnet 1M으로 전환 (베타)
/model opus[1m]     # Opus 1M으로 전환 (베타)

전략 3: 컨텍스트 관리 - /clear, /compact 적극 활용

5장에서 설명한 워크플로우를 습관화하는 것이 핵심이다.

작업 단위 분리 패턴:

세션 1: 데이터 모델 설계 → 완료 → /clear
세션 2: API 엔드포인트 구현 → 완료 → /clear
세션 3: 프론트엔드 연동 → 완료 → /clear
세션 4: 테스트 작성 → 완료 → /clear

하나의 긴 세션에서 모든 작업을 하는 것보다, 작업 단위로 세션을 분리하면:

• 각 세션에서 AI가 최적의 성능을 발휘
• 맥락 혼동으로 인한 재작업이 줄어듦
• 결과적으로 총 토큰 사용량이 감소

전략 4: 불필요한 요소 줄이기

컨텍스트 윈도우는 대화만 차지하는 것이 아니다. 다양한 요소가 공간을 먹는다.

점검 대상:

• 안 쓰는 MCP 서버 제거: MCP 서버가 등록되어 있으면, 해당 서버가 제공하는 모든 도구(tool)의 정의가 컨텍스트에 포함된다. 현재 프로젝트에서 사용하지 않는 MCP 서버는 꺼 두자.

• 서브에이전트 최소화: 서브에이전트 정의도 컨텍스트를 차지한다. 필요한 것만 활성화하자.

• CLAUDE.md 간결하게 유지: CLAUDE.md가 방대하면 매 요청마다 그만큼의 토큰을 소비한다. 핵심 지침만 남기고 불필요한 내용은 삭제하자.

• 출력 스타일 조정: 시스템 프롬프트에서 "자세한 설명과 함께" 같은 지시를 주면 AI가 긴 응답을 생성한다. 필요에 따라 "간결하게 응답"을 지시하면 응답 토큰을 줄일 수 있다.

---

7. 컨텍스트를 차지하는 요소들

컨텍스트 윈도우는 대화 내용만으로 채워지는 것이 아니다. 다양한 요소가 시작부터 공간을 점유한다.

7.1 구성 요소별 상세

(1) 대화 기록 - 가장 큰 비중

대화가 진행될수록 누적되며, 전체 컨텍스트의 대부분을 차지하게 된다. 2장에서 설명한 누적 메커니즘에 의해 기하급수적으로 증가한다.

관리법: /clear와 /compact로 관리

(2) CLAUDE.md 파일 내용

프로젝트 루트의 CLAUDE.md, 홈 디렉터리의 ~/.claude/CLAUDE.md, 그리고 하위 디렉터리의 CLAUDE.md가 모두 자동으로 로드된다.

관리법:

• 꼭 필요한 지침만 작성
• 중복 내용 제거
• 너무 긴 예시 코드는 별도 파일로 분리하고 필요할 때만 참조

(3) MCP 서버 도구 정의

MCP(Model Context Protocol) 서버를 연결하면, 해당 서버가 제공하는 모든 도구의 이름, 설명, 파라미터 정의가 컨텍스트에 포함된다. MCP 서버 하나당 수십 개의 도구가 있을 수 있으며, 이들 정의만으로도 상당한 토큰을 소비한다.

관리법:

• 현재 프로젝트에서 사용하지 않는 MCP 서버는 비활성화
• 필요할 때만 활성화하고, 작업이 끝나면 다시 비활성화

(4) 서브에이전트 정의

서브에이전트가 설정되어 있으면 해당 정의(이름, 설명, 역할, 도구 접근 권한 등)가 컨텍스트에 포함된다.

관리법: 필요한 서브에이전트만 활성화

(5) 시스템 프롬프트 (출력 스타일 포함)

Claude Code가 기본적으로 가지고 있는 시스템 프롬프트와, 사용자가 설정한 출력 스타일 등이 포함된다. 이 부분은 사용자가 직접 줄일 수 없지만, 존재한다는 것을 인지하고 있어야 한다.

(6) 참조한 파일 내용

AI가 작업 도중 읽어들인 파일 내용이 컨텍스트에 적재된다. 큰 파일을 여러 개 읽으면 그만큼 컨텍스트가 빠르게 차오른다.

관리법:

• 프롬프트에서 파일과 함수를 특정하여 불필요한 파일 탐색을 방지
• "이 파일만 봐 줘"와 같은 표현으로 범위 한정

7.2 실제 시나리오: 동일 작업, 다른 토큰 소비

비효율적 시나리오:

사용자: "이 프로젝트에서 버그를 찾아줘"
→ AI가 프로젝트 전체를 탐색 (수십 개 파일 읽기)
→ 참조 파일 내용만으로 컨텍스트 40% 소비
→ 대화 진행할 여유 공간이 부족

효율적 시나리오:

사용자: "src/auth/session.ts의 refreshToken 함수에서
       토큰 만료 후에도 세션이 유지되는 버그가 있어.
       이 함수만 확인해 줘."
→ AI가 정확히 1개 파일만 읽기
→ 참조 파일 내용이 컨텍스트 2% 수준
→ 대화 진행할 여유 공간이 충분

---

8. 핵심 메시지: AI 네이티브 개발 = 컨텍스트 싸움

8.1 본질

AI 네이티브 개발에서 가장 중요한 능력은 한정된 컨텍스트 윈도우 안에서 꼭 필요한 컨텍스트만 정확하게 전달하는 것이다.

코드를 얼마나 잘 짜는지, 프레임워크를 얼마나 잘 아는지보다, AI에게 올바른 맥락을 효율적으로 전달하는 능력이 생산성을 결정한다.

8.2 모델이 좋아져도 본질은 동일

현재:  200K 토큰 윈도우  →  컨텍스트 관리 필수
미래:  1M, 10M 토큰 윈도우  →  여전히 컨텍스트 관리 필수

왜 윈도우가 커져도 동일한가?

1. 프로젝트도 커진다: 윈도우가 커지면 더 큰 프로젝트를 다루게 되므로, 상대적 부족함은 동일하다.
2. 비용 문제: 윈도우가 크면 토큰 사용량도 비례하여 증가하므로, 효율적 사용의 필요성은 동일하다.
3. 성능 저하 특성: 모델이 아무리 좋아져도, 정보가 많을수록 핵심을 놓칠 확률은 올라간다. 이는 "건초더미에서 바늘 찾기(needle in a haystack)" 문제와 같다.
4. 정보 밀도: 불필요한 정보가 많으면 필요한 정보의 영향력이 희석된다. 적은 양의 정확한 정보가 대량의 두루뭉술한 정보보다 항상 낫다.

8.3 컨텍스트 관리 체크리스트

매일의 작업에서 아래 체크리스트를 참고하자.

작업 시작 전:

• [ ] /context로 현재 사용량 확인
• [ ] 이전 작업과 무관한 새 작업이면 /clear 실행
• [ ] CLAUDE.md에 불필요한 내용이 없는지 점검

작업 진행 중:

• [ ] 프롬프트에 파일명, 함수명 등 구체적 위치 명시
• [ ] 범위를 제한하는 표현("~만", "~에 한해서") 사용
• [ ] 5~10번 대화마다 /context 확인
• [ ] 60%를 넘으면 /compact 실행

작업 전환 시:

• [ ] 중요 결정 사항을 CLAUDE.md에 기록
• [ ] /clear 실행
• [ ] 새 작업에 필요한 맥락만 첫 프롬프트에 포함

세션 종료 전:

• [ ] 미완료 작업 상태를 기록
• [ ] 다음 세션에서 이어갈 수 있도록 프롬프트 초안 준비

---

요약

개념	핵심 내용
토큰	AI가 텍스트를 처리하는 최소 단위. 한국어는 영어 대비 ~2배 토큰 소비
토큰 누적	매 요청마다 이전 대화 전체가 함께 전송되어 누적됨
컨텍스트 윈도우	AI가 한 번에 처리할 수 있는 토큰 최대 용량 (200K~1M)
60% 규칙	컨텍스트가 60%를 넘으면 성능 저하가 시작됨
/clear	대화를 완전 초기화. 새 작업 시작 시 필수
/compact	대화를 요약 압축. 작업 이어갈 때 유용
/context	현재 컨텍스트 사용량 시각적 확인
효율화 전략	범위 제한, 모델 선택, 컨텍스트 관리, 불필요 요소 제거
본질	AI 네이티브 개발 = 한정된 컨텍스트 안에서의 정보 전달 싸움

---

다음 챕터: 05. 메모리 관리 - CLAUDE.md 파일로 프로젝트 지침을 체계적으로 관리하는 방법을 다룬다. 컨텍스트 윈도우의 한계를 극복하기 위해 "영속적 메모리"를 활용하는 전략이다.