컨텍스트 윈도우 관리 · /clear·/compact·/context

앞 글 「에이전틱 루프의 동작 원리」에서 모든 도구 결과가 한 공간에 쌓인다고 했습니다. 그 공간이 컨텍스트 윈도우이고, 이 글은 그것을 다스리는 세 명령 /context, /clear, /compact를 다룹니다. 읽고 나면 지금 세션이 왜 느려졌는지 진단하고, 지울지 압축할지를 망설임 없이 고를 수 있습니다. 다음 글 「내장 도구 이해하기」는 컨텍스트를 채우는 주체인 도구들을 하나씩 살펴봅니다.

핵심 요약

• 표준 컨텍스트 윈도우는 20만 토큰이며, Sonnet 5는 기본 100만 토큰으로 동작합니다. 크기가 커도 채우는 방식과 압축 원리는 같습니다.
• 세션 시작 전에 시스템 프롬프트, CLAUDE.md, 자동 메모리, 스킬 설명, MCP 도구 이름이 먼저 들어갑니다. 그 위에 파일 읽기와 명령 출력이 쌓입니다.
• /context는 색상 그리드로 사용량을 보여 주고, /clear는 대화를 비우되 이전 세션은 저장하며, /compact는 대화를 구조화된 요약으로 바꿉니다.
• 압축 뒤 CLAUDE.md와 자동 메모리는 다시 주입되지만, 경로 범위 규칙과 하위 폴더 CLAUDE.md는 해당 파일을 다시 읽을 때까지 사라집니다.
• 자동 압축은 기본으로 켜져 있고(autoCompactEnabled), 임계값은 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE로 낮출 수만 있습니다.

컨텍스트에는 무엇이 들어가나

컨텍스트 윈도우는 Claude가 이 세션에 대해 아는 전부입니다. 공식 문서의 컨텍스트 시뮬레이션은 세션을 20만 토큰 기준으로 재생하는데, 사용자가 아무것도 입력하기 전에 이미 아래 항목이 로드됩니다.

그 다음부터는 루프가 돌 때마다 내 요청, 읽은 파일 본문, .claude/rules/의 경로 범위 규칙(해당 경로 파일을 읽을 때 자동 로드), 검색 결과, 편집 diff, 훅이 additionalContext로 돌려준 텍스트, 테스트 출력, Claude의 응답이 차례로 추가됩니다. 터미널에는 "Read auth.ts" 한 줄로 보여도 파일 2,400토큰이 통째로 들어가는 식입니다.

컨텍스트를 잡아먹는 주범

경험상, 그리고 공식 비용 문서가 지목하는 주범은 다음과 같습니다.

1. 큰 파일 읽기와 긴 명령 출력: 로그 파일 통째 읽기, 테스트 전체 출력. Bash 도구는 3만 자를 넘는 출력을 파일로 저장하고 미리보기만 넣어 주지만 그 아래까지는 그대로 들어갑니다.
2. 관련 없는 작업을 한 세션에서 이어 가기: 오래된 대화는 이후 모든 메시지에서 토큰을 낭비합니다.
3. 비대한 CLAUDE.md: 세션 시작마다 로드되므로 특정 워크플로우 지침은 스킬로 옮기고 200줄 이하로 유지하라는 것이 공식 권장입니다.
4. 이미지: 스크린샷 한 장이 텍스트 수천 토큰에 해당할 수 있습니다.
5. 모호한 요청: "이 코드베이스 개선해 줘"는 광범위한 스캔을 유발합니다. 우리 5주차 교재의 표현대로 "모호한 요청 + 긴 대화 + 대량 수정 = 토큰 급증"입니다.

MCP 도구 정의는 기본적으로 지연 로드되므로 예전만큼 큰 주범은 아닙니다. 다만 안 쓰는 서버는 /mcp에서 비활성화하고, gh·aws 같은 CLI가 있으면 MCP보다 CLI가 컨텍스트 면에서 유리하다는 점은 기억해 둡니다. 우리 6주차의 MCP 10항 체크리스트는 비용뿐 아니라 컨텍스트 부담까지 걸러 주는 장치입니다.

/context 로 사용량 확인하기

/context는 현재 컨텍스트 사용량을 색상 그리드로 시각화하고, 컨텍스트를 많이 쓰는 도구, 메모리 비대, 용량 경고에 대한 최적화 제안을 함께 보여 줍니다. /context all을 입력하면 항목별 분석을 전체 화면으로 펼칩니다. 상태줄에 컨텍스트 사용률을 상시 표시하도록 /statusline으로 구성할 수도 있습니다.

