Claude Code를 효율적으로 활용하려면 모델이 정보를 처리하는 방식과 컨텍스트 한계를 명확히 이해해야 합니다. Claude Code를 사용하다가 점점 응답이 느려지거나 엉뚱한 대답을 들어본 경험은 모두에게 있을 겁니다. 이는 모델이 텍스트를 인식하는 최소 단위인 '토큰'의 한계에 도달했기 때문일 확률이 높습니다. 이 글에서는 Claude Code가 어떻게 컨텍스트를 관리하는지 파악하고, 불필요한 토큰 낭비를 막는 토큰 최적화 실전 가이드를 알려 드리겠습니다.

토큰의 기본 개념 이해하기

Claude Code를 사용할 때 가장 먼저 이해해야 할 개념은 바로 토큰입니다.

토큰이란

AI 모델은 텍스트를 그대로 처리하지 않고, 내부의 토크나이저(tokenizer)라는 변환 프로그램을 사용해 단어, 구두점, 기호, 공백 등을 잘게 나눈 최소 단위로 변환합니다. 이 단위를 토큰(token)이라 합니다.

다음 예시를 보면 토큰의 개념을 직관적으로 이해할 수 있습니다.

영어: "Claude Code is an excellent tool." → ["Claude", " Code", " is", " an", " excellent", " tool", "."] → 약 6~7토큰
한글: "Claude Code는 훌륭한 도구입니다." → ["Claude", " Code", "는", " 훌륭", "한", " 도구", "입니다", "."] → 조사, 형용사, 어미가 분리되어 약 8~10토큰

한글은 조사, 어미, 복합어 구조 때문에 영어보다 토큰 수가 더 많아지는 경향이 있습니다. 따라서 짧고 명확한 문장일수록 토큰 효율이 좋아지고 모델이 컨텍스트를 더 정확히 파악할 수 있습니다.

입력 토큰과 출력 토큰

Claude Code에서 토큰은 크게 두 종류로 구분합니다.

1. 입력 토큰

사용자가 모델에 전달하는 모든 텍스트를 입력 토큰(input token)에 포함합니다. 이때, 사용자가 보지 못하는 내부 정보까지 모두 토큰으로 계산합니다.

사용자의 요청 메시지
세션 대화 이력
CLAUDE.md
시스템 프롬프트 예 모델 동작 규칙
도구 정의 예 MCP 스키마 등
@로 참조한 코드나 문서

2. 출력 토큰

Claude가 새로 생성하는 모든 텍스트를 출력 토큰(output token)으로 계산합니다.

Claude의 응답 문장
자동 생성된 코드
분석 결과문
수정된 diff 내용

입력과 출력의 합계가 총 사용 토큰이며, 이는 곧 비용과 응답 속도에 직접적인 영향을 줍니다.

컨텍스트에 포함되는 실제 구성 요소

Claude Code는 입력된 문자 수만 세지 않습니다. 실제로는 사용자의 요청 문장뿐 아니라, 그 요청을 처리하 데 필요한 대화 이력, CLAUDE.md, 도구 정의, 참조된 파일 내용까지 모두 토크나이저를 통해 토큰으로 변환합니다. 따라서 한 번 요청을 보내면 겉으로 보이는 텍스트보다 훨씬 많은 정보가 모델에 전달되고, 이 모든 요소가 입력 토큰으로 계산됩니다.

따라서 다음 요청처럼 매우 짧아도 실제 입력 토큰은 수만 개일 수 있습니다.

이 점을 이해해야 컨텍스트를 과도하게 사용하는 상황을 예방할 수 있습니다.

토큰 사용량 확인 방법

Claude Code에서는 다음과 같은 방식으로 토큰 수를 확인할 수 있습니다.

1. /context 명령으로 컨텍스트 사용량 확인하기

대화형 세션에서 /context 명령을 실행하면 시스템 프롬프트, 시스템 도구, 메모리 파일, 메시지 등을 포함해 현재 세션의 모든 컴포넌트별 토큰 사용량을 표시합니다.

