Claude Code 토큰 절약 방법: 탐색 위임과 출력 압축으로 컨텍스트를 아낀 다섯 가지 습관

Claude Code 같은 AI 코딩 에이전트를 매일 쓰다 보면 어느 순간 토큰이 신경 쓰이기 시작합니다. 종량제 과금이면 바로 돈이고, 구독제여도 한도에 걸리면 월 중후반에 도구가 무력화됩니다. 그리고 비용보다 더 크게 다가온 게 하나 있었습니다. 컨텍스트 윈도우입니다. 토큰을 아끼는 습관은 결국 에이전트가 한 세션에서 더 길고 정확하게 일하게 만드는 습관이었습니다.

정답을 처음부터 안 건 아니고, 몇 달 동안 이것저것 붙였다 뗐다 하면서 남은 것들만 정리합니다.

탐색은 서브에이전트에게, 결론만 받는다#

제일 효과가 컸던 습관입니다. "이 기능 어디서 처리하는지 찾아줘" 같은 탐색 작업을 메인 대화에서 직접 시키면, 에이전트가 파일을 열 때마다 그 내용이 전부 메인 컨텍스트에 쌓입니다. 파일 열 개 뒤지고 나면 정작 코드 수정을 시작하기도 전에 컨텍스트가 잡동사니로 가득 찹니다.

그래서 규칙을 만들었습니다. 파일 3개 이상 뒤져야 하는 탐색은 무조건 서브에이전트에 위임하고, 메인에는 요약만 돌려받습니다. 서브에이전트가 중간에 읽은 파일 내용은 서브에이전트의 컨텍스트에서만 소비되고 버려집니다. 메인 대화에는 "인증 로직은 이 파일의 이 함수, 미들웨어는 여기" 같은 결론 몇 줄만 남습니다.

• 탐색·수집·로그 확인 → 위임, 요약만 수신
• 실제 코드 수정 → 메인에서 직접
• 서로 독립인 탐색은 병렬로 동시에 던지기

이 분업 하나로 세션 수명이 눈에 띄게 길어졌습니다.

출력을 짧게 강제하는 규칙 파일#

에이전트의 기본 출력은 친절합니다. 그리고 그 친절이 전부 출력 토큰입니다. 코드 한 줄 고치고 나서 "이 변경으로 무엇이 개선되었는지" 세 문단으로 설명해 주는 걸 매번 읽고 있을 필요가 없습니다.

전역 설정 파일(Claude Code라면 CLAUDE.md)에 출력 규칙을 박아두면 모든 세션에 적용됩니다. 제가 쓰는 건 대략 이런 내용입니다.

# Output
- 짧게, 핵심만. 불필요한 헤더/불릿/요약 자제.
- 결론 먼저 1~2줄, 디테일은 요청 시에만.
- 긴 내용은 채팅 본문이 아니라 파일/코드/실행결과로
  떨어뜨리고, 채팅엔 위치 + 한 줄 요약만.

마지막 줄이 포인트입니다. 긴 분석 결과를 채팅으로 출력하게 두지 말고 파일로 쓰게 하면, 같은 정보가 대화 히스토리에 계속 실려 다니지 않습니다. 커뮤니티에는 출력을 전보문 수준으로 압축하는 더 극단적인 규칙 세트들도 공개돼 있는데, 절감률 수치는 대부분 자체 벤치마크라 그대로 믿기보다는 직접 붙여보고 판단하는 게 낫습니다. 체감상 주는 건 확실합니다.

CLI 출력은 걸러서 먹인다#

에이전트가 터미널 명령을 실행하면 그 출력이 전부 컨텍스트로 들어갑니다. 테스트 한 번 돌리면 통과한 케이스 수백 줄이 딸려 오고, 빌드 로그는 진행률 바까지 통째로 들어옵니다. 에이전트한테 필요한 건 "뭐가 실패했나" 한 줄인데요.

간단하게는 명령 자체를 필터링하는 습관부터 시작할 수 있습니다.

# 실패한 것만 보여주기
npm test 2>&1 | grep -E "FAIL|✕|Error" | head -20
 
# 마지막 결과 요약만
npm run build 2>&1 | tail -5

여기서 더 나아가면, 자주 쓰는 CLI 명령의 출력에서 불필요한 라인을 자동으로 걷어내는 프록시 도구를 끼우는 방법이 있습니다. git status, 테스트 러너, 패키지 매니저 출력을 에이전트에게 전달하기 전에 필터링해 주는 오픈소스 도구들이 나와 있습니다. 훅으로 명령을 자동 치환하게 걸어두면 습관을 따로 의식할 필요도 없어집니다. 이 계열은 프롬프트 규칙과 달리 지시문 오버헤드가 없다는 게 장점입니다.

긴 파일은 통째로 읽지 않는다#

2,000줄짜리 파일에서 함수 하나 고치는데 파일 전체를 읽어 들이는 건 낭비입니다. 에이전트 도구는 대개 파일을 오프셋과 줄 수를 지정해 부분적으로 읽을 수 있습니다. "이 파일의 몇 번째 줄 근처만 봐" 또는 "이 함수만 찾아서 읽어"라고 지시하는 것만으로도 큰 파일 작업의 토큰이 뚝 떨어집니다.

같은 맥락에서, 이미 읽은 파일을 확인차 다시 읽게 두지 않는 것도 습관입니다. 수정이 실패했으면 도구가 에러를 냈을 테니, "잘 됐는지 다시 읽어봐"는 대부분 불필요한 재독입니다.

컨텍스트 오염이 진짜 비용이다#

앞의 습관들을 관통하는 관점이 하나 있습니다. 토큰 절감의 본질은 개별 호출을 싸게 만드는 게 아니라 컨텍스트를 깨끗하게 유지하는 것입니다. 대화 히스토리에 잡동사니가 쌓이면 매 턴마다 그 잡동사니가 입력 토큰으로 다시 청구되고, 에이전트의 판단력도 같이 흐려집니다.

그래서 세션 관리도 절감 기법입니다.

• 주제가 바뀌면 이어가지 말고 새 세션을 연다
• 긴 세션은 압축 명령(/compact 류)으로 히스토리를 요약해 토큰을 회수한다
• 다음 세션에 넘길 컨텍스트는 채팅이 아니라 핸드오프 문서로 남긴다

구독제 사용자에게는 이쪽이 오히려 프롬프트 압축보다 중요합니다. 비용이 정액이어도 컨텍스트 윈도우는 정액이 아니기 때문입니다.

트레이드오프는 있다#

토큰 절감은 공짜가 아닙니다. 출력을 줄이면 설명이 부족해져서 나중에 "왜 이렇게 고쳤지?"를 되짚기 어려울 수 있고, 컨텍스트를 압축하면 세부사항이 누락될 수 있습니다. 코드 리뷰나 아키텍처 논의처럼 맥락이 생명인 작업에서는 압축을 풀고, 반복적인 탐색·수정 작업에서는 조입니다. 작업 유형에 따라 다이얼을 조절하는 게 요령입니다.

다섯 가지를 다 붙일 필요도 없습니다. 하나만 고른다면 첫 번째, 탐색을 위임하고 결론만 받는 습관부터. 토큰 고지서보다 먼저, 에이전트가 오후까지 멀쩡하게 일하는 걸로 효과를 체감하게 됩니다.