클로드 코드(Claude Code) 토큰 절약, 직접 재 보니 먼저 바꿀 3가지

MCP 서버 3개를 붙이고 도구 검색을 끄자, 요청 한 번에 붙는 입력 토큰이 빈 프로젝트의 30,711개에서 60,225개로 늘었습니다. 같은 서버를 도구 검색이 켜진 기본값으로 붙이면 늘어난 양은 +383개였어요. 클로드 코드 토큰 절약을 고민하고 있다면 프롬프트를 다듬기 전에 이런 설정부터 보는 게 순서입니다. 아래는 클로드 코드 2.1.309에서 지침 파일 위치, 긴 문서 연결 방식, MCP 설정을 하나씩 바꿔 가며 잰 결과입니다.

무엇부터 바꾸면 효과가 클까요?

이번 시작 요청(파일이나 도구를 쓰지 않는 한 턴)에서 입력 토큰 차이가 컸던 순서는 이렇습니다. 실제 작업 중에 지침·문서를 나중에 읽어 들이는 비용은 포함하지 않았으므로, 아래 숫자는 세션 시작 시점의 증가량으로만 보는 편이 좋습니다.

1. MCP 도구 검색은 기본값(켬)으로 두기: 끄면 +29,514개, 켜 두면 +383개였습니다.
2. 긴 설계 문서는 붙이지 말고 경로만 적기: 붙이면 +2,028개, 경로만 적으면 +379개였습니다.
3. 루트 CLAUDE.md의 특정 작업용 지침은 하위 폴더 지침, 경로 지정 rules, 스킬로 옮기기: 루트에 두면 +1,616개, 옮기면 +1~+79개였습니다.

한국어 지침의 위치·형태 비교(루트 CLAUDE.md, src/CLAUDE.md, 경로 지정 rules, 스킬 본문)에는 같은 본문을 쓰고 두는 곳과 형태만 바꿨습니다. 영어 번역, 긴 문서 연결, MCP 설정은 별도 조건입니다. 숫자는 조건마다 3번 잰 값의 중앙값입니다.

도식출처: Claude Code 입력 토큰 측정

그렇다면 왜 이렇게 차이가 날까요? 가장 큰 MCP부터 공식 문서로 짚어 보겠습니다.

함께 읽을 글

• 클로드 코드(Claude Code) MCP 토큰, 도구 검색 켰을 때와 껐을 때 비교
• MCP 서버 직접 만들기, 클로드 코드에 붙여 토큰과 호출 확인
• 클로드 코드(Claude Code) 사용법, 같은 버그 수정을 3가지로 맡겨 보니

MCP 도구 검색을 끄면 왜 크게 늘까요?

비용 관리 문서를 보면 MCP 도구 정의는 기본적으로 미뤄서 불러옵니다. 그래서 Claude가 특정 도구를 실제로 쓰기 전까지는 도구 이름과 서버 안내만 컨텍스트에 들어가죠. 측정에서 두 조건 모두 MCP 도구는 24개였는데, 늘어난 토큰은 +383개와 +29,514개로 크게 갈렸습니다.

측정에서 도구 검색을 끈 조건은 환경 변수 ENABLE_TOOL_SEARCH=false로 실행했습니다. 셸 설정이나 실행 스크립트에 이 값을 넣어 두었다면 먼저 지워 보세요. 문서는 이 밖에도 두 가지를 권합니다.

• gh, aws, gcloud, sentry-cli처럼 CLI가 있는 도구는 MCP 서버보다 컨텍스트를 덜 씁니다. 도구마다 목록을 덧붙이지 않기 때문입니다.
• /mcp로 설정된 서버를 보고, 지금 쓰지 않는 서버는 꺼 두세요.

다음으로 효과가 컸던 건 지침을 어디에 두느냐였습니다.

지침 파일은 어디에 두면 덜 붙나요?

메모리 문서에 따르면 작업 폴더와 그 위 폴더의 CLAUDE.md는 세션을 시작할 때 불러옵니다. 반면 하위 폴더의 CLAUDE.md는 Claude가 그 폴더 안 파일을 읽거나 쓰거나 고칠 때 불러오죠. 그래서 루트에 둔 지침은 +1,616개였지만, src/CLAUDE.md로 옮기면 시작할 때 +1개만 붙었습니다.

경로를 지정한 rules도 비슷합니다. paths가 있는 rule은 맞는 파일에 Read, Write, Edit 도구를 쓸 때 불려 오고, 측정값은 +3개였어요. 문서의 예시는 이렇습니다.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

스킬은 부르거나 Claude가 관련 있다고 판단할 때만 불려 옵니다. 측정에서는 앞부분에 아래 이름과 설명을 붙였고, 스킬 수가 22개에서 23개로 늘며 +79개가 붙었습니다.

