Claude Code 토큰 절약 가이드

왜 토큰이 빨리 소모될까?

메시지를 보낼 때마다 이전 대화 전체(프롬프트, 응답, 도구 실행 결과 전부)가 처음부터 다시 전송되어 처리된다. 즉 토큰 사용량은 "내가 방금 입력한 양"이 아니라 세션이 시작된 이후 오간 모든 내용의 누적량이다. 특히 Claude가 도구를 써서 파일을 읽거나 diff를 가져올 때마다 그 결과 전체가 대화 기록에 그대로 끼어들기 때문에, 무심코 큰 파일을 여러 개 읽게 하면 순식간에 컨텍스트가 불어난다.

💡 아래 명령어들은 모두 Claude Code를 실행 중인 터미널(또는 VS Code 통합 터미널) 안에서, 그냥 타이핑하고 Enter를 누르면 된다.

01세션 관리 02CLAUDE.md 다이어트 03작업에 맞는 모델 선택 04MCP 서버 오버헤드 05훅·스킬로 전처리 위임 06서브에이전트 위임 07확장 사고 조정 08구체적인 프롬프트 09Plan Mode + 조기 수정 10코드 인텔리전스 플러그인 11에이전트 팀 주의사항 12서드파티 커뮤니티 도구 ＋사용량 확인 방법 ＋참고 자료

세션 관리 — 컨텍스트를 주기적으로 비우기

Claude Code는 세션이 길어질수록 이전에 시도했다 실패한 접근, 이미 해결된 에러, 더 이상 필요 없는 파일 내용까지 계속 컨텍스트에 들고 있는다. 아침에 시작한 세션을 점심 이후까지 그대로 이어가면, 실제로 지금 필요한 정보보다 "죽은 무게(dead weight)"가 더 많아질 수 있다. /clear는 이 무게를 완전히 털어내는 것이고, /compact는 버리지 않고 핵심만 요약해서 남기는 것이다. 둘의 용도가 다르므로 상황에 맞게 골라 써야 한다.

어떻게 하나요?

지금 하던 작업과 무관한 새 작업을 시작하려면, 터미널에 /clear만 입력하고 Enter. 대화가 완전히 초기화된다.

나중에 지금 세션으로 돌아오고 싶다면, /clear 치기 전에 먼저 /rename 로그인버그수정처럼 세션 이름을 붙여두자. 나중에 /resume을 입력하면 이름으로 이전 세션 목록이 뜨고 골라서 돌아갈 수 있다.

대화를 없애지 않고 압축만 하고 싶다면(예: 작업 단계 하나를 끝냈을 때) /compact만 입력. 무엇을 남길지 지정하고 싶으면 /compact 코드 변경사항과 테스트 결과 위주로 남겨줘처럼 뒤에 지시문을 붙인다.

팁: 이미 Claude가 앞의 내용을 헷갈려하기 시작한 뒤(반응형)가 아니라, 기능 하나를 완성했을 때(능동형) 실행하는 게 더 좋은 요약을 만든다.

지금 컨텍스트에 뭐가 얼마나 차 있는지 궁금하면 /context를 입력. 필요 없는 파일이 계속 남아있는 게 보이면 그때 /clear를 고려하면 된다.

현재 세션 토큰/비용이 궁금하면 /usage를 입력.

CLAUDE.md는 짧고 핵심만

CLAUDE.md는 프로젝트 루트에 두는 파일로, Claude Code가 세션을 시작할 때마다 자동으로 읽어서 컨텍스트에 넣는 "표준 지침서"다. 매번 "이 프로젝트는 pnpm을 쓰고, 테스트는 이렇게 돌리고..."라고 설명하는 수고를 덜어준다는 장점이 있지만, 문제는 이 파일이 세션 내내 항상 켜져 있다는 점이다. 2,000토큰짜리 CLAUDE.md라면 메시지를 2번 보내든 200번 보내든 매번 2,000토큰이 청구된다. 즉 CLAUDE.md에 넣은 모든 문장은 세션당 고정 비용이 되므로, 자주 필요하지 않은 상세 절차까지 다 넣어두면 매 턴마다 불필요한 비용을 계속 내는 셈이 된다.

