Claude Code를 사용하다 보면, 프로젝트의 구성이나 작업 규칙을 CLAUDE.md에 작성하는 경우가 있습니다.

주요 목적 중 하나는 CLAUDE.md에 주요 파일이 적혀 있으면, Claude가 리포지토리(Repository) 내부를 수동으로 탐색할 필요가 없어진다는 점입니다.

파일 탐색이나 서브 에이전트(Sub-agent)의 기동을 생략할 수 있다면, 최종적인 토큰(Token) 소비는 줄어들지도 모릅니다.

그래서 이번에는 이것이 토큰 소비 관점에서 얼마나 효과가 있는지를 실제로 검증해 보고자 합니다.

내용으로는, 동일한 리포지토리에 대해

로그인 기능은 어떤 형태인가요?

라고 질문하고, 다음의 두 패턴으로 Claude Code에서 모델로 전송된 요청(Request)·응답(Response)을 비교했습니다.

• CLAUDE.md를 작성하기 전
• CLAUDE.md를 작성한 후

본 기사에서는 단순한 토큰 수 비교뿐만 아니라, Claude가 어떤 파일을 읽고, 어떤 도구(Tool)를 사용하며, 왜 호출 횟수에 차이가 발생했는지까지 실제 로그를 통해 추적합니다.

• WSL2 (Ubuntu) 환경
• Claude Code를 리버스 프록시(Reverse Proxy)를 통해 Amazon Bedrock (jp.anthropic.* 프로필)에 연결
• 모델은 claude-sonnet-5를 사용
• 조사 대상 리포지토리는 full-stack-fastapi-template (FastAPI + React 풀스택 템플릿)

이번 2회 실행은 완전히 조건을 고정한 벤치마크는 아닙니다. 따라서 "CLAUDE.md를 두면 항상 같은 비율로 절감할 수 있다"는 결과가 아니라, **이번 실행 로그에서 무엇이 일어났는지를 분석한 케이스 스터디(Case Study)**로 읽어주시기 바랍니다.

이번에 작성한 CLAUDE.md는 다음과 같습니다.

내용은 주로 리포지토리의 개요와 주요 파일의 역할입니다.

# CLAUDE.md
이 파일은, Claude Code (claude.ai/code)가 이 리포지토리에서 코드를 다룰 때의 가이던스를 제공합니다.
## 리포지토리 개요
...

이 CLAUDE.md는 24행, 1,297자입니다.

특정 질문에 대한 답을 미리 알려주는 식의 조건으로 만들지 않기 위해, "로그인 기능을 설명할 때는 이 5개 파일을 본다"와 같은 태스크(Task) 고유의 참조 지시는 넣지 않았습니다.

검증하는 것은 어디까지나 프로젝트 개요와 디렉토리 구성만으로, Claude의 탐색 경로가 어떻게 변하는가입니다.

먼저 "CLAUDE.md 없음"의 경우입니다.

총 14단계의 모델 실행이 진행되었습니다.

CLAUDE.md 없음 응답

로그인 기능 구현을 확인하기 위해 리포지토리를 조사합니다.
● Explore(Explore login/auth implementation)
Backgrounded agent (↓ to manage · ctrl+o to expand)
...

다음으로 CLAUDE.md 있음의 경우, 총 6단계의 모델 실행이 진행되었습니다.

CLAUDE.md 있음 응답

로그인 기능 구현을 확인하기 위해 관련 파일을 읽습니다.
Searched for 1 pattern, read 6 files, ran 1 shell command
로그인 기능은 백엔드(FastAPI + JWT)와 프론트엔드(React + TanStack Router)에서 다음과 같이 구현되어 있습니다.
...

저장된 모든 응답에 대해 usage를 합산했습니다.

CLAUDE.md 있음 측은 입력 토큰이 없음 측의 약 54.2%, 출력 토큰이 약 45.0%까지 줄어들었습니다. 합계로는 약 54.1%입니다.

단, 이 14회·6회라는 숫자에는 사용자에게 전달되는 최종 답변 이외의 내부 처리도 포함되어 있습니다.

• 대화 제목 생성
• 다음에 사용자가 입력할 법한 문장 생성
• 사용자가 돌아왔을 때의 대화 요약

따라서, 이것들을 제외하고 「로그인 기능을 조사하여 답변하는 처리」만을 집계해 보겠습니다.

본 답변에 필요한 처리만 보더라도, 입력은 약 45.9%, 합계는 약 46.0% 절감되었습니다.