언제 확인하나

• 세션을 시작하자마자 한 번: 내 CLAUDE.md·메모리·MCP가 시작 컨텍스트를 얼마나 먹는지 기준선을 잡습니다.
• 큰 조사나 대량 수정이 끝난 뒤: 다음 작업을 이 세션에서 이어 갈지 결정할 재료가 됩니다.
• 응답이 느려지거나 이전 지시를 잊은 것 같을 때: 원인이 컨텍스트인지 먼저 확인합니다.
• 우리 5주차 교재처럼 상태줄에 세션 시간(session:320m)을 띄워 두었다면, 시간이 길어진 만큼 컨텍스트도 함께 의심합니다.

/clear 는 무엇을 지우고 무엇을 남기나

/clear(별칭 /reset, /new)는 빈 컨텍스트로 새 대화를 시작합니다. 지워지는 것은 대화 기록과 그 안의 파일 내용·명령 출력이고, 입력 기록(위쪽 화살표로 부르는 이전 프롬프트)도 초기화됩니다. 남는 것은 두 가지입니다. 첫째, 시작 시 로드되는 항목(CLAUDE.md, 자동 메모리, 스킬, MCP)은 새 대화에서 그대로 다시 들어갑니다. 둘째, 지워진 이전 대화는 디스크에 저장되어 /resume으로 돌아갈 수 있고, 같은 프로세스 안에서는 되감기 메뉴 맨 위의 /resume <session-id> (이전 세션) 항목으로도 재개할 수 있습니다(v2.1.191 이상).

/clear를 써야 할 네 가지 타이밍

1. 관련 없는 새 작업으로 넘어갈 때. 공식 비용 문서가 첫 번째로 꼽는 습관입니다. 지우기 전에 /rename으로 이름을 붙여 두면 나중에 찾기 쉽습니다.
2. 잘못된 방향으로 오래 진행해 대화에 오답이 많이 쌓였을 때. 요약해 봤자 오답이 요약될 뿐입니다.
3. 큰 파일이나 로그를 읽은 직후 그 내용이 더는 필요 없을 때.
4. 플랜 모드에서 계획을 승인하며 새로 시작하고 싶을 때. showClearContextOnPlanAccept를 켜면 승인 화면에서 컨텍스트 지우기 옵션이 나옵니다.

/compact 는 무엇을 남기나

/compact는 지금까지의 대화를 구조화된 요약으로 바꿉니다. 공식 시뮬레이션이 설명하는 요약의 보존 항목은 사용자의 요청과 의도, 핵심 기술 개념, 살펴보거나 수정한 파일과 중요한 코드 조각, 오류와 해결 방법, 남은 작업, 현재 진행 중인 작업입니다. 반대로 도구 출력 원문과 중간 추론은 사라집니다. 압축 뒤 Claude Code는 최근에 수정한 파일 최대 다섯 개를 다시 읽고, 그 파일에 맞는 규칙을 다시 로드하며, 호출했던 스킬 본문을 다시 주입합니다.

토픽을 지정한 압축

/compact 뒤에 지시를 붙이면 요약의 초점을 정할 수 있습니다.

/compact 결제 게이트 수정 내역과 남은 QA 항목 위주로 남겨 줘

세션 전체에 같은 기준을 적용하려면 프로젝트 CLAUDE.md에 압축 지침 섹션을 둡니다.

# Compact instructions

압축할 때는 테스트 출력과 변경한 파일 목록을 우선 보존할 것

자동 컴팩트는 믿어도 되나

자동 압축은 autoCompactEnabled(기본 true)로 켜져 있고, 한계에 가까워지면 오래된 도구 출력을 먼저 비우고 필요하면 대화를 요약합니다. 임계값은 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE(1~100)로 낮출 수 있는데, 기본값보다 높이는 방향으로는 효과가 없습니다. 환경 변수 DISABLE_AUTO_COMPACT로 끌 수도 있습니다.

믿어도 되는 부분은 "세션이 끊기지 않는다"는 점입니다. 믿으면 안 되는 부분은 "무엇을 남길지"입니다. 자동 패스는 중요한 항목을 추측하지만, 내가 /compact에 초점을 주면 추측 대신 내 선택이 남습니다. 또 한 파일이나 한 출력이 너무 커서 요약 직후 다시 가득 차는 경우, 몇 번 시도 뒤 자동 압축이 멈추고 오류를 표시합니다. 이때는 큰 출력을 파일로 빼거나 서브에이전트로 넘겨야 합니다.

