Claude Code를 본격적인 코딩 작업에 사용해 본 결과, 가장 큰 교훈은 단순합니다. 토큰 소비는 주로 가격의 문제가 아니라 워크플로우 (Workflow)의 문제입니다.

Claude Code 세션이 지저분해지면 성능이 떨어집니다. 관련 없는 파일을 다시 읽기 시작하고, 실패한 시도들을 기억하며, 오래된 로그를 계속 들고 다니고, 더 이상 중요하지 않은 것들에 컨텍스트 (Context)를 낭비하게 됩니다.

그래서 저의 워크플로우는 하나의 원칙을 중심으로 구축되었습니다:

Claude의 활성 컨텍스트 (Active Context)를 작고, 깨끗하며, 유용하게 유지하는 것.

다음은 제가 매일 사용하며 여러분에게도 도움이 될 수 있는, Claude Code에서 토큰 소비를 줄이는 9가지 최선의 방법입니다.

tldr; (요약)

• 원시 로그 (Raw logs)나 전체 테스트 결과를 보내지 마세요. 필터와 간단한 명령 래퍼 (Command wrappers)를 사용하여 에러, 스택 트레이스 (Stack trace), 핵심 세부 사항 등 중요한 것만 보여주세요.

• Sonnet은 대부분의 코딩 작업을 잘 처리하며 비용도 저렴합니다. 정말 어려운 문제에는 Opus를 사용하세요. 보조 작업이나 탐색에는 Haiku를 사용하세요.

• 단순한 수정 작업에 비용이 많이 드는 모델을 실행하지 마세요. 깊은 추론이 필요하지 않을 때는 확장된 사고 (Extended thinking) 기능을 끄세요.

• 정리 작업을 수행하는 동안 중요한 내용은 유지하면서 /compact를 사용하세요.

• 완전히 다른 작업으로 전환할 때는 핸드오프 파일 (Handoff file)과 함께 /clear를 사용하세요. 이렇게 하면 이전의 실패한 시도들이 컨텍스트 메모리에 쌓이는 것을 방지할 수 있습니다.

• Claude가 항상 필요로 하는 지침(테스트 실행 방법, 빌드 명령, 폴더 구조, 주요 규칙 등)만 포함하세요. 그 외의 모든 것은 별도의 스킬 파일 (Skill files)에 보관하고 실제로 필요할 때만 로드하여 토큰을 절약하세요.

• 30개 이상의 활성 서버를 번갈아 사용하는 대신, Composio MCP를 사용하여 1000개 이상의 도구를 단일 시스템으로 관리하세요. 작업이 셸 명령 (Shell commands)을 사용하기에 충분히 간단하다면 Composio CLI를 사용하세요.

1. Claude가 확인하기 전에 도구 출력값을 필터링하세요. 원시 로그 (Raw logs)는 컨텍스트에 있어 쓰레기나 다름없습니다. Claude에게 10,000줄짜리 테스트 출력 결과는 필요하지 않습니다. 대신 실패한 테스트, 스택 트레이스 (Stack trace), 예상값 대 실제값, 그리고 아마도 변경된 파일들이 필요할 것입니다.

그래서 저는 다음과 같은 방식은 피합니다:

npm test

대신 필터링된 명령을 사용합니다:

npm test 2>&1 | grep -A 5 -E "FAIL|ERROR|Error|Expected|Received" | head -100

저의 이상적인 설정에서는 아래와 같이 작은 래퍼(wrapper)들을 만들어 필요할 때 사용합니다:

cc-test
cc-lint
cc-typecheck
...

여기서 핵심은 Claude가 터미널의 노이즈(noise)가 아닌 요약본(summaries)을 소비하게 만드는 것입니다.

이 한 가지 변화는 컨텍스트 오염(context pollution)이 시작되기도 전에 방지해주기 때문에 가장 많은 토큰을 절약해 줍니다.

1. 작업에 맞는 모델 선택하기
   모든 작업에 동일한 성능이 필요한 것은 아닙니다. 모든 작업에 Opus를 실행하는 것은 Claude Code에서 가장 비용이 많이 드는 습관 중 하나입니다. 대부분의 코딩 작업에는 Opus가 필요하지 않습니다. Sonnet은 훨씬 적은 비용으로 이를 처리할 수 있습니다.

저의 설정:

/model sonnet   → 대부분의 코딩 작업용 기본값
/model opus     → 복잡한 아키텍처, 심층 추론, 까다로운 버그
/model haiku    → 반복적인 작업, 보일러플레이트(boilerplate), 빠른 조회

저는 진정으로 더 깊은 추론이 필요할 때만 Opus로 전환하고, 어려운 부분이 끝나면 즉시 다시 돌아옵니다.