CLAUDE.md가 없는 쪽의 처리를 역할별로 나누면 다음과 같습니다.

플로우 차트로 나타내면 이런 느낌입니다.

첫 번째 부모 AI는 로그인 기능이 어디에 있는지 스스로 조사하지 않고, Agent 도구를 통해 **Explore 서브 에이전트 (Explore sub-agent)**를 기동했습니다.

Explore AI란

Explore AI는 Claude Code에 내장된 읽기 전용 서브 에이전트입니다. 파일의 위치를 찾거나 코드 내의 심볼을 검색하는 역할을 수행합니다.

CLAUDE.md가 있는 쪽에서는 디렉터리 구성을 입구로 삼아, 실제 코드의 의존 관계를 따라가는 3단계 조사가 이루어졌습니다.

Claude는 CLAUDE.md의 디렉터리 구성으로부터 직접 관련이 있다고 판단한 다음 4개 파일을 첫 번째 응답에서 병렬로 읽었습니다.

backend/app/api/routes/login.py
backend/app/core/security.py
frontend/src/hooks/useAuth.ts
frontend/src/routes/login.tsx

그 후, login.py의 import와 함수 호출을 단서로 다음 2개 파일로 조사를 확장했습니다.

backend/app/api/deps.py
backend/app/crud.py

deps.py는 파일 전체를 읽은 후, 구문 오류(Syntax error)가 의심되는 해당 행을 다시 부분적으로 읽었습니다. crud.py 또한 처음에 authenticate() 주변을 grep한 뒤, 그 후에 앞부분 65행을 읽었습니다.

플로우 차트로 나타내면 이런 느낌입니다.

Explore AI와 find는 사용되지 않았습니다. 도구 실행은 Read가 7회, grep이 1회로 총 8회입니다.

내용을 확인한 유니크 파일은 6개였습니다.

여기서 주의해야 할 점은, CLAUDE.md의 내용이 매번 모델에 전달된다는 것입니다.

첫 번째 Sonnet 호출만을 비교하면, CLAUDE.md가 있는 쪽의 입력은 증가했습니다.

첫 번째 호출만 따지면, CLAUDE.md가 있는 쪽이 약 2.1% 더 많은 결과입니다.

이 차이인 1,323 토큰을 모두 CLAUDE.md의 비용이라고 단정할 수는 없습니다. 이용 가능한 도구 수도 없는 쪽이 36개, 있는 쪽이 37개로 1개 차이가 났습니다.

하지만 지금까지 검증한 결과, CLAUDE.md는 **후속 탐색 비용을 절감하기 위한 인덱스 (Index)**로서 기능하며, 토큰 소비로 이어지고 있음을 알 수 있습니다.

즉, CLAUDE.md는 AI가 업무를 수행하는 데 필요한 정보를 간결하게 정리해 둠으로써, 증가하는 토큰 수 이상의 역할을 해줍니다.

코드 내용까지 확인한 유니크 파일 수는 없는 쪽이 11개, 있는 쪽이 6개였습니다.

없음(なし) 쪽에서는, 게다가 다음 파일명도 find로 나열했습니다. 다만, 내용까지는 읽지 않았습니다.

frontend/src/components/Common/AuthLayout.tsx

frontend/src/routes/recover-password.tsx

frontend/src/routes/reset-password.tsx

frontend/src/client/

하위 생성 파일 backend/tests/utils/user.py

backend/tests/crud/test_user.py

backend/tests/api/routes/test_users.py

CLAUDE.md

있음(あり) 쪽에서는, CLAUDE.md를 Read 툴로 연 것이 아닙니다.

Claude Code의 하네스(Harness)가 내용을 자동으로 가져와서, system-reminder로서 모델 입력에 포함시키고 있습니다.

툴마다 고정된 토큰 수가 있는 것은 아니며, 영향량은 커맨드의 길이, 검색 결과 수, 파일 크기에 따라 달라지지만,

각 커맨드 결과 사이즈에서는 대략 다음 순서일 것입니다.

find < grep < Read

Read가 많은 CLAUDE.md 없음(なし)은 필연적으로 소비 토큰 수도 많아집니다...

하지만, 정말 큰 요인은 툴 결과 사이즈만은 아닙니다.

Explore AI의 입력 토큰은, 툴 실행이 진행됨에 따라 다음과 같이 증가했습니다.

27,281
↓ find 결과를 추가
28,276
...

매번 새로운 결과만 전송되는 것이 아닙니다. 그전까지의 대화, 시스템 지시(System Instruction), 툴 정의(Tool Definition), 과거의 툴 호출(Tool Call), 과거의 실행 결과가 다시 입력에 포함됩니다.

