Claude Code 토큰 절약 가이드

Claude Code 토큰 절약 가이드

Claude Code 토큰 절약은 무조건 짧게 묻거나 싼 모델을 고르는 일이 아닙니다. 필요 없는 입력과 재시도를 줄이면서 같은 작업을 같은 품질로 끝내는 것이 목표입니다. 먼저 컨텍스트 점유량, 사용 토큰, 실제 비용을 나눠 보세요.

이 글은 공식 문서를 바탕으로 세션·지침·스킬·MCP·모델 분업을 점검하는 방법과 독자가 직접 비교할 수 있는 실습 절차를 정리했습니다. 특정 절감률을 직접 측정한 후기는 아닙니다.

문서 대조·개정: 2026년 11월 4일. 모델과 명령의 지원 범위는 설치 버전·계정에 따라 달라질 수 있습니다.

먼저 구분할 세 가지

  • 컨텍스트: 현재 요청에서 모델이 참고하는 정보의 크기입니다.
  • 토큰 사용량: 요청과 응답, 추론·도구 사용 과정에서 집계되는 양입니다.
  • 비용·플랜 한도: 모델, 캐시, 구독/API 조건에 따라 달라집니다. 토큰 수와 일대일로 같지 않습니다.

이전 대화가 현재 컨텍스트에 포함되더라도 캐시 적중 부분은 새 입력과 과금 방식이 다를 수 있습니다. 자동 압축도 있으므로 과거 대화가 영원히 원문 그대로 전부 쌓인다고 보지는 않습니다.

1. /clear와 /compact는 언제 쓰면 좋을까요?

지금 작업과 관계없는 새 일을 시작한다면 /clear, 같은 작업을 이어가되 긴 대화를 요약하고 싶다면 /compact를 검토합니다. 컨텍스트를 줄이는 것과 이미 사용한 토큰을 되돌려 받는 것은 다릅니다. 요약 자체에도 모델 호출이 필요하므로 매번 습관적으로 압축할 필요는 없습니다.

  1. /context로 현재 무엇이 공간을 차지하는지 확인합니다.
  2. 나중에 다시 찾을 세션이면 /rename login-validation처럼 이름을 붙입니다.
  3. 작업을 이어갈 때는 /compact 변경 파일, 테스트 결과, 남은 오류와 다음 작업을 남겨줘처럼 보존할 내용을 적습니다.
  4. 완전히 다른 일을 시작할 때 새 세션을 열고, 필요할 때 /resume으로 이전 세션을 찾습니다.

압축 뒤에는 파일 경로와 미해결 사항이 제대로 남았는지 확인하세요. 요약이 원본의 모든 세부 사항을 보존한다고 가정하면 안 됩니다.

2. CLAUDE.md는 줄 수보다 내용의 역할을 나누세요

CLAUDE.md에는 빌드·테스트 명령, 디렉터리 규칙, 반드시 지켜야 할 제약처럼 자주 필요한 정보를 남깁니다. 특정 상황에서만 필요한 긴 절차는 스킬이나 별도 문서로 분리하는 편이 좋습니다.

이 파일은 컨텍스트를 차지하지만, 매번 같은 양의 새 입력 요금이 그대로 청구되는 것은 아닙니다. 캐시가 적중하면 반복되는 앞부분에 캐시 읽기 요금이 적용될 수 있습니다. 컨텍스트 점유량, 사용 토큰, 실제 비용은 구분해서 봐야 합니다.

# 프로젝트 규칙
- 패키지 매니저: pnpm
- 테스트: pnpm test
- 변경한 기능의 테스트 결과를 함께 보고
- 인증·결제 코드는 요청 범위 밖이면 변경 금지

위 내용은 작성 예시입니다. 실제 프로젝트 명령에 맞게 바꾸세요. 무조건 몇 줄 이하로 줄이기보다, 불필요한 설명은 빼고 빠뜨리면 재작업이 생기는 규칙은 남기는 것이 기준입니다.

근거: 공식 프롬프트 캐싱 안내 · 공식 스킬 안내

3. 모델은 토큰 단가보다 작업 완료 비용으로 고르세요

단순한 이름 변경과 여러 서비스에 걸친 설계 검토에 같은 모델을 쓸 필요는 없습니다. 다만 저렴한 모델이 반복해서 실패하면 재시도와 사람의 수정 비용이 더 커질 수 있습니다.

  • 오타·작은 수정: 현재 계정에서 제공되는 비교적 가벼운 모델부터 검토합니다.
  • 복잡한 설계·보안 검토: 더 높은 추론 능력이 필요한지 판단합니다.
  • 모델 분업: 구현과 검토를 나눌 수 있지만 작업 지시·결과 통합 비용까지 합산합니다.