2. 로그 파일에서 직접 확인하기

Claude Code는 모든 대화 기록을 ~/.claude/projects/ 폴더에 JSONL 형식으로 저장합니다. 각 메시지의 usage 필드에 포함된 input_tokens, output_tokens 값을 확인할 수 있습니다.

3. 웹 기반 토큰 계산기 사용하기

별도의 웹 도구를 이용해 텍스트를 직접 입력하고 토큰 수를 확인할 수도 있습니다.

token-counter.app/anthropic: 웹 브라우저에서 직접 토큰 계산
claude-tokenizer.vercel.app: Anthropic의 token counting API 기반 토큰 계산기

토큰 사용 최적화 전략

Claude Code를 효율적으로 활용하려면 토큰을 어디에서, 어떻게 소비하는지 이해해 불필요한 낭비를 줄이는 것이 중요합니다.

CLAUDE.md를 간결하게 유지하기

CLAUDE.md는 요청마다 함께 로드되는 핵심 문서입니다. 내용이 길수록 컨텍스트 초기 비용이 불필요하게 증가하므로 다음 원칙을 적용해 문서를 최소화하는 것이 좋습니다.

1. 비효율적인 예시(약 5,000토큰)

프로젝트 설명을 장황하게 서술
기술 스택을 여러 문단으로 중복 표현
코딩 규칙을 장문으로 상세 기술

2. 개선된 예시(약 700토큰)

기술 스택, 폴더 구조, 핵심 규칙만 간단히 요약
불필요한 문장 제거, 헤딩/리스트 중심 재구성

최적화 전략은 다음과 같습니다.

“이 프로젝트는…”과 같은 서술형 문장 제거
헤딩, 리스트, 테이블을 사용해 구조화
규칙은 최소 단위로 축약
코드 예시는 과도하게 포함하지 않기

이 원칙만 적용해도 문서 크기를 80~90%까지 줄일 수 있습니다.

분산 메모리 구조

CLAUDE.md가 지나치게 길어지는 경우, 내용을 여러 보조 문서로 분리한 뒤 필요할 때만 불러오는 방식이 효과적입니다. 이 방식은 Claude가 기본 컨텍스트를 가볍게 유지한 채, 요청 시 필요한 문서만 추가로 읽도록 합니다.

예시 구조

⊥ CLAUDE.md

⊥ docs/api-guide.md

⊥ docs/db-guide.md

⊥ docs/deploy-guide.md

이런 구조를 사용하면 다음과 같은 장점이 있습니다.

토큰 절약: 기본 컨텍스트가 가벼워져 Claude가 불필요한 정보를 동시에 유지하지 않아도 됨
유지보수 용이: 문서가 기능별, 역할별로 나뉘어 있어 특정 영역만 수정하거나 업데이트하기가 수월함
가독성 향상: 한 파일에 모든 내용을 담지 않아 필요한 정보를 더 빠르고 정확하게 찾을 수 있음

MCP 도구는 필요한 것만 사용하기

MCP(Model Context Protocol) 서버를 설치하면 각 도구 정의가 컨텍스트에 로드됩니다.

GitHub, Web Search, Database, Playwright 등을 모두 활성화하면 최대 1만 토큰 이상이 시스템 영역에서 추가될 수 있습니다. 최적화 전략은 다음과 같습니다.

현재 작업에 필요한 MCP만 활성화 (예) 프런트엔드 작업에는 Playwright만, 백엔드 작업에는 Database MCP만
프로젝트별 .config/claude/config.json 파일에서 불필요한 MCP 비활성화
정기적으로 MCP 목록을 점검해 미사용 항목 제거

이렇게 관리하면 컨텍스트 공간 5~7% 정도를 즉시 확보할 수 있습니다.

대화 메시지 관리하기

대화 이력은 컨텍스트에서 가장 빠르게 증가하는 영역입니다. 다음 세 가지 원칙만 지켜도 토큰 낭비를 크게 줄일 수 있습니다.

