Claude Code를 본격적으로 쓰기 시작하면 한 달 토큰 사용량을 보고 한 번쯤 놀란다. 똑같은 작업을 시켰는데 어떤 날은 컨텍스트가 가볍고 어떤 날은 무거워진다. 결국 토큰이 어디서 새는지 모르면 절약 전략도 세울 수 없다는 결론에 도달한다. Anthropic 공식 마켓플레이스에는 이 문제를 정면으로 겨냥한 플러그인이 모여 있다. 이 글은 그중에서 토큰 절약에 직결되는 4개를 골라, 각 도구가 토큰을 어떻게 아껴주고 Harness Engineering 관점에서 어떻게 쓰는지 정리한다
다루는 4개 플러그인 한눈에 보기
| 플러그인 | 핵심 역할 | 절약 메커니즘 |
|---|---|---|
| Session Report | 토큰 사용 명세서 | 비싼 프롬프트와 캐시 적중률 가시화 |
| ClaudeMD Management | CLAUDE.md 정리 도구 | 매 요청에 따라붙는 시스템 프롬프트 다이어트 |
| Serena | 의미 기반 코드 검색 MCP | grep 기반 탐색을 심볼 단위로 대체 |
| Hookify | 반복 실수 차단 훅 자동 생성 | 잘못된 작업으로 낭비되는 재시도 사이클 제거 |
이 네 가지는 각각 토큰 누수의 다른 지점을 막는다. 측정(Session Report) → 시스템 프롬프트 절약(ClaudeMD Management) → 탐색 절약(Serena) → 재시도 절약(Hookify) 순으로 보면 흐름이 자연스럽다
공식 마켓플레이스에서 플러그인 설치하는 법
Anthropic 공식 마켓플레이스(claude-plugins-official)는 Claude Code에 기본으로 등록돼 있다. 설치는 슬래시 명령 한 번으로 끝난다.
# Claude Code 안에서 /plugins
검색 탭에서 원하는 플러그인 이름을 입력하고, 설치할 스코프(프로젝트 또는 사용자 전역)를 선택한다. 설치 직후 등록된 명령과 스킬을 활성화하려면 다음을 실행한다
/reload-plugins
이 단계는 모든 플러그인 공통이다. 아래 4개 도구도 같은 방식으로 설치한다
Session Report – Claude Code의 토큰 명세서
Session Report는 Claude Code 사용량을 카드 명세서처럼 보여주는 플러그인이다. 카드 명세서가 카페·주유소·배달 앱 항목별로 지출을 분리해 보여주듯, Session Report는 토큰을 프로젝트별·스킬별·서브에이전트별·프롬프트별로 분리해 HTML 리포트로 출력한다
이 도구가 특히 빛을 발하는 두 가지 상황이 있다
- 토큰 비용이 갑자기 튀었을 때 어떤 프로젝트와 어떤 프롬프트가 원인인지 추적
- 프롬프트 캐시가 정상 작동하는지 적중률 확인
캐시는 토큰 비용을 결정짓는 핵심 요소다. Claude Code는 시스템 프롬프트나 CLAUDE.md처럼 반복되는 부분을 한 번 처리해 캐시에 저장하고, 이후 요청에서 해당 영역을 1/10 가격으로 청구한다. 캐시가 자주 깨지면 이 할인이 무의미해지므로, Session Report로 캐시 적중률을 주기적으로 확인하는 것이 비용 관리의 출발점이다
호출은 자연어로도 되고 슬래시 명령으로도 된다. 직접 호출 방식이 옵션을 명시하기 좋다.
# 기본은 7일 /session-report # 기간 지정: 30일 /session-report --period 30d # 24시간 /session-report --period 24h
리포트는 HTML 파일로 생성된다. 히어로 섹션에 분석 기간, 입력·출력 토큰, 캐시 처리 비율이 표시되고, 그 아래에 프로젝트별 사용량과 가장 비싼 프롬프트 목록이 이어진다. 비싼 프롬프트를 클릭하면 해당 프롬프트가 거친 작업 사이클과 기간 내 토큰 추이를 볼 수 있다. 절약 전략은 이 리포트를 본 다음에 세우는 것이 효율적이다
ClaudeMD Management – 시스템 프롬프트 다이어트 도구
CLAUDE.md는 프로젝트에서 Claude Code가 따라야 할 규칙을 적어두는 파일이다. 모든 요청 앞에 자동으로 붙기 때문에, 이 파일이 비대해질수록 매 요청마다 더 많은 토큰을 쓴다. 프로젝트가 길어질수록 규칙이 쌓이고, 쌓일수록 파일이 무거워지는 구조다. ClaudeMD Management 플러그인은 이 파일을 깔끔하게 유지하기 위한 두 개의 명령으로 구성된다
Revise Cloud MD – 작업이 끝난 직후 회의록처럼 기록
작업 한 사이클을 마치고 세션이 끝나기 전에 호출한다. 이번 대화에서 새로 알게 된 명령어, 작업 패턴, 함정 같은 것을 자동으로 추출해 CLAUDE.md에 추가할 후보로 보여준다
/revise-cloud-md
회의가 끝난 직후 작성하는 회의록과 같은 역할이다. 사람이 직접 메모할 때는 사소해 보여 빼먹기 쉬운 패턴까지 잡아준다
ClaudeMD Improver – 주기적으로 파일 건강 진단
이 명령은 프로젝트의 모든 CLAUDE.md를 6개 기준으로 채점하고 등급을 매긴다. 더 이상 동작하지 않는 명령어, 빠진 의존성, 누락된 환경 설정 같은 이슈를 함께 보고한다
/claude-md-improver
CLAUDE.md가 매 요청에 붙는다는 사실을 다시 떠올리면, 죽은 규칙을 빼는 것만으로도 누적 절약 효과가 크다
Serena MCP – grep 기반 탐색을 의미 기반으로 대체
Serena는 토큰 절약 관점에서 가장 효과가 큰 도구다. 외부 MCP임에도 Anthropic 공식 마켓플레이스와 공식 문서가 함께 소개할 정도다
왜 grep 기반 탐색이 토큰을 잡아먹는가
“로그인 기능을 분석해줘”라는 요청을 받으면 Claude Code는 기본적으로 로그인이라는 키워드를 프로젝트 전체에서 grep으로 찾는다. 변수명·주석·문자열 모두 같은 텍스트로 보고 훑는다. 의미는 모르고 글자만 보는 방식이다. 이 방식의 문제는 두 가지다
- 관련 없는 매칭이 대거 잡혀 컨텍스트에 들어간다
- 한 번 컨텍스트에 들어간 토큰은 이후 대화 내내 계속 비용으로 쌓인다
검색에 1만 토큰을 썼다면, 같은 세션에서 추가 질문을 할 때마다 그 1만 토큰이 누적된다. 탐색 한 번이 잘못되면 세션 전체 비용이 부풀어 오르는 구조다
Serena가 하는 일
Serena는 IDE의 “정의로 이동”, “참조 찾기” 같은 의미 기반 탐색을 MCP로 제공한다. Claude는 더 이상 글자가 아니라 심볼 단위로 코드를 본다.
[기존 grep 방식] "로그인" 키워드 → 변수명 · 주석 · 문자열 전부 매칭 → 컨텍스트 폭증 [Serena MCP 방식] "로그인" 의미 → LoginService 심볼 정의 · 호출처 → 필요한 코드만 컨텍스트
리팩토링에서도 위력이 다르다. AuthContext를 SessionContext로 바꾸려면 기존에는 30개 파일을 일일이 확인해야 했지만, Serena의 rename 기능으로 한 번에 처리할 수 있다
설치와 연결
Serena는 Python 패키지 매니저 uv가 시스템에 있어야 동작한다
# uv 설치 (macOS / Linux 예시) curl -LsSf https://astral.sh/uv/install.sh | sh
uv를 설치한 다음, Claude Code에서 Serena 플러그인을 설치하고 MCP를 재연결한다
/plugins # Serena 검색 후 설치 /reload-plugins /mcp # Serena가 failed 상태면 Reconnect 선택
연결되면 로컬에서 Serena 대시보드가 실행되고, 활성 도구 n개가 표시된다. 자연어 요청 시 의도한 MCP가 작동하지 않으면 프롬프트에 명시적으로 도구 이름을 적는다
Serena를 사용해서 GoogleLoginButton이 어디에서 쓰이는지 찾아줘
명시 호출이 한두 번 들어가면 이후에는 Claude가 해당 프로젝트에서 Serena를 우선 선택한다
Hookify – 같은 실수를 두 번 하지 않게 만드는 Harness 도구
Harness Engineering은 Mitchell Hashimoto가 정리한 개념으로, “에이전트가 실수할 때마다 그 실수가 다시는 발생하지 않도록 환경을 엔지니어링한다”는 원칙이다. AI를 탓하는 대신 같은 실수를 못 하도록 환경을 고친다는 뜻이다. Hookify는 이 원칙을 그대로 구현한 Anthropic 공식 플러그인이다
토큰 관점에서 잘못된 작업의 비용은 단순히 그 작업 자체가 아니다. 잘못 만든 결과물을 검토하고, 원인을 추궁하고, 수정 지시를 내리고, 재시도하는 사이클 전체가 비용이다. Hookify는 실수가 발생하기 전에 차단해 이 사이클을 통째로 없앤다
가장 자주 쓰는 두 명령
# Claude가 또 하면 안 되는 실수를 등록 /hookify # 최근 짜증났던 패턴을 자동 추출 (같은 실수 3회 반복 시 추천) /hookify-extract
/hookify는 사용자가 명시한 실수에 대해 몇 가지 질문을 던진 뒤, .claude 디렉터리 하위에 마크다운 파일을 생성한다. 파일은 frontmatter에 어떤 시점에 발동할지를 정의하고, 본문에 Claude가 따라야 할 지침을 담는다
/hookify-extract는 최근 대화에서 반복된 실수를 스스로 찾아 규칙을 만든다. 같은 작업을 세 번째 다시 시키고 있다는 느낌이 들면 이 명령이 가장 빠른 해결책이다
플러그인 안에는 등록 규칙 조회, 사용법 안내 등 보조 명령도 함께 들어 있다. Harness 규칙 자체를 자산처럼 관리할 수 있는 구조다
네 도구를 함께 쓰면 절약 효과가 곱해진다
각 도구의 효과는 독립적이지만, 같이 쓰면 토큰 절약 사이클이 닫힌다
1. Session Report로 비싼 프롬프트와 캐시 적중률 확인 2. CLAUDE.md가 비대하면 ClaudeMD Improver로 정리 3. 코드 탐색이 무거우면 Serena MCP로 의미 기반 전환 4. 같은 실수가 반복되면 Hookify로 차단 5. 다시 1번으로 돌아가 효과 측정
Session Report가 측정 지점, ClaudeMD Management와 Serena가 매 요청 비용을 줄이는 지점, Hookify가 재시도 비용을 없애는 지점이다. 어디서 새는지 모른 채 절약하려 들면 결국 또 새는데, 이 네 도구는 누수 지점을 차례대로 봉쇄한다
정리
Claude Code 토큰 절약은 결국 네 가지 질문에 답하는 일이다. 어디서 새는가(Session Report), 시스템 프롬프트가 비대하지 않은가(ClaudeMD Management), 코드 탐색이 의미 기반인가(Serena), 같은 실수를 반복하지 않는가(Hookify). 이 네 개를 같이 들이면 같은 작업을 더 적은 토큰으로 끝낼 수 있다