Claude Code·Codex·Cursor의 토큰 사용량을 줄이는 방법

핵심 요약

1. 분석한 에이전트 세션에서 전체 토큰의 94.2%는 캐시 읽기였고, 에이전트 응답은 0.6%에 그쳐 출력보다 반복되는 컨텍스트를 줄이는 편이 효과적이었다.
2. xcsift와 전역 hook을 사용하면 필터 없는 xcodebuild·SwiftPM 출력이 다음 단계마다 컨텍스트에 다시 포함되는 문제를 프로젝트별 지침에 의존하지 않고 막을 수 있다.
3. AGENTS.md를 작게 유지하고 파일 재읽기·중복 skill·불필요한 폴링을 줄이는 한편, 탐색용 subagent에는 작고 빠른 모델을 배정하는 방법을 제안한다.

도입

작성자는 RocketSim, RocketTrace 등 자신의 Swift 앱에서 에이전트 세션 1,674개를 분석했다. 전체 토큰의 94.2%가 기존 지침과 파일, 도구 출력을 다시 보내는 캐시 읽기였고, 응답 토큰은 0.6%였다. 따라서 핵심 절감 지점은 에이전트가 쓰는 답변의 길이가 아니라, 매 단계마다 컨텍스트에 다시 포함되는 빌드 로그와 파일, 지침을 제한하는 데 있다.

상세 요약

토큰 사용량의 대부분은 컨텍스트 재전송

작성자는 자신의 에이전트 세션 1,674개와 Cursor 사용량 데이터를 분석했다. 전체 토큰의 94.2%가 캐시 읽기였고 응답은 0.6%였다. 13,323회의 xcodebuild·swift test 실행 중 48%는 출력 필터가 없었다. 파일 읽기의 53%는 파일 전체를 불러왔으며, 파일이 바뀌지 않았는데 다시 읽은 횟수는 18,683회였다. 같은 세션에서 skill을 중복으로 불러온 사례는 961회였다.

도구를 호출한 뒤 에이전트는 지침, 대화, 읽은 파일, 빌드 로그를 포함한 전체 대화를 모델에 다시 보낸다. 캐싱은 처리 속도를 높여도 토큰 집계에는 포함된다. 컨텍스트 창이 차면 대화를 요약하거나 새로 시작하게 되고, 이후 파일과 지침을 다시 읽게 된다. 따라서 관련 없는 작업으로 전환할 때 새 대화를 시작하고, 파일은 필요한 줄만 읽도록 한다.

지침·파일·skill의 범위 줄이기

AGENTS.md는 매 단계 컨텍스트에 포함되므로 공통 지침은 짧게 유지한다. 프로젝트별 세부 내용은 하위 폴더의 AGENTS.md나 해당 작업에서만 여는 문서로 옮긴다. Codex 로그에서는 32KB 예산을 넘긴 프로젝트 지침이 잘린 사례도 있었다.

skill은 프레임워크별로 하나만 두고, 오래 쓰지 않은 항목은 정리한다. 탐색·검색을 맡는 subagent에는 작은 모델을 배정하고, 주요 판단과 수정은 주 모델에 맡긴다. 작성자는 주 모델을 그대로 물려받은 subagent가 85%였지만, 대부분은 코드베이스 탐색을 수행했다고 설명한다.

빌드 출력에 xcsift 적용

원문은 xcsift로 xcodebuild와 Swift Package Manager의 출력을 요약하는 방식을 제시한다. 예시 명령은 다음과 같다.

brew install ldomaradzki/xcsift/xcsift
xcodebuild test -scheme MyApp -destination 'platform=macOS' 2>&1 | xcsift -f toon -w

작성자의 측정에서 증분 빌드 출력은 필터 적용 전 약 18,200토큰, 적용 후 32토큰이었다. FAQ는 MCPBeast의 테스트 실행이 약 406,500토큰에서 168토큰으로 줄었다고 덧붙인다. 필터 결과에는 컴파일 경고의 파일·줄 번호와 통과한 테스트 수가 남는다.

프로젝트 지침만으로는 필터 적용을 보장할 수 없어 전역 hook을 사용한다. 스크립트는 필터 없는 xcodebuild, swift build, swift test 명령을 찾아 xcsift 파이프로 바꾼다. 이미 필터가 있거나 xcodebuild -list처럼 제외 대상인 명령은 건드리지 않는다. xcsift가 설치되지 않았거나 명령을 안전하게 처리할 수 없으면 원래 명령을 유지한다. set -o pipefail을 추가해 빌드 실패 코드도 전달한다.

Cursor와 Claude Code는 각각 사용자 hook 설정에 스크립트를 등록해 명령을 재작성한다. Codex는 재작성된 명령을 다시 승인받아야 하므로 원래 빌드를 차단하고 필터 적용 명령을 재시도 지침으로 전달한다. Codex에서는 설정에서 hook을 활성화하고, 새 hook을 신뢰해야 실행된다.

그 밖의 세션 규칙

• 검색을 먼저 하고 필요한 줄만 읽으며, 수정되지 않은 파일은 다시 읽지 않는다.
• 전체 테스트 전에 -only-testing:이나 --filter로 좁은 테스트를 실행한다.
• sleep 후 상태를 반복 확인하는 대신 gh run watch처럼 한 명령에서 기다린다. 분석에서 반복 확인 과정은 740개 턴에 걸쳐 나타났다.
• Simulator는 접근성 트리로 확인하고, 시각 검증이 필요할 때만 스크린샷을 찍는다. 관련 사례는 RocketSim과 RocketTrace로 구현하는 에이전트 기반 iOS 개발에서 다룬다.
• 같은 수정에 두 번 실패하면 반복을 멈추고 확인한 내용을 보고한다. 관련 없는 작업으로 바뀌면 짧은 인계 메모와 함께 새 대화를 제안한다.

저자는 이 규칙을 Cursor 사용자 규칙, ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md 등 전역 지침에 두고, 프로젝트별 문서는 해당 저장소에만 필요한 정보에 집중한다.

결론

이 분석에서 토큰 사용량을 좌우한 것은 응답의 짧음보다 반복해서 전달되는 컨텍스트의 크기와 횟수였다. 특히 Swift 개발에서는 필터 없는 빌드 출력이 큰 비용을 만들었고, 전역 hook은 이를 프로젝트별 AGENTS.md 지침에 맡기지 않고 자동 처리한다. 파일을 필요한 범위만 읽고, 중복 skill과 반복 폴링을 줄이는 규칙도 같은 원칙을 따른다.