어떻게 하나요?

프로젝트 폴더의 최상위(루트)에서 /init을 입력하면 Claude가 프로젝트를 분석해서 CLAUDE.md 파일을 자동으로 만들어준다.

파일이 너무 길어지지 않게 관리하자. 목표는 200줄 이하, 이상적으로는 300~600토큰 수준이다. 아래처럼 "항상 참인 규칙"만 남긴다.

# 프로젝트 규칙
- 패키지 매니저: pnpm
- 테스트: `pnpm test`로 실행, 커밋 전 항상 통과 확인
- 스타일: 함수형 컴포넌트만 사용, class 컴포넌트 금지
- 커밋 메시지는 Conventional Commits 형식 사용

"PR 리뷰할 때는 이렇게 해라", "DB 마이그레이션은 이 순서로" 같은 특정 상황에서만 필요한 상세 절차는 CLAUDE.md에 넣지 말고 05번 항목에서 설명할 스킬(Skill)로 옮긴다. CLAUDE.md는 매 세션 항상 로드되지만, 스킬은 필요할 때만 불려온다.

이미 CLAUDE.md가 길어졌다면, 열어서 "항상 참인 사실"과 "특정 작업 절차"를 구분해보고, 후자를 스킬로 옮기는 식으로 다이어트하면 된다.

작업에 맞는 모델 선택 (자동화: Fable 오케스트레이션)

Claude Code에서는 Fable, Opus, Sonnet, Haiku 중 하나를 골라 쓸 수 있는데, 모델이 클수록(Fable) 추론 능력은 좋지만 같은 작업이라도 토큰당 단가가 높다. 문제는 "변수 이름 하나 바꿔줘" 같은 단순 작업에도 별생각 없이 가장 비싼 모델을 계속 쓰는 습관이다. 반대로 복잡한 아키텍처 설계처럼 정말 깊은 추론이 필요한 작업에 값싼 모델을 쓰면 시행착오가 늘어나 오히려 전체 토큰이 더 들 수도 있다. 즉 "무조건 싼 모델"이 아니라 작업 난이도에 맞는 모델을 고르는 게 핵심이다.

이 부분을 자동화 해주기 위해 Fable을 기획 및 검토를 담당하는 관리자(Planner/Advisor)로 두고 실제 작업(Executor/Worker)은 상대적으로 저렴한 모델이 수행하는 모델 오케스트레이션(Orchestration) 구조를 구축하는 것이다. 자세한 셋팅 방법은 아래의 링크를 클릭하면 볼 수 있다.

성공지식백과의 Fable 5 오케스트레이션 가이드 에서는 '워커(Worker)'로 Opus나 Haiku를 사용하여 토큰을 90% 절약하였다고 하고,
Use 60% Less Fable Tokens With This Orchestrator Setup 에서는 '워크(Worker)'로 Codex를 사용하여 60% 토큰을 절약하였다고 한다.
더 보기: Claude Code에서 Fable 오케스트레이션으로 토큰 절약하기

어떻게 하나요?

세션 중간에 모델을 바꾸려면 /model을 입력하면 선택 메뉴가 뜬다. 목록에서 원하는 모델(예: Sonnet)을 고르면 그 시점부터 적용된다.

매번 수동으로 바꾸기 귀찮다면 /config에서 기본 모델을 아예 지정해둘 수 있다.

판단 기준(경험칙):

변수명 일괄 변경, 오타 수정, 간단한 버그 하나 고치기 → Sonnet (또는 더 단순하면 Haiku)
아키텍처 설계, 여러 파일에 걸친 복잡한 리팩터링, 다단계 추론이 필요한 문제 → Opus

커스텀 서브에이전트를 쓴다면(06번 항목 참고), 서브에이전트 정의 파일(.claude/agents/이름.md)의 YAML 앞부분에 model: haiku처럼 명시해서 그 서브에이전트만 저렴한 모델로 고정할 수 있다.

MCP 서버 오버헤드 줄이기