/model에서 실제 제공 모델을 확인하고, 설정은 공식 모델 설정 문서와 대조하세요. 블로그에 적힌 모델 이름이 내 플랜에서도 제공된다고 가정하지 않는 편이 좋습니다.

외부 후기의 절감률은 사용 모델, 입력량, 캐시와 과금 방식에 따라 달라집니다. 특정 모델의 토큰을 덜 쓴 것과 전체 비용이 줄어든 것도 다릅니다. 저는 고정 절감률을 약속하기보다 아래의 비교 절차로 작업 완료까지의 비용을 확인하는 방식을 권합니다.

4. MCP는 서버 수보다 실제 로드량과 응답 크기를 보세요

MCP는 외부 서비스의 도구를 Claude Code에서 쓰게 해줍니다. 현재 공식 문서의 MCP Tool Search는 도구 정의를 필요할 때 불러오는 방식을 설명합니다. 따라서 연결된 모든 도구의 전체 정의가 언제나 처음부터 컨텍스트에 들어간다고 설명하는 것은 정확하지 않습니다.

  1. /mcp에서 연결 상태와 불필요한 서버를 확인합니다.
  2. /context에서 실제 컨텍스트 구성을 살펴봅니다.
  3. 검색 기간, 파일 범위, 반환 항목 수를 줄여 큰 응답이 반복되지 않게 합니다.

이미 쓰는 CLI가 있고 필요한 항목만 출력할 수 있다면 대안이 될 수 있습니다. 하지만 CLI라고 항상 토큰이 적게 드는 것은 아닙니다. 같은 작업의 출력 크기, 권한과 재시도 횟수를 비교하세요.

근거: MCP Tool Search 공식 안내

5. 스킬과 훅은 서로 다른 문제를 해결합니다

스킬은 반복되는 작업 절차를 재사용하는 방법입니다. 일반 세션에서는 스킬의 이름·설명 등 메타데이터가 컨텍스트에 들어가고, 본문은 호출할 때 로드됩니다. 따라서 “평소에는 토큰을 전혀 쓰지 않는다”가 아니라 “긴 본문을 항상 넣지 않아도 된다”가 정확합니다.

프로젝트 폴더의 .claude/skills/commit-summary/SKILL.md에 아래처럼 짧은 절차를 둘 수 있습니다. 실제 자동 선택 여부는 설명과 요청의 관련성에 따라 달라집니다.

---
name: commit-summary
description: 변경 내용을 읽고 커밋 메시지 초안을 만들 때 사용.
---
1. git diff --stat으로 변경 범위를 확인한다.
2. 필요한 변경 파일의 diff를 읽는다.
3. 테스트 실행 여부와 남은 위험을 구분한다.
4. Conventional Commits 형식의 메시지 초안만 제안한다.
5. 사용자의 요청 없이 커밋하거나 푸시하지 않는다.

훅은 정해진 이벤트에 실행되는 코드입니다. PreToolUse는 도구 실행 전이므로, 이름만 등록한다고 아직 실행하지 않은 테스트의 결과를 자동으로 걸러주지 않습니다. 실행 뒤 결과 처리는 해당 이벤트와 출력 규격에 맞춘 구현이 별도로 필요합니다.

처음에는 훅을 설치하기보다, 테스트 로그를 파일에 보관하고 필요한 부분만 읽게 하는 편이 이해하기 쉽습니다. 예를 들어 Bash 계열 셸에서 이미 저장한 로그를 찾는 명령은 다음과 같습니다.

grep -n -E 'FAIL|Error|Assertion' test-output.log

이 명령은 테스트를 실행하거나 성공을 판정하지 않습니다. 테스트의 종료 코드와 최종 요약을 별도로 확인하고, 검색어가 없는 실패를 놓치지 않도록 원본 로그도 보관하세요. Bash 예시이므로 PowerShell에 그대로 복사하는 명령으로 소개하지 않습니다.

근거: 스킬 로딩 방식 · 훅 이벤트와 입출력 규격

6. 서브에이전트는 메인 대화를 정리하지만 공짜는 아닙니다

서브에이전트는 별도 컨텍스트에서 작업하고 요약을 돌려주므로, 탐색 과정의 긴 로그가 메인 대화를 채우는 것을 줄일 수 있습니다. 하지만 별도의 모델 요청과 사용량이 생깁니다. 메인 컨텍스트 절약이 전체 토큰 절약을 보장하지는 않습니다.

관련 없는 두 영역의 조사처럼 결과를 독립적으로 모을 수 있을 때 활용하고, 파일 하나의 작은 수정은 메인 에이전트로 끝내는 편이 나을 수 있습니다.

인증 경로 조사만 서브에이전트에 맡겨줘.
범위는 src/auth와 관련 테스트야. 파일은 수정하지 마.
반환 결과는 관련 파일 경로, 확인된 동작, 근거 위치,
확인하지 못한 점으로 제한해줘. 같은 조사는 메인에서 반복하지 마.