첫 번째 입력 27,281 토큰을 7번 반복하는 것만으로도 다음 양이 됩니다.

27,281 × 7 = 190,967 토큰

실제 Explore AI의 입력 합계는 255,680 토큰이었습니다.

툴을 사용할 때마다 다음 모델 호출이 필요해지고, 거대한 기본 컨텍스트가 재전송되어 버립니다.

CLAUDE.md 있음(あり)에서는, 진입점인 4개 파일을 하나씩 읽지 않고, 한 번의 모델 응답으로 4개의 Read를 병렬로 발행했습니다.

모델 호출
↓
Read × 4를 병렬 실행
...

처음 4개 파일을 한 트어닝에 모은 점은 효율적이었습니다.

반면, 의존처 확인과 문제 지점 재확인이 필요했기 때문에, 본 답변까지의 모델 호출은 총 4회가 되었습니다.

본 답변 처리의 첫 입력 65,602 토큰을 4번 분으로 늘리면 262,408 토큰입니다. 실제 입력 283,263 토큰과의 차이인 20,855 토큰이, 툴 호출 및 결과 누적분입니다.

독립된 파일은 같은 턴에 묶어서 처리하되, 의존 대상에 대한 추가 확인은 대상 행을 좁히는 것이 중요합니다.

prompt_tokens에는 프롬프트 캐시 (Prompt Cache)로부터 읽어온 토큰도 포함되어 있습니다.

CLAUDE.md가 없는 쪽은 모델 호출이 많기 때문에, 동일한 시스템 프롬프트나 툴 정의를 반복해서 캐시로부터 읽고 있습니다. 입력의 86.4%가 캐시 읽기였습니다.

따라서 이번의 "입력 45.8% 절감"을 그대로 "비용 45.8% 절감"으로 생각할 수는 없습니다.

일반 입력, 캐시 생성, 캐시 읽기는 요금 체계가 다르기 때문입니다.

한편, raw token 수는 레이턴시(Latency)나 컨텍스트(Context) 양을 파악하는 데 사용할 수 있으므로, 호출 경로를 비교하는 지표로서는 유효합니다.

CLAUDE.md가 없는 쪽은 11개 파일, 있는 쪽은 6개 파일을 확인했지만, 로그인 기능의 설명 내용에는 큰 차이가 없었습니다.

또한, 양쪽 모두 backend/app/api/deps.py:36의 구문 오류를 발견했습니다. 이번 질문에 대해서는 CLAUDE.md가 있는 쪽이 조사 대상을 좁혔음에도 불구하고 중요한 정보를 놓쳤다고는 확인되지 않았습니다.

즉, 이번에는 확인 파일 수와 토큰 소비를 줄이면서도 주요 답변 내용을 유지할 수 있었던 결과입니다.

이번 결과로부터 효과가 큰 순서대로 정리합니다.

단, 과도하게 대책을 세우면 반대로 AI의 동작을 너무 제한하게 될 수 있으므로, **"토큰 효율과 조사 품질의 트레이드오프 (Trade-off)"**라는 점에 주의하십시오.

가장 효과가 큰 대책입니다.

피해야 할 방식
검색 → 판단 → Read → 판단 → Read → 판단 → Read
권장 방식
...

1회당 결과를 수백 토큰 줄이는 것보다, 모델 호출을 1회 줄이는 것이 더 크게 작용하는 경우가 있습니다.

구현 상세를 모두 적는 것이 아니라, 다음 정보를 짧게 기재합니다.

• 프로젝트 개요
• 주요 디렉토리
• 기능별 진입 파일
• 관련 백엔드 · 프론트엔드 · 테스트
• 조사 목적별 참조 범위
• 해서는 안 되는 탐색이나 불필요한 서브 에이전트 (Sub-agent) 기동

이번 검증에서는 태스크 고유의 참조 지시를 적지 않아도, 다음과 같이 역할이 부여된 디렉토리 목록만으로 탐색 경로가 짧아졌습니다.

## 디렉토리 구성
- `backend/app/api/routes/login.py` — 로그인 · 비밀번호 재설정 API.
- `backend/app/core/security.py` — JWT 생성 및 비밀번호 해싱.
...

특정 질문에 대해 "이 파일을 읽어라"라고 답을 미리 심어두는 것이 아니라, 각 디렉토리나 주요 파일의 역할을 색인(Index)으로서 작성하는 것이 포인트입니다.