MCP(Model Context Protocol) 서버는 Claude Code가 Jira, Slack, 데이터베이스 같은 외부 서비스와 연동할 수 있게 해주는 확장 도구다. 각 MCP 서버는 자신이 제공하는 도구 목록을 Claude에게 알려줘야 하고, 실제로 그 도구를 호출하면 그 결과(때로는 수천 줄짜리 JSON)가 통째로 대화 기록에 들어간다. 편리하다고 이것저것 다 연결해두면, 쓰지도 않는 서버의 존재 자체와 가끔 호출될 때 딸려오는 방대한 응답이 컨텍스트를 조용히 갉아먹는다. 반면 gh, aws 같은 커맨드라인 도구는 Claude가 그냥 셸 명령으로 실행하는 것이라 도구 목록을 따로 등록할 필요가 없어 더 가볍다.

어떻게 하나요?

지금 연결된 MCP 서버 목록을 보려면 /mcp를 입력한다. 최근에 안 쓰는 서버가 보이면 그 자리에서 비활성화하면 된다.

GitHub, AWS, GCP 작업처럼 CLI 도구(gh, aws, gcloud 등)가 이미 설치돼 있다면, 같은 작업이라도 MCP 서버보다 CLI 명령을 그대로 실행하게 하는 편이 컨텍스트를 덜 먹는다.

실제로 얼마나 차지하는지 궁금하면 /context로 확인해서, MCP 관련 항목이 크게 나오는 서버부터 정리하면 된다.

훅·스킬로 전처리 위임

훅(Hook)은 Claude가 어떤 결과를 "보기 전에" 자동으로 실행되는 스크립트다. 테스트를 돌리면 원래는 로그 수백~수천 줄이 그대로 컨텍스트에 들어가는데, 훅이 중간에서 실패한 부분만 걸러 전달하면 Claude는 필요한 정보만 받게 된다. 스킬(Skill)은 이것과 다르게, Claude에게 "이 프로젝트는 이런 구조고, 이럴 땐 이렇게 해라"는 도메인 지식을 미리 문서로 준비해두는 것이다. CLAUDE.md와 달리 스킬은 관련된 요청이 들어왔을 때만 그때 불러와지므로, 평소에는 컨텍스트를 전혀 차지하지 않는다.

스킬 만들기 (예: 반복되는 설명을 아껴주는 방법)

터미널에서 스킬 폴더를 만든다.

mkdir -p ~/.claude/skills/커밋메시지작성

프로젝트 전체 팀과 공유하고 싶다면 ~/.claude/skills/ 대신 프로젝트 루트의 .claude/skills/에 만들면 된다.

그 폴더 안에 SKILL.md 파일을 만들고 아래처럼 작성한다.

---
name: 커밋메시지작성
description: 커밋 메시지를 작성하거나 변경사항을 정리할 때 사용. Conventional Commits 형식 적용.
---
## 절차
1. `git diff HEAD` 결과를 확인한다
2. 변경사항을 두세 문장으로 요약한다
3. feat/fix/docs 등 Conventional Commits 형식으로 메시지를 작성한다

저장하면 끝. 이후 "커밋 메시지 좀 써줘" 같은 요청을 하면 Claude가 이 스킬의 description을 보고 자동으로 찾아서 그때만 본문을 읽어온다.

훅으로 시끄러운 출력 걸러내기 (예: 테스트 실패만 보여주기)

훅 스크립트를 둘 폴더를 만든다.

mkdir -p ~/.claude/hooks

~/.claude/hooks/filter-test-output.sh 파일을 만들고 실행 권한을 준다.

chmod +x ~/.claude/hooks/filter-test-output.sh

프로젝트의 settings.json에 아래처럼 등록하면, 테스트 명령을 실행할 때마다 Claude가 전체 로그 대신 실패한 부분만 받게 된다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }
        ]
      }
    ]
  }
}

처음이라 스크립트 작성이 부담스럽다면, 직접 짜지 말고 Claude에게 "테스트 실패한 부분만 보여주는 훅을 만들어줘"라고 요청해도 된다.

서브에이전트에게 시끄러운 작업 위임