처음부터 여러 에이전트를 만들기보다 한 작업에 적용한 뒤 총사용량과 검수 시간을 확인하세요. 재사용 역할을 만들 때는 도구 권한과 모델도 범위에 맞게 제한합니다.

근거: 공식 서브에이전트 안내

7. 사고 강도 설정은 모델 지원 범위부터 확인하세요

추론에 쓰는 토큰을 줄이면 비용과 시간이 줄 수 있지만, 어려운 작업의 재시도가 늘면 전체 효율은 나빠질 수 있습니다. 현재 모델이 지원한다면 /effort 또는 모델 설정에서 사고 강도를 조절하고 결과 품질을 비교합니다.

MAX_THINKING_TOKENS의 양수 예산은 모든 모델에 공통으로 적용되는 설정이 아닙니다. 고정 예산 방식과 adaptive reasoning 방식의 동작이 다르고, 일부 모델은 thinking을 끌 수 없습니다. 따라서 MAX_THINKING_TOKENS=8000을 만능 절약 설정으로 권하지 않습니다.

작은 수정에서 낮은 강도를 시험하더라도 동일한 테스트를 통과하는지 확인하세요. 모델마다 기본 강도와 허용 값이 다를 수 있으므로 “기본값은 항상 높음”이라고 가정하지 않습니다.

근거: 공식 모델·effort 설정

8. 프롬프트에 범위와 완료 조건을 같이 적으세요

“이 코드베이스를 개선해줘”보다 수정 위치, 해야 할 일, 건드리지 않을 범위를 알려주는 편이 불필요한 탐색을 줄이기 쉽습니다. 그렇다고 필요한 보안 검토나 테스트까지 생략시키면 안 됩니다.

src/auth.ts의 login 함수에 이메일 형식 검증을 추가해줘.
기존 인증 흐름과 응답 형식은 유지하고, DB 스키마는 바꾸지 마.
먼저 관련 구현과 테스트 위치만 확인해줘.
정상 이메일, 잘못된 형식, 빈 문자열의 테스트를 확인하고
실행한 명령과 결과, 실행하지 못한 검사를 구분해 보고해줘.
범위 밖 리팩터링이 필요하면 수정 전에 이유를 알려줘.

이 예시는 특정 프로젝트에서 실행한 결과가 아니라 요청 구조를 보여주는 템플릿입니다. 파일 경로와 검증 조건은 내 코드베이스에 맞게 바꾸세요.

9. 큰 작업은 계획을 먼저 확인하고 잘못된 방향을 일찍 멈추세요

범위가 큰 작업은 Plan Mode로 변경 대상과 검증 계획부터 확인하는 편이 좋습니다. 반대로 작은 오타 수정까지 긴 계획을 반복하면 그 자체가 비용이 됩니다.

  1. 수정 범위, 영향을 받는 파일, 통과해야 할 테스트를 먼저 정합니다.
  2. 방향이 다르면 길게 진행하기 전에 중단하고 조건을 바로잡습니다.
  3. 구현 뒤 실제 테스트 결과와 변경 diff를 확인합니다.

/rewind 같은 체크포인트 기능이 모든 외부 작업을 되돌려주지는 않습니다. 셸 명령의 부수 효과, 배포, 데이터베이스 변경까지 자동 복구된다고 믿지 말고 Git과 별도 백업을 사용하세요.

핵심은 “가장 짧은 답변”이 아니라 “불필요한 수정 왕복 없이 검증된 변경을 끝내기”입니다.

10. 코드 탐색 도구는 프로젝트에 맞는 것만 쓰세요

언어 서버를 활용하는 코드 인텔리전스 도구는 정의·참조 탐색과 진단에 도움이 될 수 있습니다. 다만 설치 여부만으로 모든 탐색이 한 번에 끝나거나 빌드·테스트가 필요 없어지는 것은 아닙니다.

현재 /plugin 화면과 공식 설치 문서에서 지원 언어, 플러그인 이름, 필요한 언어 서버를 확인하세요. 이미 잘 동작하는 환경이라면 절약을 위해 무조건 새 도구부터 설치할 필요는 없습니다.

확인 기준은 관련 없는 파일을 덜 읽는지, 실제로 참조 위치를 정확히 찾는지, 시작 시간과 컨텍스트 부담이 늘지 않는지입니다.

근거: 공식 플러그인 안내

11. 에이전트 팀은 속도와 총비용을 따로 평가하세요