읽어야 할 파일이 정해져 있다면, 하나씩이 아니라 같은 응답에서 묶어서 Read 합니다.

피해야 할 방식
Read A → 모델 → Read B → 모델 → Read C
권장 방식
...

다음과 같은 경우에는 상위 AI가 직접 조사하는 것이 효율적입니다.

• 주요 파일이 CLAUDE.md에 적혀 있음
• 읽어야 할 파일이 몇 개 정도임
• 한 번의 병렬 Read로 조사가 가능함
• 단일 기능의 개요 설명

반면, 다음과 같은 경우에는 Explore AI가 가치가 있습니다.

• 구현 위치를 모를 때
• 대규모 리포지토리를 횡단할 때
• 여러 개의 독립적인 조사를 병렬화할 때
• 상위 AI와 탐색용 컨텍스트를 분리하고 싶을 때

서브 에이전트를 사용할 때도 대상 디렉토리, 최대 툴 호출 횟수, 보고 글자 수를 지정하면 팽창을 억제할 수 있습니다.

대상 파일이 불분명한 경우에는 다음 순서로 범위를 좁힙니다.

rg --files / rg -l로 후보를 좁힘
↓
rg -n으로 관련 행을 확인
...

• 대상 디렉토리를 한정한다
• 일치 건수를 제한한다
• node_modules

또는 생성물을 제외한다 - 큰 파일은 행 범위를 지정한다

• 락 파일 (Lock file)을 전체로 읽지 않는다

이번 '없음' 케이스에서는 Explore AI가 deps.py를 읽은 후, 상위 AI가 동일한 파일을 다시 읽고 있습니다. '있음' 케이스에서도 deps.py 전체를 읽은 후에 해당 행을 재독해(re-read)하고 있으며, crud.py는 grep 이후에 부분적으로 Read 하고 있습니다.

서브 에이전트 (Sub-agent)에게 파일 전체를 보고하게 하는 대신, 다음 형식으로 반환하게 하면 재독해 범위를 줄일 수 있습니다.

- 파일 경로
- 행 번호
- 근거가 되는 코드 5행 이내
...

상위 AI가 확인할 때도 해당 행 주변만 읽습니다.

이번에는 짧은 질문임에도 불구하고 첫 입력이 약 64,000~66,000 토큰(Token)에 달했습니다. 사용자의 질문보다 시스템 지시 (System instruction), 도구 정의 (Tool definition), Skill 목록, MCP 도구의 스키마 등이 큰 비중을 차지하고 있습니다.

사용하지 않는 MCP나 Skill을 항상 활성화해 두면, 모델 호출 (Model call) 시마다 기본 입력에 포함됩니다.

• 프로젝트에서 사용하지 않는 MCP를 제거한다
• 용도별로 유효한 도구를 분리한다
• 사용하지 않는 Skill 패키지를 항상 로드하지 않는다
• IDE 연동이 필요 없다면 IDE 도구를 줄인다

기본 입력을 1,000 토큰 줄이면, 10번의 모델 호출 시 약 10,000 입력 토큰의 차이가 발생합니다.

도구 (Tool) 등이 토큰 양에 미치는 영향에 대해서는 별도의 기사에 정리해 두었습니다.

괜찮으시다면 확인해 주세요.

이번 결과를 실무용 플로우로 정리하면 다음과 같습니다.

이번에 동일한 "로그인 기능은 어떤 것인가요?"라는 질문을 CLAUDE.md의 유무에 따라 비교했습니다.

포인트는 다음 세 가지입니다.

1. CLAUDE.md 자체는 입력 토큰을 늘리지만, 그 이상으로 탐색·서브 에이전트·모델과의 왕복을 줄이는 효과가 컸다
2. 토큰 절감에 가장 효과적인 것은, 한 번의 Read를 작게 만드는 것보다 모델 호출 횟수를 줄이는 것이었다
3. 따라서 CLAUDE.md에는 특정 질문에 대한 답을 쓰는 것이 아니라,

• 프로젝트 개요
• 주요 디렉토리와 역할
• 기능의 진입점이 되는 파일
• 테스트나 설정 파일의 위치

를 간결한 색인 (Index)으로서 작성하는 것이 좋아 보입니다.

CLAUDE.md는 "모델이 준수해야 할 규칙 모음"인 동시에, 리포지토리 탐색을 단축하기 위한 색인으로 설계함으로써 토큰 소비를 크게 억제할 수 있다는 것을 이번 로그를 통해 확인할 수 있었습니다.