서브에이전트는 메인 대화와 완전히 분리된 자기만의 컨텍스트 창을 가진 "보조 Claude"다. 예를 들어 "인증 로직이 어떻게 동작하는지 조사해줘"라고 서브에이전트에게 맡기면, 그 서브에이전트가 파일 열 개를 읽고 뒤지는 과정 전체는 서브에이전트 자신의 컨텍스트에만 쌓이고, 메인 대화창에는 마지막 요약 결과 하나만 돌아온다. 로그 분석, 대규모 코드 탐색처럼 "결과만 필요하고 과정은 필요 없는" 작업에 특히 효과적이다.

어떻게 하나요? (설치·설정 없이 바로 되는 방법)

가장 쉬운 방법은 그냥 대화로 요청하는 것이다. 예: "서브에이전트를 시켜서 이 코드베이스에서 인증 로직이 어떻게 동작하는지 조사해줘"라고 말하면 Claude가 알아서 별도 컨텍스트에서 탐색하고, 대화창에는 요약만 가져온다.
서브에이전트가 시간이 걸리는 작업을 하는 동안 다른 걸 하고 싶다면 Ctrl+B로 백그라운드로 보내고, /tasks로 진행 상황을 확인할 수 있다.

자주 반복하는 역할이면 아예 만들어두기

.claude/agents/코드리뷰어.md 파일을 직접 만들거나, Claude에게 "코드 리뷰용 서브에이전트를 만들어줘"라고 요청해서 초안을 받는다.

파일 예시:

---
name: 코드리뷰어
description: 코드 품질과 베스트 프랙티스를 검토할 때 사용
tools: Read, Glob, Grep
model: sonnet
---
당신은 코드 리뷰어입니다. 호출되면 코드를 분석해 품질, 보안, 베스트 프랙티스에 대한 구체적인 피드백을 제공하세요.

이후 "코드 리뷰어 에이전트로 이 변경사항 검토해줘"라고 이름을 지정해 부르거나, 상황이 맞으면 Claude가 자동으로 델리게이션한다.

확장 사고(Extended Thinking) 조정

확장 사고는 Claude가 답을 내놓기 전에 내부적으로 더 오래, 더 깊이 "생각"하게 하는 기능으로, 복잡한 계획·추론 작업의 품질을 크게 끌어올려주기 때문에 기본적으로 켜져 있다. 문제는 이 "생각 과정"도 눈에는 안 보이지만 출력 토큰으로 과금된다는 점이다. 단순한 작업에까지 매번 이 예산이 쓰이면 누적 비용이 커진다. 반대로 정말 복잡한 설계 작업에서 사고를 꺼버리면 결과 품질이 떨어져서 재작업 비용이 더 늘 수 있으니, 작업 난이도에 맞춰 조절하는 게 핵심이다.

어떻게 하나요?

지금 사고 강도를 낮추고 싶다면 /effort를 입력해 레벨을 선택하거나, /model에서 effort 옵션을 조정한다.

아예 확장 사고를 끄고 싶다면 /config에 들어가서 thinking 옵션을 끈다.

완전히 끄기보다 예산만 줄이고 싶다면, 터미널에서 환경변수를 설정한다.

export MAX_THINKING_TOKENS=8000

매번 치기 귀찮으면 ~/.bashrc나 ~/.zshrc에 넣어두면 터미널 열 때마다 자동 적용된다.

판단 기준: "이 변수 이름 오타 고쳐줘" 같은 단순 작업엔 낮은 effort로 충분하고, "이 시스템을 어떻게 리팩터링할지 설계해줘" 같은 작업엔 기본값(높은 effort)을 유지하는 게 낫다.

프롬프트를 구체적으로 쓰기

Claude는 요청이 모호할수록 스스로 범위를 넓혀서 탐색한다. "이 코드베이스 좀 개선해줘"라는 요청을 받으면, 어디부터 손봐야 할지 판단하기 위해 여러 폴더와 파일을 순서대로 열어보게 된다. 이 탐색 과정에서 읽은 파일 내용은 전부 컨텍스트에 쌓인다. 반대로 범위가 명확하면, Claude는 딱 필요한 파일만 열어보고 바로 작업에 들어갈 수 있다.

