컨텍스트와 토큰 관리
Claude Code를 잘 쓰는 사람과 못 쓰는 사람의 가장 큰 차이는 "컨텍스트 관리"에서 갈립니다.
1. 컨텍스트란?
컨텍스트(context)는 Claude가 현재 답변을 만들기 위해 참고하는 "기억의 창"입니다. 시스템 프롬프트, CLAUDE.md, 내가 입력한 대화, 읽어들인 파일 내용, 도구·MCP 정보가 모두 여기에 들어갑니다.

그림은 컨텍스트 창 하나를 상자로 그린 것입니다. 아래 칸은 내가 아무것도 입력하기 전에 이미 들어 있는 것들입니다. 시스템 지시, CLAUDE.md, 자동 메모리, 사용할 수 있는 Skills의 이름·설명, MCP 도구 이름이 여기에 해당합니다. 그 위로 작업하면서 내 지시, 읽은 파일 내용, 명령 출력, Claude의 답이 차례로 쌓입니다. 터미널에 보이지 않는 파일 내용과 출력도 모두 이 상자를 채운다는 점이 중요합니다. 상자가 거의 차면 Claude Code는 대화를 요약해 자리를 비웁니다(자동 압축).
컨텍스트 한도는 모델·제공자·설정에 따라 다릅니다. 현재 주요 모델은 1M 토큰을 지원하며, 실제 세션의 한도는 /context로 확인합니다.
2. 컨텍스트가 길수록 똑똑해지지 않습니다
많은 분이 "대화를 많이 할수록 Claude가 내 프로젝트를 더 잘 이해하겠지"라고 생각합니다. 사실은 반대인 경우가 많습니다.
컨텍스트가 길어지고 불필요한 내용이 쌓일수록, 모델은 정작 중요한 정보를 놓치고 답변 품질이 떨어질 수 있습니다. 연구에서도 긴 입력에서 성능이 떨어지는 모습이 확인됐습니다. NoLiMa(2025)는 질문과 정답 문장이 같은 낱말을 공유하지 않는 시험에서, 입력이 32K 토큰으로 길어지자 시험한 모델 13개 가운데 11개의 점수가 짧은 입력일 때의 절반 아래로 떨어졌다고 보고했습니다. 'Lost in the Middle'(2023)은 필요한 정보가 긴 입력의 한가운데 있을 때 특히 잘 활용하지 못한다고 보고했습니다. 두 연구 모두 당시 모델을 시험한 결과라 지금 모델에서의 정도는 다를 수 있습니다.
- 관련 연구(NoLiMa): https://arxiv.org/abs/2502.05167
- 관련 연구(Lost in the Middle): https://arxiv.org/abs/2307.03172
필요한 자료와 무관한 출력이 섞이지 않도록 작업 단위를 정하고, 필요한 때 대화를 정리합니다.
길어진 대화는 품질만이 아니라 사용량에도 영향을 줍니다. Claude Code는 요청을 보낼 때마다 지금까지의 대화 전체를 함께 보냅니다. Claude가 도구를 한 번 쓸 때마다 그 결과를 실은 요청이 또 나갑니다.