/clear·/compact·/context 사용 구분

망설여질 때의 판단 기준

• 다음 요청이 지금까지의 결정을 참조하는가: 예라면 /compact, 아니오라면 /clear.
• 지금 대화에 틀린 시도가 많이 섞였는가: 예라면 /clear. 틀린 과정은 요약해도 쓸모가 없습니다.
• 규칙을 대화로만 전달했는가: 어느 쪽이든 먼저 CLAUDE.md에 옮긴 뒤 실행합니다. 압축이든 지우기든 대화 속 지시는 보장되지 않습니다.
• 확신이 없으면 /rename으로 이름을 붙이고 /clear합니다. /resume으로 언제든 돌아올 수 있으니 잃는 것이 없습니다.

컨텍스트 오염이 일으키는 문제

컨텍스트 오염은 현재 작업과 무관하거나 이미 틀린 것으로 판명된 정보가 윈도우에 남아 판단을 흐리는 상태입니다. 자동 모드 문서는 압축이 대화 속 경계 지시("푸시하지 마")를 지울 수 있다고 경고합니다. 반대로 지워지지 않은 오래된 지시가 새 작업에 잘못 적용되기도 합니다. 우리 5주차 교재에서 "안 되는데 고쳐 줘"를 반복하며 전체를 갈아엎는 상황이 전형적인 오염 사례입니다.

세션이 길어졌을 때 나타나는 신호

• 방금 말한 제약을 다음 턴에서 잊습니다.
• 이미 실패한 방법을 다시 시도합니다.
• 응답 시작이 눈에 띄게 느려집니다. 컨텍스트가 클수록 매 요청의 입력이 큽니다.
• 압축 경고나 "Conversation compacted" 메시지가 자주 나타납니다.
• /context에서 도구 출력 비중이 압도적으로 큽니다.

세션을 가볍게 유지하는 실전 전략

1. 한 세션에 한 작업. 끝나면 /clear. 우리 교육연합이 모든 과정에서 강제하는 습관입니다.
2. 규칙은 CLAUDE.md에, 절차는 스킬에. CLAUDE.md는 200줄 이하로.
3. 조사와 로그 처리는 서브에이전트에 위임하고 요약만 받습니다.
4. 훅으로 전처리합니다. 테스트 출력을 실패 줄만 남기도록 PreToolUse 훅에서 걸러 주면 수만 토큰이 수백 토큰이 됩니다.
5. 요청을 구체적으로 씁니다. 파일 경로와 검증 기준을 적으면 스캔 범위가 줄어듭니다.
6. 모델을 나눠 씁니다. 6주차 교재의 4단계대로 계획·요약은 가벼운 모델, 구현은 강한 모델. 더 큰 윈도우가 정말 필요하면 opus[1m] 같은 확장 컨텍스트 변형을 고릅니다.

프롬프트 캐싱과의 관계

Claude Code는 시스템 프롬프트처럼 반복되는 내용에 프롬프트 캐싱을 자동 적용해 비용을 줄입니다. 캐시는 앞부분이 같을 때 효력이 있으므로, 세션 중간에 모델을 바꾸면 다음 응답이 캐시 없이 전체 기록을 다시 읽습니다(/model 선택기가 확인을 요구하는 이유입니다). /btw 같은 측면 질문과 프롬프트 제안은 부모 대화의 캐시를 재사용해 추가 비용이 적습니다. 요약하면 캐싱은 "같은 앞부분을 다시 보내는 비용"을 줄여 줄 뿐, 컨텍스트가 큰 것 자체를 싸게 만들지는 않습니다.

정리

• 컨텍스트는 시작 로드 항목 위에 도구 결과가 쌓이는 구조이며, 보이지 않는 토큰이 대부분입니다.
• /context로 진단하고, 같은 작업이면 /compact, 다른 작업이면 /clear가 기본 규칙입니다.
• 압축 뒤 CLAUDE.md·메모리는 돌아오지만 경로 규칙과 하위 CLAUDE.md는 파일을 다시 읽어야 돌아옵니다.
• 자동 압축은 연속성을 보장할 뿐 보존 항목을 보장하지 않으므로 초점 지시와 CLAUDE.md 압축 지침을 씁니다.
• 한 세션 한 작업, 규칙은 파일에, 조사는 서브에이전트에. 이 세 가지가 실전의 대부분입니다.

자주 묻는 질문