여러 독립 세션이 협업하는 에이전트 팀은 병렬 조사에 유용할 수 있지만, 각 세션의 요청과 팀 간 조정에 추가 사용량이 듭니다. 팀원 수와 실제 비용이 정확히 같은 배수로 늘어나는 것도 아니고, Plan Mode만 켜면 일정 배수의 비용이 발생하는 것도 아닙니다.

  • 작업이 서로 독립적일 때만 나눕니다.
  • 동일 파일을 여러 작업자가 동시에 고치지 않도록 소유 범위를 정합니다.
  • 필요한 인원만 사용하고, 끝난 작업자를 정리합니다.
  • 대기 시간뿐 아니라 전체 토큰·비용·통합 및 검수 시간을 비교합니다.

단순한 조사 한 건이면 팀보다 서브에이전트 하나가 적절할 수 있습니다. 제공 조건과 활성화 방법은 현재 버전의 공식 에이전트 팀 안내를 확인하세요.

12. 보조 도구 설치는 기본 설정을 확인한 다음입니다

출력 압축 도구, 저장소 요약 도구, 사용량 표시 플러그인은 보조 수단입니다. 설치하기 전에 공식 프로젝트인지, 어떤 파일을 읽고 외부로 보내는지, 최근 유지보수가 되는지 확인해야 합니다.

특히 저장소를 한 파일로 모은다고 자동으로 토큰이 절약되는 것은 아닙니다. 필요 없는 코드까지 모두 전달하면 오히려 입력이 커질 수 있습니다. 로그를 압축할 때도 오류·종료 코드·검증 근거를 없애지 않아야 합니다.

처음에는 /context, /usage, 명확한 작업 범위만으로 기준선을 만드세요. 이후에 부족한 점 하나를 해결할 도구를 선택하는 편이 원인과 효과를 파악하기 쉽습니다.

내 작업에서 정말 절약됐는지 비교하는 방법

아래는 독자가 직접 실행할 수 있는 비교 절차입니다. 이 글에서 측정한 절감률이나 벤치마크 결과가 아닙니다. 토큰 수만 줄고 테스트가 실패한다면 같은 품질의 개선이라고 보기 어렵습니다.

  1. 작업을 고정합니다. 예를 들어 작은 버그 한 건을 고르고 시작 커밋, 요청문, 통과 조건을 기록합니다.
  2. 환경을 기록합니다. Claude Code 버전, 모델, effort, 구독/API 방식, 활성 스킬·MCP를 적습니다.
  3. 현재 방식으로 기준선을 만듭니다. 종료 시 /usage에서 제공되는 토큰·캐시·비용 또는 플랜 사용량과 테스트 결과를 기록합니다.
  4. 변수 하나만 바꿉니다. 별도 브랜치나 작업 복사본에서 같은 시작 상태를 사용하고, 예를 들어 프롬프트 범위만 좁혀 다시 실행합니다. 기존 작업을 강제로 초기화하지 마세요.
  5. 전체 완료 비용을 비교합니다. 재시도, 서브에이전트, 사람이 고친 시간까지 포함합니다. 캐시 상태가 다르다면 차이를 함께 기록하고, 한 번의 실행만으로 일반적인 절감률을 주장하지 않습니다.
실행일 / Claude Code 버전:
시작 커밋 / 작업 / 통과 조건:
모델 / effort / 구독 또는 API:
이번에 바꾼 조건 한 가지:
입력·출력 토큰 / 캐시 읽기·쓰기(표시되는 경우):
세션 비용 추정치 또는 플랜 사용량:
총 소요 시간 / 재시도 / 사람의 수정 시간:
테스트 결과 / 확인하지 못한 항목:

API 사용자는 표시 비용이 추정치라는 점을 기억하고 최종 청구 내역과 대조하세요. 구독 사용자는 세션 비용 숫자를 월 구독료에 추가 청구되는 금액으로 해석하지 않습니다. 플랜 한도와 API 비용은 같은 지표가 아닙니다.

현재 공식 안내는 /usage에서 세션 및 플랜 사용량을 확인하는 방법을 설명합니다. 버전에 따라 표시 항목이 다를 수 있으므로 내 화면에 없는 세부 수치를 추측해서 채우지 마세요.

근거: 공식 사용량·비용 안내

먼저 세 가지만 적용한다면

첫째, /context와 /usage로 기준선을 확인하세요. 둘째, 요청 범위와 완료 조건을 구체화하세요. 셋째, 작업에 필요 없는 긴 지침과 로그를 줄이세요. 모델 분업과 보조 도구는 그다음입니다.

관련 글

공식 참고 자료

기능·설정은 아래 공식 문서를 기준으로 확인했습니다. 이 글의 예시 프롬프트와 비교 절차는 이해를 돕기 위한 제안이며, 실제 성과를 보장하지 않습니다.

#ClaudeCode #토큰절약 #AI코딩

댓글

이 블로그의 인기 게시물

클로드 Gmail 연동 방법: 이메일 분류·요약·답장 자동화

바이브 코딩에 유용한 핵심 AI 스킬 8가지와 생성 프롬프트