특히 서브에이전트(subagents)의 경우, 다음과 같이 설정합니다:

CLAUDE_CODE_SUBAGENT_MODEL=haiku

이는 탐색 에이전트(exploration agents), 로그 검사 에이전트(log inspectors), 문서 조회 에이전트(doc-lookup agents)가 모두 Haiku에서 실행됨을 의미합니다. 메인 스레드는 Sonnet을 유지합니다.

확장된 사고(Extended thinking)는 또 다른 숨겨진 비용입니다. 내부 추론을 위해 출력 토큰(output tokens)을 소모하기 때문입니다. 간단한 편집의 경우 이를 비활성화합니다:

MAX_THINKING_TOKENS=0      → 사소한 작업
MAX_THINKING_TOKENS=10000  → 아키텍처 추론

사실 이 접근 방식은 매우 효과적이어서, 5시간 제한이 리셋되기 전에 컨텍스트 메모리(context memory)가 가득 차는 일이 거의 없습니다. 기본적으로 무제한 사용이 가능한 셈입니다!

결론: 모든 것에 Opus를 사용하는 것은 모든 데이터베이스 쿼리를 가장 비싼 운영 서버에서 실행하는 것과 같습니다. 작업에 맞춰 모델을 선택하세요.

3. /clear + /compact + handoffs를 사용하여 하나의 세션이 영원히 지속되지 않게 하세요

충분한 턴(turns)이 지나면, 컨텍스트는 이전의 시도들, 잘못된 이론들, 오래된 파일 읽기, 그리고 구식 결정들로 가득 차게 됩니다. Claude가 여전히 모든 것을 기억하고 있더라도, 그 메모리의 상당 부분은 이제 독성(toxic)을 띠게 됩니다.

그래서 저는 /clear를 사용하되, 다른 워크플로우(workflow)를 적용합니다. 저는 handoff.md 파일을 생성하여 목표, 변경된 파일, 결정된 사항 등 필요한 모든 관련 세부 정보를 포함합니다.

여러분도 다음과 같이 할 수 있습니다.

클리어(clearing) 하기 전:
Claude에게 .claude/session-handoff.md를 작성하도록 요청합니다.

...

그다음 저는 다음을 실행합니다:

/clear

그리고 다음과 같이 재시작합니다:

.claude/session-handoff.md를 읽고 계속 진행해.

이렇게 하면 진행 상황을 잃지 않으면서도 새로운 컨텍스트(context)를 얻는, 두 마리 토끼를 모두 잡을 수 있습니다.

전체 리셋 없이 작업 중간에 정리하고 싶을 때는 대신 /compact를 사용합니다. 하지만 저는 결코 맹목적으로 실행하지 않습니다. 압축(compacting)하기 전에 Claude에게 무엇을 보존해야 하는지 정확히 알려줍니다:

/compact 보존할 내용: 사용자 업데이트를 위한 낙관적 잠금(optimistic locking), 이번 세션에서는 스키마 변경 없음.

그다음:

/compact

이렇게 하면 요약본이 무엇을 포착할지 결정됩니다. 요컨대, 노이즈(noise)는 제거하면서 중요한 결정 사항들은 컨텍스트에 추가됩니다.

차이점 (반드시 알아두어야 할 사항):

• /compact: 더 가벼운 컨텍스트가 필요한 작업을 위해, 요약하고 계속 진행합니다.
• /clear: 전환이 필요하거나 새로 시작해야 하는 작업을 위해, 핸드오프(handoff) 파일과 함께 전체 리셋을 수행합니다.

결론: /clear를 단순한 리셋 버튼으로 취급하지 마세요. 컨텍스트 가비지 컬렉션(context garbage collection)으로 취급하세요. 작업 도중의 가비지 컬렉션에는 지침과 함께 /compact를 사용하세요.

4. CLAUDE.md를 최소한으로 유지하기

대부분의 사람들은 CLAUDE.md에 너무 많은 정보를 담습니다. 아키텍처 노트, 배포 단계, PR 규칙, 디버깅 체크리스트, 스타일 가이드, 테스트 철학, 그리고 무작위적인 프로젝트 이력까지 추가하곤 합니다.

그것이 정리된 것처럼 느껴질 수 있지만, 매 세션마다 조용히 컨텍스트를 태워버립니다.

저의 규칙은 다음과 같습니다:

Claude가 세션의 80%에서 해당 정보가 필요하지 않다면, 그것은 CLAUDE.md에 포함되어서는 안 된다.

저의 CLAUDE.md에는 오직 다음 내용만 포함됩니다:

- 패키지 매니저 (package manager)
- 테스트 명령 (test command)
- 빌드 명령 (build command)
...