이 그래프는 측정값이 아니라 가정으로 계산한 예입니다. 세션이 2만 토큰으로 시작하고, 한 번 주고받을 때마다 6천 토큰씩 늘고, 10번마다 관련 없는 일로 넘어가 /clear한다고 보았습니다. 왼쪽은 요청 한 번에 싣는 양입니다. 한 세션으로 계속하면(주황) 40번째에는 요청 하나가 25만 토큰을 넘게 싣고, 10번마다 /clear하면(파랑) 7만 4천 토큰을 넘지 않는 톱니 모양이 됩니다. 오른쪽은 그 양을 모두 더한 것으로, 주고받은 횟수는 같아도 합계가 약 2.9배 차이가 납니다. 한 줄짜리 질문도 긴 세션에서는 앞의 대화를 통째로 다시 읽기 때문입니다. 도구를 쓸 때마다 나가는 요청은 뺀 단순한 계산이라 실제 요청 수는 이보다 많고, 세션이 길수록 차이는 더 벌어집니다.
실제로는 반복해서 보내는 앞부분에 프롬프트 캐시가 적용돼 요금은 이보다 훨씬 적게 듭니다. 그래도 공식 문서는 긴 세션이 사용량 한도를 예상보다 빨리 쓰는 첫째 이유로 이 '긴 컨텍스트'를 꼽고, 잠시 자리를 비운 뒤 캐시 유지 시간이 지나 첫 메시지를 보내면 전체를 다시 처리한다고 설명합니다. 관련 없는 일로 넘어갈 때 /clear가 가장 값싼 정리입니다.
- 사용량이 긴 세션에서 늘어나는 이유: https://code.claude.com/docs/en/costs
3. 컨텍스트 관리 3대 명령어
| 명령어 | 동작 | 언제 쓰나 |
|---|---|---|
/context | 현재 토큰 분포를 시각화 | 컨텍스트 상태 점검 |
/clear | 대화를 완전히 초기화 | 새 작업을 시작할 때 |
/compact | 대화를 요약본으로 바꿔 축소 | 이어가야 하는 작업의 컨텍스트를 줄일 때 |
3.1 /context: 상태 점검
/context로 지금 컨텍스트에 무엇이 얼마나 차 있는지 확인하세요. 내가 입력한 메시지뿐 아니라 시스템 프롬프트, 도구, CLAUDE.md, Skills가 차지하는 양도 함께 보입니다. 아무 지시도 하지 않은 새 세션에서 실행한 결과를 줄여 옮기면 다음과 같습니다(Claude Code 2.1.322, Opus 5.5).
Tokens: 14k / 1m (1%)
| Category | Tokens | Percentage |
|---|---|---|
| System prompt | 2k | 0.2% |
| System tools | 9.5k | 1.0% |
| Memory files | 446 | 0.0% |
| Skills | 2.1k | 0.2% |
| Free space | 953k | 95.3% |
| Autocompact buffer | 33k | 3.3% |
아무것도 입력하지 않았는데도 1M 중 1만 4천 토큰이 이미 차 있습니다. 시스템 지시와 도구 목록(System prompt·System tools), CLAUDE.md(Memory files), Skills 설명이 위 그림의 아래 칸에 해당합니다. 맨 아래 Autocompact buffer는 비워 두는 자리입니다. 컨텍스트가 이 자리에 닿기 전에 Claude Code가 대화를 자동으로 압축하므로, 실제로 채울 수 있는 빈자리는 Free space만큼입니다. MCP 서버나 Skills를 많이 붙이고 CLAUDE.md를 길게 쓸수록 이 시작량이 늘어납니다. 점유율 하나만으로 비우기보다, 다음 작업에 불필요한 내용이 쌓였는지 함께 판단합니다.
3.2 /clear: 새 작업의 시작
새로운 주제나 작업으로 넘어갈 때는 /clear로 비우는 것이 기본입니다. 파일은 그대로 유지되니 안심하세요. "작업 하나 = 세션 하나" 정도로 생각하면 좋습니다.
3.3 /compact: 요약해서 이어가기
작업을 이어가야 하는데 대화가 길어졌다면 /compact로 요약합니다. 대화를 요약본으로 바꿔 토큰을 줄이는 대신, 요약에서 빠진 세부는 사라집니다. 하루 작업을 마칠 때 /compact로 요약해두고, 다음 날 그 요약을 바탕으로 이어가면 효율적입니다.
/compact API 변경 내용 위주로처럼 무엇을 남길지 함께 적으면 요약이 그 부분을 지킵니다. 자주 쓰는 기준은 CLAUDE.md에 # Compact instructions 같은 절로 적어 둘 수 있습니다. 직접 하지 않아도 컨텍스트가 한도에 가까워지면 Claude Code가 자동으로 압축합니다. 다만 자동 압축은 무엇이 중요한지 짐작해 요약하므로, 대화 초반에 말로만 준 자세한 지시는 사라질 수 있습니다. 계속 지켜야 하는 규칙은 대화가 아니라 CLAUDE.md에 둡니다.

그림은 같은 긴 대화(왼쪽)에 두 명령을 썼을 때 컨텍스트 창에 무엇이 남는지 비교한 것입니다. /clear(가운데)는 대화를 모두 비우고 세션을 시작할 때 읽는 것(시스템 지시·CLAUDE.md·자동 메모리·Skills 설명)만 다시 남깁니다. 비용이 들지 않습니다. /compact(오른쪽)는 대화를 구조화된 요약 하나로 바꾸고, 프로젝트 CLAUDE.md와 자동 메모리를 디스크에서 다시 넣고, 최근에 읽거나 고친 파일을 최대 다섯 개까지 다시 읽습니다. 요약을 만드는 과정에서 긴 대화를 한 번 읽으므로 /compact 자체도 큰 요청입니다.
- 압축 뒤에 남는 것: https://code.claude.com/docs/en/context-window
4. 토큰 절약 실전 팁
Claude Code는 사용량(토큰)에 따라 한도가 소진됩니다. 다음 방법으로 토큰을 아낄 수 있습니다.
| 방법 | 명령/동작 | 효과 |
|---|---|---|
| 가벼운 모델로 내리기 | /model로 Sonnet·Haiku 전환 | 단순 작업의 사용량 절감(2장 '요금제와 모델 선택') |
| 노력 수준 낮추기 | /effort low 또는 medium | 단순 작업에서 생각(출력 토큰) 줄이기 |
| 대화 요약 | /compact | 긴 대화를 축소 |
| 세션 초기화 | /clear | 불필요한 대화 제거 |
| 곁가지 질문 | /btw 질문 | 대화에 남기지 않고 잠깐 묻기 |
| 명령 직접 입력 | ! 셸 모드 | 자연어로 명령을 만드는 과정 생략, 출력은 컨텍스트에 포함 |
| 파일 콕 집기 | @파일명 | 엉뚱한 파일 탐색 방지 |
| CLAUDE.md 다이어트 | 200줄 아래, 특정 작업 지침은 Skill로 | 매 요청마다 싣는 양 줄이기(7장) |
| 긴 출력 맡기기 | Subagent에 테스트·로그·문서 조사 위임 | 긴 출력은 서브에이전트 컨텍스트에 두고 요약만 받기(8장) |
| 안 쓰는 MCP 끄기 | /mcp에서 비활성화 | 도구 목록이 차지하는 자리 줄이기(9장) |
마지막 수정