어떻게 하나요? (설정이 필요 없는, 습관만 바꾸면 되는 항목)

✕막연한 요청: "이 코드베이스 좀 개선해줘" → Claude가 전체를 훑어보느라 파일을 많이 읽는다.

✓구체적인 요청: "auth.ts의 login 함수에 이메일 형식 검증을 추가해줘" → 딱 필요한 파일만 열어서 작업한다.

요청할 때 파일 경로나 함수 이름을 알고 있다면 직접 언급해주는 것만으로도 탐색 비용이 크게 줄어든다.

복잡한 작업은 Plan Mode + 조기 수정으로

토큰 낭비의 큰 원인 중 하나는 "잘못된 방향으로 한참 작업한 뒤에야 알아채는 것"이다. 코드를 이미 여러 파일에 걸쳐 고쳐놓은 다음에 방향이 틀렸다는 걸 알면, 되돌리고 다시 설명하고 다시 시키는 과정에서 토큰이 두 배, 세 배로 든다. Plan Mode는 Claude가 곧바로 코드를 고치지 않고 먼저 "이렇게 하겠습니다"라는 계획만 세워서 보여주고, 사용자가 승인한 뒤에야 실제 변경을 시작하게 해서 이 문제를 예방한다.

어떻게 하나요?

복잡한 작업을 시키기 전에 Shift+Tab을 눌러 Plan Mode로 들어간다. Claude가 코드를 바로 고치지 않고 먼저 코드베이스를 탐색한 뒤 계획을 제시하고, 승인하면 그때 실제 작업을 시작한다.

작업 도중 Claude가 엉뚱한 방향으로 가는 게 보이면 Escape를 눌러 즉시 멈춘다.

되돌리고 싶으면 /rewind를 입력하거나 Escape를 두 번 눌러서 이전 체크포인트로 대화와 코드를 되돌릴 수 있다.

요청할 때 "이 테스트가 통과해야 해", 스크린샷, 기대 출력 예시를 같이 주면 Claude가 스스로 검증하면서 작업해서 추가 수정 왕복이 줄어든다.

큰 작업은 한 번에 다 시키지 말고, 파일 하나 작성 → 테스트 → 다음 파일, 이런 식으로 잘라서 진행하자.

코드 인텔리전스 플러그인 설치 (타입 언어 사용자)

Claude가 코드 안에서 "이 함수가 어디서 정의됐는지" 알아내려면 보통 grep으로 검색한 다음, 후보 파일들을 하나씩 열어서 확인하는 방식을 쓴다. 코드 인텔리전스 플러그인은 IDE가 쓰는 것과 같은 LSP(Language Server Protocol) 기술을 Claude Code에 연결해서, "정의로 이동" 같은 요청을 grep 없이 정확한 한 번의 조회로 끝내게 해준다. 편집 후 타입 오류도 컴파일 없이 자동으로 알려준다.

어떻게 하나요? (예: TypeScript 프로젝트 기준)

먼저 언어 서버(LSP)가 컴퓨터에 설치돼 있어야 한다. TypeScript라면:

npm install -g typescript-language-server typescript

Claude Code 안에서 /plugin을 입력하면 플러그인 브라우저가 뜬다. 여기서 자기 언어에 맞는 공식 LSP 플러그인을 찾아 설치하거나, 명령을 바로 입력해도 된다.

/plugin install typescript-lsp@claude-plugins-official

Python은 pyright-lsp, Go는 gopls 등 언어별로 이름이 다르니 /plugin 메뉴에서 검색해서 고르는 게 가장 안전하다.

설치 후 세션을 한 번 재시작하면, 이후로는 Claude가 정확한 탐색을 사용하고, 편집 후 타입 오류도 자동으로 알려준다.

필요한 언어 하나만 설치하자. 안 쓰는 언어의 플러그인까지 여러 개 설치하면 오히려 시작 비용이 늘어난다.

에이전트 팀(Agent Teams) 사용 시 주의