그 외의 모든 것은 skills 폴더나 별도의 docs 폴더로 들어갑니다.

예시:

.claude/skills/db-migration/SKILL.md
.claude/skills/pr-review/SKILL.md
.claude/skills/prod-debugging/SKILL.md

결론: 기본 컨텍스트 (base context)를 가볍게 유지하세요. 긴 워크플로우 (workflow)는 필요할 때만 로드하여 컨텍스트의 품질을 온전하게 유지합니다.

5. 코드를 수정하기 전에 플랜 모드 (plan mode)를 사용하세요

대부분의 컨텍스트 낭비는 Claude가 명확한 계획 없이 바로 구현 (implementation) 단계로 뛰어들 때 발생합니다.

Claude는 추측성으로 파일을 읽고, 특정 방식을 시도했다가, 다시 되돌아오고(backtracks), 더 많은 파일을 읽습니다. 작동하는 솔루션에 도달할 때쯤이면 세션은 이미 실패한 시도들로 오염된 상태가 됩니다.

플랜 모드 (plan mode)는 쓰기 및 수정 도구 (write-and-modify tool)에 대한 접근을 제한함으로써 사고(thinking)와 실행(doing)을 분리합니다.

저는 사소하지 않은 작업을 하기 전에 Shift+Tab을 두 번 누릅니다.

Shift+Tab → 플랜 모드 (plan mode) 활성화

플랜 모드에서 Claude는 어떠한 변경도 가하지 않은 채 파일을 읽고 문제를 추론 (reasoning)합니다. 저는 Claude가 의존성 (dependencies)을 매핑하고 미지의 요소 (unknowns)를 드러내도록 둡니다.

그런 다음 Claude가 단 한 줄의 코드도 작성하기 전에 Ctrl+G를 눌러 플랜을 직접 열고 편집합니다.

나쁜 프롬프트 (계획 없음):

로그인 시스템에 Google OAuth를 추가해줘.

더 나은 워크플로우 (workflow):

[플랜 모드 활성화]
Google OAuth를 추가하고 싶어. 어떤 파일들을 변경해야 할까?
세션 흐름 (session flow)은 어떻게 되지? 계획을 세워줘.
...

[플랜 모드 비활성화]
이제 계획에 따라 구현해줘.

결론: Claude가 처음부터 올바른 문제를 해결하게 하는 것이 재작업 (rework)을 하는 것보다 항상 비용이 저렴합니다. Claude가 계획하고, 검증하고, 그 다음에 실행하게 하세요.

6. 노이즈가 많은 탐색에는 제한된 서브에이전트 (subagents)를 사용하세요

서브에이전트 (subagents)는 유용하지만, 길을 잃는 경향이 있으므로 엄격하게 제어될 때만 유효합니다.

저는 다음과 같이 프롬프트를 작성하지 않습니다:

저장소 (repo)를 조사해줘.

대신 다음과 같이 프롬프트를 작성합니다:

src/auth와 tests/auth만 검사해줘.
최대 15개의 불렛 포인트 (bullets)로 반환해줘.
정확한 파일명을 포함해줘.
...

일반적으로 저는 로그 분석 (log analysis), 테스트 실패 조사 (test failure inspection), 의존성 검색 (dependency search), 문서 조회 (doc lookup), 그리고 영향 범위 분석 (blast radius analysis)과 같이 노이즈가 많은 작업에 Claude 서브에이전트를 사용합니다.

이러한 멀티 에이전트 협업 (multi-agent collaboration)은 단일 에이전트 방식보다 더 깔끔한 워크플로우를 제공합니다.

결론: 메인 Claude 세션이 모든 탐색 과정을 떠안아서는 안 됩니다. 메인 세션은 각 에이전트로부터 압축된 결과 (compressed result)만을 전달받아야 합니다.

7. 정밀한 저장소 탐색(Surgical repo navigation) 강제하기

저는 Claude에게 "코드베이스를 이해하고 나에게 설명해줘"라고 요청하지 않습니다.

그러한 요청은 대개 잘못된 파일들을 광범위하게 스캔하게 만들어 불필요한 컨텍스트 (context) 사용을 초래하며, 최근에는 에이전트가 저장소 내부에 직접 문서를 생성하는 문제까지 발생합니다.

대신, 저는 다음과 같은 내용이 담긴 docs/repo_map.md를 생성합니다:

- 주요 엔트리포인트 (main entrypoints)
- 핵심 모듈 (key modules)
- 테스트 명령 (test commands)
...

그 다음 그에 맞춰 프롬프트를 작성합니다. 제가 의미하는 바를 보여주는 예시는 다음과 같습니다.

나쁜 프롬프트:

인증 시스템을 이해하고 버그를 수정해줘.

