Claude Code를 잘 쓰는 사람과 못 쓰는 사람을 나누는 결정적 차이가 있습니다. 프롬프트 스킬도 아니고, 모델 선택도 아닙니다. 바로 컨텍스트 관리입니다.
컨텍스트는 컴퓨터의 RAM과 같습니다. 95%까지 채울 수 있지만, 그 마지막 5%는 스와핑과 가비지 컬렉션에 소모되어 실제 작업 공간이 없어집니다. Claude Code도 마찬가지입니다. 대화가 길어지면 초반 내용을 까먹거나 헷갈리기 시작합니다.
이 글에서는 왜 이런 일이 발생하고, 어떻게 관리해야 하는지, 그리고 리셋 전에 꼭 해야 할 것까지 정리합니다.
TL;DR
- 컨텍스트 윈도우는 Claude의 **작업 기억(Working Memory)**입니다
- 200k 토큰이 한계지만, 80~100k만 넘어도 품질이 떨어집니다
- 3~5개 작업마다 또는 100k 토큰 전에 리셋하세요
- 리셋 전에 HANDOFF.md 파일을 꼭 만들어두세요
- /compact 3번 후 /clear하는 패턴을 추천합니다
Anthropic 공식 권장사항
이건 "개인 경험담"이 아닙니다. Anthropic이 공식 블로그에서 명시적으로 권장하는 내용입니다.
"During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude. Use the /clear command frequently between tasks to reset the context window." — Anthropic Engineering Blog: Claude Code Best Practices
핵심:
- 긴 세션에서 컨텍스트가 불필요한 내용으로 채워집니다
- 이로 인해 성능이 저하되고 Claude가 산만해집니다
- 작업 사이에 /clear를 자주 사용하세요
왜 성능이 떨어지나?
Context Rot: 채워질수록 썩는다
Chroma의 연구에서 "Context Rot"라는 개념이 제시되었습니다. 컨텍스트 윈도우가 채워질수록 작업 난이도와 무관하게 성능이 떨어집니다.
"Research consistently shows that optimizing Claude's context window in 2025 involves context quality over quantity, with performance degrading substantially as models approach their limits." — Hyperdev
"LLM accuracy declines as the context window fills past 50%... effective context windows are probably 50-60% or even lesser." — Sankalp's Blog
RAM 비유: 왜 여유 공간이 필요한가
"Think of it like RAM on your computer. Sure, you can run programs until you hit 95% memory utilization. But that last 5% gets consumed by swapping, garbage collection, and system overhead—leaving nothing for actual computation. Your programs slow to a crawl despite having 'only' 95% utilization. LLMs work similarly. That 'free' context space isn't wasted—it's where reasoning happens." — Hyperdev
실제 증상
컨텍스트가 오염되면 이런 현상이 나타납니다:
- 초반 지시를 잊어버림: "아까 말한 컨벤션 왜 안 지켜?"
- 자기 모순: 방금 전 결정과 반대로 행동
- 환각(Hallucination): 없는 함수나 파일을 참조
- 품질 저하: 갑자기 코드가 엉성해짐
- 응답 속도 저하: 눈에 띄게 느려짐
"The pattern was frustrating: you'd be deep into a complex refactoring, making steady progress, then suddenly Claude Code would struggle. Responses would become generic, previous decisions would be forgotten, and code quality would noticeably degrade." — Hyperdev
200k 토큰인데 왜 100k에서 리셋하나?
이론적으로 Claude Code는 200k 토큰까지 쓸 수 있습니다. 하지만 실전에서는 80~100k만 넘어가도 품질이 떨어지기 시작합니다.
실제 사용 가능 공간
200k 전체를 대화에 쓸 수 있는 게 아닙니다:
┌─────────────────────────────────────────────────────┐
│ 컨텍스트 윈도우 (200K 토큰) │
├─────────────────────────────────────────────────────┤
│ 시스템 프롬프트 + 도구: ~15K │
│ MCP 도구 정의: 가변 (수천~수만) │
│ Auto-compact 예약: ~45K (22.5%) │
│ ───────────────────────────────────── │
│ 실제 대화/코드: ~140K (이론상) │
│ 유효 작업 공간: ~100K (현실적) │
└─────────────────────────────────────────────────────┘"Auto-compact is a feature that quietly consumes a massive amount of your context window before you even start coding, with some reports showing the autocompact buffer consuming 45k tokens—22.5% of your context window gone before writing a single line of code." — Hyperdev
75% 규칙
Claude Code는 내부적으로 75% 사용량에서 auto-compact를 트리거합니다. 이는 25%(50k 토큰)를 추론 공간으로 남겨두기 위함입니다.
"If Claude Code is indeed triggering compaction at 75% utilization rather than 90%+, that leaves 25% of the context window (50k tokens in a 200k window) free for reasoning." — Hyperdev
결론: 100k를 넘기 전에 리셋하는 게 시간 절약입니다. 아깝게 느껴져도 이게 결국 더 효율적입니다.
컨텍스트 관리 명령어: /compact vs /clear
/compact — 요약 압축
/compact
대화 기록을 요약해서 압축합니다. 핵심 결정사항은 보존하면서 토큰만 줄입니다.
특징:
- 작업 흐름이 끊기지 않음
- 중요한 정보는 유지
- 하지만 미묘한 컨텍스트가 손실될 수 있음
"Compacting is distinct from the /clear command. While /clear completely wipes out the chat history and starts a brand new conversation from scratch, /compact summarizes the conversation and preserves the essential nuances and key information." — Steve Kinney
사용 시점:
- 같은 작업을 계속하지만 컨텍스트가 70-85% 찼을 때
- 이전 결정사항을 유지하고 싶을 때
/clear — 완전 초기화
/clear
모든 대화 기록을 삭제하고 완전히 새로운 세션을 시작합니다.
특징:
- 깨끗한 상태로 시작
- 모든 컨텍스트 손실
- HANDOFF.md 없으면 위험
"Pro tip: use /clear often. Every time you start something new, clear the chat. You don't need all that history eating your tokens, and you definitely don't need Claude running compaction calls to summarize old conversations." — Builder.io
사용 시점:
- 작업 완료 후 다른 작업으로 전환할 때
- Claude가 이상하게 행동하거나 루프에 빠졌을 때
- 컨텍스트가 90% 이상 찼을 때
- 대화가 완전히 엉뚱한 방향으로 갔을 때
언제 뭘 쓸까?
상황 명령어 이유
| 컨텍스트 70-85%, 같은 작업 계속 | /compact | 결정사항 보존 |
| 컨텍스트 90%+, 작업 전환 | /clear | 깨끗한 시작 |
| Claude가 루프에 빠짐 | /clear | 오염된 컨텍스트 제거 |
| 이전 컨텍스트 50% 미만 관련 | /clear | 불필요한 정보 제거 |
"Use /compact when: Context 70-85%, same task continues, need to preserve decisions. Use /clear when: Context 90%+, task complete, switching context, conversation went off-track, context poisoning." — DeepWiki
추천 패턴: /compact 3번 후 /clear
제가 쓰는 패턴입니다:
작업 1-2: 자유롭게 작업
──────────────────────
[/compact] ← 70% 도달
──────────────────────
작업 3-4: 계속 작업
──────────────────────
[/compact] ← 다시 70% 도달
──────────────────────
작업 5: 계속 작업
──────────────────────
[/compact] ← 세 번째
──────────────────────
[HANDOFF.md 생성]
[/clear] ← 완전 리셋
──────────────────────
새 세션: HANDOFF.md 읽고 시작
왜 이 패턴인가?
"Compaction, we found, encourages long, meandering threads, in which you just compact once you run out of context window, stacking summary on top of summary. What we want to encourage are focused threads, because we think that's how agents yield the best results." — Amp
/compact를 반복하면 "요약의 요약"이 쌓이면서 정보가 점점 손실됩니다. 3번 정도 후에는 /clear로 깨끗하게 시작하는 게 좋습니다.
HANDOFF.md: 리셋 전에 꼭 만들어야 할 파일
컨텍스트를 리셋하기 전에 꼭 해야 할 일이 있습니다. HANDOFF.md 파일 만들기입니다.
왜 필요한가?
"AI sessions have limited context. When you switch tools, take a break, or hit a context limit, the next agent starts from scratch. Handoffs solve this by capturing: What you're trying to do, what's done, what's not, what failed (so the next agent doesn't repeat mistakes), key decisions and their rationale, exactly how to continue." — willseltzer/claude-handoff
HANDOFF.md 없이 /clear하면:
- 2시간치 작업 흐름을 다시 설명해야 함
- 이전에 실패한 접근법을 또 시도함
- 이미 내린 결정을 다시 논의함
"Creating a handoff takes 2-3 minutes. Re-establishing context without one takes 10-15 minutes. Every session." — DEV Community
HANDOFF.md 템플릿
# Handoff: [작업 제목]
**생성일**: 2026-01-20 14:30
**브랜치**: feature/user-auth
**상태**: 진행 중
## 목표
OAuth2를 이용한 사용자 인증 추가
## 완료된 작업
- [x] OAuth2 provider 설정
- [x] 로그인 엔드포인트 생성
- [x] JWT 토큰 발급 로직
## 남은 작업
- [ ] 토큰 갱신 로직 추가
- [ ] 로그아웃 처리
- [ ] 테스트 작성
## 실패한 접근법 (다시 시도하지 말 것!)
passport.js를 먼저 시도했으나 Express 미들웨어와 충돌.
`req.user`가 항상 undefined였음 - passport의 세션 미들웨어가
우리 커스텀 auth 체크 후에 실행되기 때문.
→ oauth4webapi로 전환 (fetch와 직접 작동, Express 건드리지 않음)
## 주요 결정사항
| 결정 | 이유 |
|------|------|
| passport 대신 oauth4webapi | 더 가볍고 미들웨어 충돌 없음 |
| refresh token은 httpOnly 쿠키에 저장 | localStorage보다 보안상 유리 |
## 현재 상태
**작동함**: 로그인 플로우에서 유효한 토큰 반환
**문제 있음**: /api/auth/refresh에서 500 에러 - `TokenExpiredError`
## 재개 지침
1. refresh.ts:42의 JWT verify 호출이 잘못된 시크릿 사용 중 - 수정 필요
2. 로그아웃: httpOnly 쿠키 클리어, POST /api/auth/logout
3. 전체 플로우 테스트 후 PR 생성
핵심 포인트
"Failed approaches are mandatory - This is the most valuable part. 'Tried X, it didn't work because Y' saves hours." — willseltzer/claude-handoff
HANDOFF.md에서 가장 중요한 부분은 **"실패한 접근법"**입니다. 이게 없으면 새 세션에서 같은 실수를 반복합니다.
/handoff 커맨드 만들기
매번 수동으로 작성하기 번거롭다면, 커스텀 커맨드를 만들 수 있습니다:
<!-- .claude/commands/handoff.md -->
Write or update a handoff document so the next agent with fresh
context can continue this work.
Include:
1. Goal and current progress
2. What worked and what didn't (with specific error messages)
3. Key decisions and their rationale
4. Current blockers or issues
5. Specific next steps
Save as HANDOFF.md in the project root.
"The way I do this is to ask Claude to write a handoff document before starting fresh. Something like: 'Put the rest of the plan in the HANDOFF.md. Explain what you have tried, what worked, what didn't work, so that the next agent with fresh context is able to just load that file and nothing else to get started.'" — ykdojo/claude-code-tips
/compact vs HANDOFF.md: 뭐가 다른가?
둘 다 컨텍스트를 보존하는 방법이지만 용도가 다릅니다:
구분 /compact HANDOFF.md
| 범위 | 세션 내 연속성 | 세션 간 연속성 |
| 저장 위치 | 컨텍스트 안 (휘발성) | 파일 (영구) |
| 제어권 | Claude가 요약 | 내가 검토 가능 |
| 손실 | 요약 과정에서 손실 가능 | 명시적으로 기록한 것만 보존 |
"Compacting is for within-session continuity. It summarizes to free up context space so you can keep working. Handoffs are for cross-session continuity. They're explicit documentation of what matters, in a format you control and can search." — DEV Community
Best Practice: 둘 다 사용하세요. /compact로 세션 내 연속성을 유지하고, /clear 전에는 HANDOFF.md로 세션 간 연속성을 확보하세요.
컨텍스트 사용량 기준
사용량 상태 권장 조치
| 0-50% | 🟢 양호 | 자유롭게 작업 |
| 50-70% | 🟡 주의 | 모니터링, HANDOFF.md 준비 |
| 70-85% | 🟠 경고 | /compact 실행 |
| 85-95% | 🔴 위험 | HANDOFF.md 작성 → /clear |
| 95%+ | ⛔ 한계 | 즉시 /clear (데이터 손실 위험) |
"I would do a handoff or compact when I reach total 60% if building something complex." — Sankalp's Blog
실전 워크플로우
패턴 1: 일반 작업
1. /context로 상태 확인
2. 작업 진행
3. 70% 도달 → /compact
4. 계속 작업
5. 다시 70% 또는 작업 전환 시점
→ HANDOFF.md 작성
→ /clear
6. 새 세션에서 @HANDOFF.md로 시작
패턴 2: 복잡한 장기 작업
1. Plan Mode로 계획 수립
2. 계획을 PLAN.md로 저장
3. /clear
4. @PLAN.md 읽고 1단계부터 실행
5. 각 단계 완료 시 PLAN.md 업데이트
6. 70% 도달 시마다:
- HANDOFF.md 작성 (현재 진행 상황)
- /clear
- @PLAN.md + @HANDOFF.md로 재개
"Often when the context window starts getting full or I feel the model is struggling with a complex task, I want to start a new conversation using /clear. I prefer to make Claude write what happened in current session before I kill it and start a new one." — Sankalp's Blog
CLAUDE.md vs HANDOFF.md
두 파일의 역할이 다릅니다:
구분 CLAUDE.md HANDOFF.md
| 성격 | 프로젝트 상수 | 세션 상태 |
| 수명 | 프로젝트 전체 | 한 작업 사이클 |
| 내용 | 코드 스타일, 빌드 명령, 아키텍처 | 진행 상황, 실패한 시도, 다음 단계 |
| 로딩 | 자동 (매 세션) | 수동 (@로 참조) |
# CLAUDE.md (프로젝트 상수)
- 기술 스택: React + Node.js + PostgreSQL
- 코드 스타일: 2-space indent, snake_case API
- 빌드 명령: pnpm dev, pnpm test
# HANDOFF.md (현재 작업 상태)
- 목표: OAuth2 인증 추가
- 완료: 로그인 엔드포인트
- 실패한 시도: passport.js (미들웨어 충돌)
- 다음 단계: 토큰 갱신 로직
체크리스트
세션 시작 시
- [ ] /context로 초기 사용량 확인
- [ ] HANDOFF.md가 있다면 @로 참조
- [ ] 불필요한 MCP 서버 비활성화
세션 진행 중
- [ ] 70% 도달하면 /compact 또는 HANDOFF.md 준비
- [ ] 100k 토큰 전에 리셋 고려
- [ ] Claude가 이상하게 행동하면 즉시 /clear
리셋 전
- [ ] ⚠️ HANDOFF.md 작성 (가장 중요!)
- [ ] 실패한 접근법 명시
- [ ] 다음 단계 구체적으로 기록
- [ ] /clear 실행
새 세션 시작
- [ ] @HANDOFF.md로 컨텍스트 복원
- [ ] "이 파일 읽고 이어서 진행해줘"
마무리
컨텍스트 관리는 Claude Code의 숨겨진 핵심 스킬입니다.
기억하세요:
- 컨텍스트는 채워질수록 썩습니다 (Context Rot)
- 200k가 한계지만 100k 전에 리셋하는 게 현명합니다
- /compact 3번 후 /clear 패턴을 추천합니다
- /clear 전에 HANDOFF.md는 필수입니다
- HANDOFF.md에서 **"실패한 접근법"**이 가장 중요합니다
Claude Code가 갑자기 이상해졌다고 느낄 때, 그건 Claude의 문제가 아닙니다. 컨텍스트가 오염된 것입니다. HANDOFF.md 작성하고 /clear 한 번이면 해결됩니다.
참고 자료
Anthropic 공식
- Claude Code Best Practices — Anthropic Engineering Blog
- Effective Context Engineering for AI Agents — Anthropic Engineering Blog
커뮤니티
- How I Use Every Claude Code Feature — Shrivu Shankar
- Claude Code: Keep the Context Clean — Arthur
- How Claude Code Got Better by Protecting More Context — Hyperdev
- Session Handoffs: Giving Your AI Assistant Memory That Actually Persists — DEV Community
- willseltzer/claude-handoff — GitHub
- ykdojo/claude-code-tips — GitHub
연구
- Context Rot — Chroma Research
'Programmer > AI' 카테고리의 다른 글
| Claude Code Hooks: 자동화로 실수를 원천 차단하기 (0) | 2026.01.21 |
|---|---|
| Claude Code 환경 설정: CLAUDE.md로 10분 투자해서 수 시간 절약하기 (0) | 2026.01.21 |
| Claude Code의 게임체인저: Plan Mode vs YOLO Mode (1) | 2026.01.20 |
| Claude Code는 시니어가 아니라 "똑똑한 주니어"다 (0) | 2026.01.20 |
| Claude Code가 느려졌다면? MCP 도구 관리가 답이다 (2) | 2026.01.20 |