---
name: project-guide
description: 예약노트 저장소의 구조, 자주 쓰는 명령, 코딩 규칙. 이 저장소에서 코드를 고치거나 명령을 실행하기 전에 읽는다.
---

도식출처: 근거를 바탕으로 코드가 그린 도식

그럼 루트 CLAUDE.md는 비워 둬야 할까요? 그렇지는 않습니다. 비용 문서는 PR 리뷰나 DB 마이그레이션처럼 특정 작업용 지침은 스킬로 옮기고, CLAUDE.md는 꼭 필요한 내용만 담아 200줄 아래로 유지하라고 권합니다. 사람에게만 남길 메모는 블록 단위 HTML 주석(<!-- maintainer notes -->)으로 쓰면 컨텍스트에 넣기 전에 지워집니다.

예를 들어 결제 웹훅 규칙은 supabase/functions/ 쪽 rule로, 배포 절차는 스킬로 나누는 식입니다. 이렇게 나누면 화면 작업만 할 때 그 지침이 매 요청에 붙지 않습니다.

같은 지침을 영어로 옮겼을 때는 +1,126개로 한국어보다 적었습니다. 다만 이 측정만으로는 원인을 가를 수 없고, 다른 지침에서도 같은 차이가 날지는 알 수 없습니다. 영어 번역을 고민한다면 자기 지침으로 직접 재 보는 편이 확실합니다.

긴 설계 문서는 어떻게 연결할까요?

설계 문서를 @import로 CLAUDE.md에 붙이면 +2,028개, CLAUDE.md에 경로만 적으면 +379개였습니다. 필요한 문서를 매번 대화에 붙여 두고 있다면 경로만 적는 쪽부터 바꿔 보세요. 다만 Claude가 작업 중에 그 문서를 실제로 읽으면 그때 토큰이 들고, 이 측정에는 그 양이 들어 있지 않습니다.

클로드 코드 토큰 사용량 확인은 어떻게 하나요?

설정을 바꾼 뒤에는 실제로 줄었는지 확인해야겠죠. 공식 문서가 안내하는 방법은 이렇습니다.

• /usage: 맨 위 Session 블록에 현재 세션의 토큰 사용량이 자세히 나옵니다. 이 블록은 API 사용자용이라, Pro·Max 구독자에게 세션 비용 숫자는 청구와 상관이 없습니다. 구독자는 같은 화면에서 요금제 사용량 막대와 사용 내역을 봅니다.
• 요금제 사용 내역: Pro, Max, Team, Enterprise 요금제에서는 스킬·서브에이전트·플러그인·MCP 서버별 비중과 추천 변경을 보여 줍니다. 추천은 최근 사용량의 10% 이상인 항목에만 붙습니다. 하단에 f to fix 2 of 3 같은 안내가 보이면 f를 눌러 적용할 수 있고, 이 단축키는 v2.1.305 이상에서 됩니다.
• /context: 무엇이 컨텍스트 공간을 차지하는지 보여 줍니다.
• 상태 표시줄: 사용량을 계속 띄워 두도록 설정할 수 있습니다.

스피너 옆에 뜨는 토큰 수는 어떨까요? 이 숫자는 이번 턴이 만든 출력만 세기 때문에 입력 쪽 절약을 확인하는 용도로는 맞지 않습니다.

이 글처럼 요청 한 번의 입력 토큰을 직접 재 보려면 claude -p "Reply with only: OK" --output-format json처럼 출력 형식을 JSON으로 지정해 실행하세요. 결과 JSON에서 새 입력, 캐시 쓰기, 캐시 읽기 토큰을 더하면 됩니다.

측정 조건과 한계

• 환경: Claude Code 2.1.309, 모델 claude-opus-5-5, darwin arm64, Node.js v22.23.1
• 방법: 조건마다 새 임시 프로젝트 폴더에서 한 턴만 실행해, 세션을 시작할 때 붙는 입력 토큰만 쟀습니다.
• 사용자 설정, 플러그인, 훅은 --setting-sources project로 빼고, MCP는 --strict-mcp-config로 조건에 적은 서버만 붙였습니다.
• MCP 서버는 @modelcontextprotocol/server-filesystem, server-memory, server-sequential-thinking 1.0.0입니다.
• 기본 도구 목록이 다 불러와지기 전에 시작된 회차(빈 프로젝트의 36,625개, 내장 도구 25개)는 뺐습니다.

이 측정에 없는 것도 분명히 해 둡니다. 작업 중 파일을 읽을 때 드는 토큰, 하위 폴더 지침이나 rules, 스킬 본문이 나중에 불려 올 때 드는 토큰은 재지 않았습니다. effort 수준이나 모델에 따른 차이도 들어 있지 않죠. 그러니 지침을 옮긴 뒤에는 평소 하던 작업을 한 번 돌리고 /usage와 /context로 실제 사용량을 확인해 보세요.