1. 불필요한 왕복 줄이기

utils.py 파일을 읽어줘. → 잘 읽었어? → 수정해줘. (×)
utils.py의 get_user 함수를 읽고 성능을 개선해줘. (○)

2. 비슷한 요청은 하나의 배치로 묶기

Header, Footer, Sidebar를 각각 다크 모드를 적용해줘. (×)
components 폴더의 Header, Footer, Sidebar에 공통으로 다크 모드를 적용해줘. (○)

3. 모호한 요청 피하기

로그인 기능을 수정해줘. (×)
.auth.py에서 JWT 토큰 만료 시간을 1시간에서 24시간으로 늘려줘. (○)

명확하고 구조화된 요청이 가장 강력한 토큰 절약 도구입니다.

파일 참조는 필요한 부분만

@ 기호를 사용해 파일을 참조하면 내용 전체가 컨텍스트에 포함되므로 큰 파일을 무조건 통째로 읽는 방식은 비효율적입니다. 권장하는 방식은 다음과 같습니다.

500줄 이하: 전체 참조 가능
500~2,000줄: 필요한 구간만 지정
2,000줄 이상: 함수나 클래스 단위로 분리

세션 길이 관리하기

한 세션이 길어질수록 컨텍스트가 누적되어 속도와 비용이 모두 증가합니다. 따라서 기능 단위로 세션을 나누거나 멀티 세션 방식으로 작업을 분리하면 효율이 높아집니다.

1. 기능 단위로 세션 구분

인증 기능 구현: /compact 실행
프로필 기능 구현: /compact 실행
완전히 다른 프로젝트: /clear로 초기화

2. 멀티 터미널 전략

터미널 1: 백엔드 전용
터미널 2: 프런트엔드 전용
터미널 3: 문서화 및 배포

서로 다른 작업을 물리적으로 분리하면 컨텍스트 충돌을 방지하고 메모리 효율이 증가하는 장점이 있습니다.

실전 최적화 흐름

Claude Code의 토큰, 컨텍스트 최적화 전략을 단계별로 요약하면 다음과 같습니다.

1.큰 작업은 먼저 계획부터 요청해 접근 범위 정리하기
아키텍처 변경, 인증 로직 교체처럼 범위가 큰 작업은 곧바로 수정하지 말고 먼저 계획을 요청해 변경 파일, 순서, 리스크를 정리합니다.

2. /context로 사용량 점검하기
/context 명령으로 현재 세션의 토큰 사용량을 확인합니다. 예를 들어 200K토큰 컨텍스트 윈도우에서 기본 세션이 약 20K토큰(10%)을 사용하고, 나머지 180K토큰을 실제 작업에 사용할 수 있습니다. 컨텍스트는 디스크 공간처럼 작업하면서 채워지므로 정기적으로 확인하면서 관리하는 것이 중요합니다.

3. 복잡한 작업의 문서화와 /clear 사용하기
대규모 작업의 경우 진행 상황을 마크다운 파일로 저장하게 한 뒤 /clear로 컨텍스트를 초기화하고, 새 세션에서 해당 파일을 읽어 작업을 이어가는 방식이 효과적입니다.

4. 프롬프트 캐싱으로 비용 절감하기
Claude Code는 자동으로 프롬프트 캐싱을 활성화해 반복되는 요청의 비용을 절감합니다. 캐시된 콘텐츠를 사용하면 기본 입력 토큰 가격의 10%만 부과되어 최대 90%의 비용을 절감하고 지연 시간을 85% 줄일 수 있습니다.

토큰 사용 최적화 전략은 Claude Code를 똑똑하게 쓰기 위한 첫걸음입니다. 현재 사용 흐름을 점검하고, 토큰 최적화 전략을 단계적으로 적용해 보시기 바랍니다.

이 글은 길벗에서 출간된 책 <AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법> 에서 발췌·편집한 글입니다. 원문은 [여기]에서 볼 수 있습니다.