에이전트 팀은 서브에이전트(06번)를 한 단계 더 확장한 기능으로, 여러 개의 독립된 Claude Code 인스턴스가 동시에 팀으로 협업한다. 서브에이전트가 "결과만 돌려주고 사라지는 일회성 심부름꾼"이라면, 에이전트 팀은 "각자 자기 컨텍스트를 유지한 채 계속 대화하는 동료들"에 가깝다. 팀원 각각이 독립된 세션이라 팀원 수만큼 토큰 비용이 그대로 곱해진다. 특히 팀원이 Plan Mode로 돌아가면 일반 세션 대비 약 7배까지 토큰을 더 쓸 수 있다.

어떻게 하나요?

에이전트 팀은 기본적으로 꺼져 있다. 켜려면 환경변수를 설정한다.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

또는 settings.json에 같은 값을 넣어도 된다.

팀을 쓸 때는:

팀원 모델은 Sonnet으로 (Opus로 여러 명 돌리면 비용이 배로 뛴다)
팀 인원은 최소한으로만 (팀원마다 자기 컨텍스트 창을 따로 가지므로 인원수에 비례해서 토큰이 든다)
팀원에게 주는 초기 지시문(스폰 프롬프트)은 짧고 명확하게
작업이 끝난 팀원은 바로 종료시키기

특히 팀원이 Plan Mode로 작업하는 경우 일반 세션보다 약 7배 더 많은 토큰을 쓸 수 있다는 점을 기억하고, 작업을 작고 독립적인 단위로 쪼개서 맡기자.

서드파티 커뮤니티 도구 (선택 사항)

공식 기능은 아니지만, 커뮤니티 개발자들이 "컨텍스트를 작게 유지한다"는 같은 원리를 응용해서 만든 보조 도구들이 여럿 있다. 공식 도구가 아니므로 설치 전 저장소 신뢰도와 최근 업데이트 여부를 직접 확인하는 게 안전하다.

CLI 출력 압축 도구 (예: RTK)

grep 결과처럼 중복이 많은 셸 출력을 감싸서 중복 경로·반복 줄을 제거한 뒤 Claude에게 전달한다.

구조화된 프로젝트 컨텍스트 도구 (예: repomix)

저장소 전체를 그대로 넘기는 대신, 생성 코드·락파일·빌드 산출물을 뺀 정제된 스냅샷을 만들어 대신 넘겨준다. npx repomix 형태로 실행해보자.

실시간 토큰 모니터링 플러그인 (예: claude-hud)

터미널에 지금 토큰 수·모델·비용을 실시간으로 표시해서 컨텍스트가 과도하게 쌓이기 전에 알아챌 수 있게 해준다.

⚠️ 처음이라면 위 도구들을 굳이 다 설치할 필요는 없다. 01~11번의 기본 습관만 잡아도 대부분의 낭비는 줄어든다. 그 이후에도 부족하다 싶을 때 하나씩 시도해보자.

＋

사용량 확인 방법

설명

방법을 적용했다고 느낌만으로 판단하면 실제로 절약이 됐는지 알기 어렵다. API로 직접 과금되는 경우와, Pro/Max 같은 구독제로 쓰는 경우 확인 경로가 다르다.

어떻게 하나요?

API 과금 사용자: 세션 종료 시 /cost로 토큰 수와 예상 비용 확인, 세션 간 누적 이력은 Claude Console(console.anthropic.com)의 Usage 페이지에서 확인.
구독제(Pro/Max) 사용자: /usage로 플랜 한도 대비 사용량, 스킬·서브에이전트·플러그인·MCP 서버별 사용 비중(%)을 확인할 수 있다.
방법을 하나 적용하기 전후로 같은 작업을 돌려 수치를 비교하는 것이 가장 확실한 검증 방법이다.

참고 자료

세부 명령어(특히 플러그인/스킬 이름, 환경변수)는 Claude Code 버전에 따라 조금씩 달라질 수 있다. 명령이 안 먹히면 /help로 현재 버전에서 지원하는 명령 목록을 확인해보자.

이 블로그 검색

해피 테크로그