더 나은 프롬프트:

로그인 엔트리포인트를 찾아줘. 토큰 검증 (token validation)을 설명하는 데 필요한 파일만 읽어줘. 관련 없는 디렉토리는 스캔하지 마.

Claude가 저장소를 헤매며 구조를 파악하는 대신 맵 (map)에서 시작하기 때문에, 이 방식은 많은 토큰을 절약해 줍니다.

결론: 저장소 맵 (Repo Maps)은 잘못된 파일 읽기를 줄여 컨텍스트 사용량을 감소시킵니다.

8. 점진적 공개 (Progressive disclosure)를 위한 스킬(Skills) 및 플러그인 활용

CLAUDE.md에서 내용을 꺼내는 것은, 옮겨진 위치 또한 매 세션마다 로드되지 않을 때만 도움이 됩니다. 그것이 바로 스킬 (skills)이 존재하는 이유입니다.

스킬은 단순히 SKILL.md가 포함된 폴더입니다 (SKILL.md에는 짧은 이름 + 설명, 지침, 그리고 참조 파일이나 스크립트가 포함됩니다). 이 방식의 이점은 로드 방식에 있습니다. 세션이 시작될 때 Claude는 각 Claude skill의 이름과 설명만을 보게 되며, 이는 각각 대략 30~100 토큰 정도입니다.

전체 SKILL.md 본문은 Claude가 해당 스킬이 관련이 있다고 판단할 때만 로드되며, 포함된 참조 파일이나 스크립트도 실제로 필요할 때만 로드됩니다.

따라서 저는 비용을 미리 지불하지 않고도 심도 있는 워크플로우를 유지할 수 있습니다:

.claude/skills/db-migration/SKILL.md
.claude/skills/pr-review/SKILL.md
.claude/skills/prod-debugging/SKILL.md

이러한 스킬 8개가 프로젝트에 있더라도, 작업을 시작하기 전에 수천 줄의 코드를 컨텍스트에 쏟아붓는 대신 시작 시점에 단 몇 백 토큰만 소모하게 됩니다.

여기서는 설명(description)이 모든 핵심적인 역할을 수행하므로, 저는 이를 구체적으로 작성합니다. "문서 작업에 도움을 줌"이라는 표현은 작동하지 않습니다. 하지만 "PDF 양식 채우기 및 테이블 데이터 추출 시 사용"과 같은 표현은 작동합니다.

플러그인(Plugins)은 그다음 단계의 계층입니다. 플러그인은 기술(skills), 슬래시 명령어(slash commands), 하위 에이전트(subagents), 훅(hooks), 그리고 MCP 서버를 하나의 설치 가능한 단위로 묶으며, 필요에 따라 전체 번들을 활성화하거나 비활성화할 수 있습니다:

/plugin marketplace add <marketplace>
/plugin add <plugin>

핵심은 이 포스트의 다른 모든 내용과 동일합니다. 즉, 사용하지 않는 기능(dormant capability)을 활성 컨텍스트(active context)에서 제외하는 것입니다. 프로젝트에 필요할 때 플러그인을 설치하고, 필요하지 않을 때는 비활성화하여 사용하지 않는 도구를 계속 들고 다니지 마세요.

잘못된 설정:

모든 것을 "항상 사용 가능"하도록 CLAUDE.md에 몰아넣기

더 나은 설정:

아주 작은 CLAUDE.md. 명확한 설명이 포함된 기술(skills) 형태의 긴 워크플로우. 프로젝트별로 전환 가능한 플러그인 형태의 기능 세트.

9. Composio MCP 및 CLI 사용하기

MCP가 도입된 이후 제가 겪은 가장 큰 병목 현상 중 하나는 30개 이상의 MCP 통합(integrations)을 관리하는 것이었습니다. MCP 서버를 적게 사용하면 작업이 완료되지 않고, 너무 많이 사용하면 컨텍스트 메모리(context memory)가 늘어납니다.

Composio는 MCP를 지원하는 모든 에이전트에 연결할 수 있는 범용 MCP 서버를 제공함으로써 이 문제를 해결해 주었습니다. 이를 통해 1,000개 이상의 서비스 및 도구에 연결할 수 있으며, 온디맨드 도구 로딩(on-demand tool loading), 도구 구성을 위한 원격 워크벤치(remote workbench), 그리고 스크립팅으로 예외 상황을 처리할 수 있는 bash 도구를 제공합니다.

다음은 Linear, GitHub, Sentry, Supabase, Context7과 같은 도구를 사용하는 작업에서 Composio MCP를 사용할 때와 사용하지 않을 때의 토큰 절감 효과를 간략하게 비교한 것입니다.

Composio MCP 미사용 시

Composio MCP 사용 시