Claude Code를 본격적으로 쓰기 시작하면 한 달 토큰 사용량을 보고 한 번쯤 놀란다. 똑같은 작업을 시켰는데 어떤 날은 컨텍스트가 가볍고 어떤 날은 무거워진다. 토큰이 어디서 새는지 모르면 절약 전략도 세울 수 없다는 결론에 도달한다. Anthropic 공식 마켓플레이스에는 이 문제를 정면으로 겨냥한 플러그인이 모여 있다. 이 글은 그중에서 토큰 절약에 직결되는 4개를 골라, 각 도구가 토큰을 어떻게 아껴주고 Harness Engineering 관점에서 어떻게 쓰는지 정리한다
다루는 4개 플러그인 한눈에 보기
| 플러그인 | 핵심 역할 | 절약 메커니즘 | 출처 |
|---|---|---|---|
| Session Report | 토큰 사용 명세서 | 비싼 프롬프트와 캐시 적중률 가시화 | Anthropic 공식 |
| ClaudeMD Management | CLAUDE.md 정리 도구 | 매 요청에 따라붙는 시스템 프롬프트 다이어트 | Anthropic 공식 |
| Serena | 의미 기반 코드 검색 MCP | grep 기반 탐색을 심볼 단위로 대체 | oraios (외부, 공식 마켓플레이스 등재) |
| Hookify | 반복 실수 차단 훅 자동 생성 | 잘못된 작업으로 낭비되는 재시도 사이클 제거 | Anthropic 공식 |
이 네 가지는 각각 토큰 누수의 다른 지점을 막는다. 측정(Session Report) → 시스템 프롬프트 절약(ClaudeMD Management) → 탐색 절약(Serena) → 재시도 절약(Hookify) 순으로 보면 흐름이 자연스럽다
공식 마켓플레이스에서 플러그인 설치하는 법
Anthropic 공식 마켓플레이스(claude-plugins-official)는 Claude Code에 기본으로 등록돼 있다. 설치는 슬래시 명령으로 진입한 뒤 UI에서 진행한다
bash
# Claude Code 안에서 /plugins
다음 순서를 따른다
/plugins입력 후 엔터Discover탭으로 이동- 설치할 플러그인 이름 검색
- 검색 결과에서 엔터로 플러그인 선택
- 설치 스코프(프로젝트 또는 사용자 전역) 선택
설치 직후 등록된 명령과 스킬을 활성화하려면 다음을 실행한다
/reload-plugins
리로드한 다음에는 슬래시 입력 후 자동완성으로 실제 등록된 명령어명을 직접 확인하는 것을 권장한다. 플러그인 버전에 따라 명령어 네임스페이스가 달라질 수 있다
/<플러그인명>: ← 콜론까지 입력하면 자동완성 후보가 펼쳐진다
이 단계는 Anthropic 공식 플러그인 공통이다. Serena만 별도 설치 경로를 따른다(아래 Serena 섹션 참고)
Session Report – Claude Code의 토큰 명세서
Session Report는 Claude Code 사용량을 카드 명세서처럼 보여주는 플러그인이다. 카드 명세서가 카페·주유소·배달 앱 항목별로 지출을 분리해 보여주듯, Session Report는 토큰을 프로젝트별·스킬별·서브에이전트별·프롬프트별로 분리해 HTML 리포트로 출력한다
이 도구가 특히 빛을 발하는 두 가지 상황이 있다
- 토큰 비용이 갑자기 튀었을 때 어떤 프로젝트와 어떤 프롬프트가 원인인지 추적
- 프롬프트 캐시가 정상 작동하는지 적중률 확인
캐시는 토큰 비용을 결정짓는 핵심 요소다. Anthropic 공식 가격표 기준으로 캐시 읽기는 표준 입력 가격의 10%로 청구된다(약 90% 할인). 다만 캐시 작성에는 5분 캐시는 1.25배, 1시간 캐시는 2배가 붙는다는 점을 함께 기억해야 한다. 캐시가 자주 깨지면 할인이 무의미해지므로, Session Report로 캐시 적중률을 주기적으로 확인하는 것이 비용 관리의 출발점이다
호출은 자연어로도 되고 슬래시 명령으로도 된다
# 기본 호출 (기본 기간) /session-report # 기간 지정 — 실제 동작 확인됨 /session-report --period 7d /session-report --period 30d # 그 외 옵션은 --help로 확인 /session-report --help
--period 7d는 실사용에서 정상 동작이 확인된 문법이다. 다른 단위(예: 24h)나 추가 플래그는 버전에 따라 다를 수 있으므로 --help로 먼저 확인하는 편이 안전하다
리포트는 HTML 파일로 생성된다. 히어로 섹션에 분석 기간, 입력·출력 토큰, 캐시 처리 비율이 표시되고, 그 아래에 프로젝트별 사용량과 가장 비싼 프롬프트 목록이 이어진다. 비싼 프롬프트를 클릭하면 해당 프롬프트가 거친 작업 사이클과 기간 내 토큰 추이를 볼 수 있다. 절약 전략은 이 리포트를 본 다음에 세우는 것이 효율적이다
ClaudeMD Management – 시스템 프롬프트 다이어트 도구
CLAUDE.md는 프로젝트에서 Claude Code가 따라야 할 규칙을 적어두는 파일이다. 모든 요청 앞에 자동으로 붙기 때문에, 이 파일이 비대해질수록 매 요청마다 더 많은 토큰을 쓴다. 프로젝트가 길어질수록 규칙이 쌓이고, 쌓일수록 파일이 무거워지는 구조다
ClaudeMD Management 플러그인은 이 파일을 깔끔하게 유지하기 위한 두 도구로 구성된다. 형태가 달라 헷갈리기 쉽다. 하나는 스킬, 하나는 슬래시 명령이다
| 도구 | 형태 | 호출 방식 | 역할 |
|---|---|---|---|
claude-md-improver | 스킬 | 자연어 또는 /claude-md-management:claude-md-improver | 코드베이스와 CLAUDE.md 정합성 점검 |
/revise-claude-md | 슬래시 명령 | /claude-md-management:revise-claude-md | 세션에서 얻은 학습을 CLAUDE.md에 반영 |
위 명령어명은 공식 문서 기준이다. 플러그인 설치와 /reload-plugins 직후, 슬래시 후 /claude-md-management: 까지 입력해 자동완성 후보를 띄우고 실제 등록된 명령어명을 한 번 더 확인하는 것을 권장한다. 버전 차이로 명령어명이 달라질 가능성이 있기 때문이다
claude-md-improver – 정기 건강검진
claude-md-improver는 스킬이라 정해진 슬래시 명령이 없다. 자연어로 충분하다.
내 CLAUDE.md 점검해줘
스킬이 발동하면 다음 워크플로우가 실행된다
- 저장소의 모든
CLAUDE.md,CLAUDE.local.md탐색 - 6개 기준 100점 루브릭으로 채점
- A(90-100) ~ F(0-29) 5단계 등급 부여
- 개선 제안을 diff로 제시하고 적용 전 승인 요청
채점 기준은 다음과 같다
| 기준 | 배점 | 평가 내용 |
|---|---|---|
| Commands / Workflows | 20 | build, test, lint, deploy 등이 빠짐없이 적혀 있는가 |
| Architecture Clarity | 20 | 디렉터리 구조와 모듈 관계가 명료한가 |
| Non-Obvious Patterns | 15 | 함정이나 비자명한 규약이 문서화돼 있는가 |
| Conciseness | 15 | 군더더기 설명이 들어 있지 않은가 |
| Currency | 15 | 현재 코드베이스와 일치하는가 |
| Actionability | 15 | 명령은 복붙으로 동작하는가, 절차는 구체적인가 |
Conciseness 항목이 별도 배점이라는 사실에 주목할 만하다. CLAUDE.md는 매 요청에 그대로 붙기 때문에, “일단 다 적어두자”는 태도가 곧 토큰 비용으로 이어진다
명시적으로 호출하고 싶다면 자동완성으로 풀네임을 채운다
/claude-md-management:claude-md-improver
/revise-claude-md – 세션 회의록
작업 한 사이클을 마치고 세션이 끝나기 전에 호출한다. 이번 대화에서 발견한 명령어, 패턴, 함정을 자동으로 추출해 CLAUDE.md에 추가할 후보로 보여준다
/claude-md-management:revise-claude-md
회의가 끝난 직후 작성하는 회의록과 같은 역할이다. 추가할 후보를 diff로 보여주므로 그대로 넘길 수도 있고 부분만 받아들일 수도 있다
Serena MCP – grep 기반 탐색을 의미 기반으로 대체
Serena는 토큰 절약 관점에서 가장 효과가 큰 도구다. 외부 MCP임에도 Anthropic 공식 마켓플레이스가 함께 소개할 정도다
왜 grep 기반 탐색이 토큰을 잡아먹는가
“로그인 기능을 분석해줘”라는 요청을 받으면 Claude Code는 기본적으로 로그인이라는 키워드를 프로젝트 전체에서 grep으로 찾는다. 변수명·주석·문자열 모두 같은 텍스트로 보고 훑는다. 의미는 모르고 글자만 보는 방식이다. 이 방식의 문제는 두 가지다
- 관련 없는 매칭이 대거 잡혀 컨텍스트에 들어간다
- 한 번 컨텍스트에 들어간 토큰은 이후 대화 내내 계속 비용으로 쌓인다
검색에 1만 토큰을 썼다면, 같은 세션에서 추가 질문을 할 때마다 그 1만 토큰이 누적된다. 탐색 한 번이 잘못되면 세션 전체 비용이 부풀어 오르는 구조다
Serena가 하는 일
Serena는 LSP(Language Server Protocol) 위에서 IDE의 의미 기반 탐색을 MCP로 제공한다. find_symbol, find_referencing_symbols, insert_after_symbol 같은 심볼 단위 도구를 Claude가 직접 호출한다. 30개 이상 언어를 지원한다
[기존 grep 방식] "로그인" 키워드 → 변수명 · 주석 · 문자열 전부 매칭 → 컨텍스트 폭증 [Serena MCP 방식] "로그인" 의미 → LoginService 심볼 정의 · 호출처 → 필요한 코드만 컨텍스트
리팩토링에서도 위력이 다르다. AuthContext를 SessionContext로 바꾸려면 기존에는 30개 파일을 일일이 확인해야 했지만, Serena의 심볼 단위 도구를 쓰면 정의·참조를 한 번에 찾아 일괄 처리할 수 있다
설치는 마켓플레이스가 아니라 공식 Quick Start로
Serena 공식 README는 마켓플레이스 설치를 권장하지 않는다. 마켓플레이스에 들어 있는 설치 명령이 오래되거나 부적절할 수 있다는 이유로, 직접 Quick Start를 따르라고 안내한다. Serena는 Python 패키지 매니저 uv로 관리되므로 uv 설치가 선행되어야 한다
# 1. uv 설치 (macOS / Linux 예시) curl -LsSf https://astral.sh/uv/install.sh | sh # 2. Serena MCP 서버 옵션 확인 uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help # 3. Claude Code에 MCP로 전역 등록 (실사용 검증됨) claude mcp add --scope user serena -- \ uvx --from git+https://github.com/oraios/serena serena start-mcp-server \ --context claude-code --project-from-cwd
여기서 빠뜨리면 안 되는 두 가지 옵션이 있다
--scope user: 단일 프로젝트가 아니라 사용자 전역으로 등록한다. 빠지면 등록한 프로젝트에서만 동작해 다른 프로젝트에 들어갈 때마다 Serena가 보이지 않는 문제가 생긴다--context claude-code --project-from-cwd: Serena가 Claude Code 환경에 맞춰 동작하고, 현재 작업 디렉터리를 프로젝트 루트로 인식하게 한다
연결되면 로컬에서 Serena 대시보드가 뜨고, Claude Code 안에서 /mcp로 상태를 확인할 수 있다. 자연어 요청 시 의도한 MCP가 작동하지 않으면 프롬프트에 명시적으로 도구 이름을 적는다
Serena를 사용해서 GoogleLoginButton이 어디에서 쓰이는지 찾아줘
명시 호출이 한두 번 들어가면 이후에는 Claude가 해당 프로젝트에서 Serena를 우선 선택한다
Hookify – 같은 실수를 두 번 하지 않게 만드는 Harness 도구
Harness Engineering은 Mitchell Hashimoto가 정리한 개념으로, “에이전트가 실수할 때마다 그 실수가 다시는 발생하지 않도록 환경을 엔지니어링한다”는 원칙이다. AI를 탓하는 대신 같은 실수를 못 하도록 환경을 고친다는 뜻이다. Hookify는 이 원칙을 그대로 구현한 Anthropic 공식 플러그인이다
토큰 관점에서 잘못된 작업의 비용은 단순히 그 작업 자체가 아니다. 잘못 만든 결과물을 검토하고, 원인을 추궁하고, 수정 지시를 내리고, 재시도하는 사이클 전체가 비용이다. Hookify는 실수가 발생하기 전에 차단해 이 사이클을 통째로 없앤다
규칙은 마크다운 파일에 YAML frontmatter로 정의한다. 이벤트 타입은 bash 명령, 파일 편집, 사용자 프롬프트, 세션 종료 등이며 정규식 매칭을 지원한다. 변경은 Claude Code 재시작 없이 즉시 반영된다
Hookify 명령 정리
설치 후 자동완성으로 확인하면 메인 명령은 네임스페이스가 붙은 /hookify:hookify 형태로 나온다. 본문에서는 편의상 /hookify로 쓰지만, 실제 입력 시에는 자동완성이 채워주는 풀네임을 그대로 사용한다
| 명령 | 실제 자동완성 형태 | 동작 |
|---|---|---|
/hookify <자연어 설명> | /hookify:hookify <설명> | 설명에 맞는 규칙을 새로 생성 (예: rm -rf 사용 시 경고) |
/hookify (인자 없음) | /hookify:hookify | 최근 대화에서 사용자가 교정한 동작을 분석해 자동으로 규칙 생성 |
/hookify:list | /hookify:list | 현재 활성 규칙 목록 확인 |
/hookify:configure | /hookify:configure | 인터랙티브 규칙 관리 |
공식 페이지 문구를 그대로 옮기면 다음과 같다
/hookify:hookify Warn me when I use rm -rf commands /hookify:hookify Don't use console.log in TypeScript files
같은 실수가 반복된다는 느낌이 들면 인자 없이 /hookify:hookify만 실행하면 된다. 별도의 /hookify-extract 같은 명령은 없다. 인자 없는 /hookify:hookify가 그 역할을 한다
규칙 파일은 .claude 디렉터리 하위에 저장된다. frontmatter에 발동 시점을, 본문에 Claude가 따라야 할 지침을 둔다. 규칙 자체를 자산처럼 관리할 수 있는 구조다
네 도구를 함께 쓰면 절약 효과가 곱해진다
각 도구의 효과는 독립적이지만, 같이 쓰면 토큰 절약 사이클이 닫힌다
1. Session Report로 비싼 프롬프트와 캐시 적중률 확인 2. CLAUDE.md가 비대하면 claude-md-improver로 정리 3. 코드 탐색이 무거우면 Serena MCP로 의미 기반 전환 4. 같은 실수가 반복되면 Hookify로 차단 5. 다시 1번으로 돌아가 효과 측정
Session Report가 측정 지점, ClaudeMD Management와 Serena가 매 요청 비용을 줄이는 지점, Hookify가 재시도 비용을 없애는 지점이다. 어디서 새는지 모른 채 절약하려 들면 결국 또 새는데, 이 네 도구는 누수 지점을 차례대로 봉쇄한다
명령어를 쓰기 전에 한 번 더 확인할 것
플러그인 명령은 버전과 네임스페이스 정책에 따라 이름이 달라진다. 실사용에서도 차이가 확인됐다. 예를 들어 Hookify는 메인 명령이 /hookify가 아니라 자동완성에서 /hookify:hookify로 잡히고, ClaudeMD Management의 명령들도 /claude-md-management: 네임스페이스 아래에 들어 있다
확인 절차는 다음과 같다
- 플러그인 설치 →
/reload-plugins - 슬래시 입력 후
/<플러그인명>:까지 타이핑 - 자동완성 후보로 뜨는 실제 명령어명 사용
- 의심이 가면 공식 페이지(
claude.com/plugins/<name>) 교차 확인
특히 헷갈리기 쉬운 이름 두 가지를 다시 정리한다
/revise-claude-md— “Cloud”가 아니라 “Claude”claude-md-improver— 슬래시 명령이 아니라 스킬. 자연어 호출이 정상 경로
본문 표에 정리해 두었지만, 실제 실행 직전에 자동완성으로 한 번 더 확인하는 습관이 안전하다
정리
Claude Code 토큰 절약은 결국 네 가지 질문에 답하는 일이다. 어디서 새는가(Session Report), 시스템 프롬프트가 비대하지 않은가(ClaudeMD Management), 코드 탐색이 의미 기반인가(Serena), 같은 실수를 반복하지 않는가(Hookify). 이 네 개를 같이 들이면 같은 작업을 더 적은 토큰으로 끝낼 수 있다
출처 – 인프런 [클로드 코드 완벽 마스터: AI 개발 워크플로우 기초부터 실전까지]