Claude Code 토큰 사용량 줄이는 설정: CLAUDE.md, settings.json, 세션 관리

Claude Code를 오래 쓰다 보면 같은 작업인데도 사용량이 들쭉날쭉하다. 원인은 대부분 질문 문장이 아니라 매 요청에 함께 실려 가는 맥락이다. 긴 지침 파일, 쓰지 않는 도구 정의, 하루 종일 이어진 대화, 수천 줄짜리 테스트 로그가 모두 요청마다 다시 전송된다. 이 글은 공식 비용 관리 문서를 기준으로 토큰이 쓰이는 지점을 나누고, 지점마다 적용할 설정을 순서대로 정리한다.

토큰이 쓰이는 네 지점과 대응 설정

먼저 /context로 무엇이 공간을 차지하는지, /usage로 현재 세션 사용량을 확인해 두면 설정 전후를 비교할 수 있다.

CLAUDE.md는 짧게, 나머지는 필요할 때만 로드

메모리 문서는 CLAUDE.md 한 파일을 200줄 이하로 유지하라고 권한다. 길수록 맥락을 더 쓰고 지침을 따르는 정도도 떨어진다는 이유다. 넣을 것은 Claude가 코드를 읽어서는 알 수 없는 정보다. 빌드·테스트 명령, 폴더 역할, 건드리면 안 되는 파일, 팀 규칙 정도면 충분하다. /init을 실행하면 코드베이스를 분석해 초안을 만들어 주고, 파일이 이미 있으면 덮어쓰지 않고 개선안을 제안한다.

# CLAUDE.md
## 명령
- 테스트: npm test
- 린트: npm run lint
- 타입 검사: npm run typecheck

## 구조
- src/api: HTTP 핸들러, src/domain: 비즈니스 로직, scripts/: 배포 스크립트(수정 금지)

프로젝트 개요는 @README.md 참고

# Compact instructions
When you are using compact, please focus on test output and code changes

@경로 문법은 다른 파일을 가져오지만, 가져온 파일도 시작 시 함께 로드되므로 분량을 줄여 주지는 않는다. 특정 폴더에서만 필요한 규칙은 .claude/rules/ 아래에 두고 paths 필드로 범위를 지정하면, Claude가 해당 경로의 파일을 읽을 때만 로드된다. 특정 모듈만 다른 컨벤션을 따르는 경우도 여기에 적어 두면 일반 규칙과 충돌하지 않는다.

# .claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---
- 모든 엔드포인트는 입력 검증을 포함한다
- 오류 응답은 표준 형식을 따른다

PR 리뷰나 DB 마이그레이션처럼 특정 작업에만 쓰는 긴 절차는 스킬로 옮기라고 비용 문서가 권한다. 스킬은 호출될 때만 로드되므로 평소 기본 맥락이 작아진다.

settings.json으로 읽지 않을 파일 막기

Claude Code 설정 파일에는 탐색 범위를 줄이는 전용 키가 따로 있지 않다. 대신 permissions.deny의 Read 규칙으로 특정 파일 읽기를 막을 수 있고, 이는 비밀 값 보호에도 쓰인다. 팀 전체에 적용하려면 저장소의 .claude/settings.json에, 나만 적용하려면 .claude/settings.local.json에 둔다. 설정 문서의 형식을 따른 예시다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./dist/**)",
      "Read(./coverage/**)"
    ]
  }
}

설정 파일은 엄격한 JSON이라 주석이나 끝의 쉼표가 있으면 오류가 난다. 저장 후 /status로 파일이 로드됐는지 확인한다. 자주 쓰는 검증 명령을 allow에 넣어 두면 매번 승인 요청이 뜨지 않아 작업 흐름이 끊기지 않는다. 설정 파일 우선순위는 관리형 설정, 명령줄 인자, 프로젝트 로컬, 공유 프로젝트, 사용자 설정 순이다.

세션과 출력 관리하기

1. 작업이 바뀌면 /clear — 이전 작업의 맥락은 이후 모든 요청에 비용을 더한다. 나중에 돌아올 세션이면 /rename으로 이름을 붙이고 /resume으로 다시 연다.
2. 이어가야 하면 지시를 붙여 /compact — 예: /compact Focus on code samples and API usage. 다만 압축 자체도 대화 전체를 읽는 큰 요청이므로, 이어갈 필요가 없으면 /clear가 비용이 들지 않는다.
3. 긴 출력은 훅으로 거르기 — 문서는 PreToolUse 훅으로 테스트 명령을 바꿔 실패 줄만 남기는 예시를 제공한다. 만 줄짜리 로그 대신 ERROR 줄만 넘기면 맥락이 수만 토큰에서 수백 토큰으로 준다고 설명한다.
4. 대량 출력 작업은 서브에이전트에 위임 — 테스트 실행, 문서 조회, 로그 처리 결과는 서브에이전트 맥락에 남고 요약만 돌아온다.
5. 작업에 맞는 모델과 노력 수준 — /model로 모델을, /effort로 추론 노력 수준을 조정한다. 사고 토큰은 출력 토큰으로 과금된다.

요청 문장도 영향을 준다. "코드베이스를 개선해 줘"처럼 넓은 요청은 광범위한 탐색을 부르고, "auth.ts의 login 함수에 입력 검증 추가"처럼 구체적인 요청은 읽는 파일 수를 줄인다.

설정 파일을 팀 문서로 관리하기

CLAUDE.md와 .claude/ 폴더는 코드와 같은 저장소에 두고 변경을 리뷰로 반영한다. 한 사람이 관리하면 그 사람이 자리를 비울 때 갱신이 멈추고, 폴더 구조가 바뀌어도 옛 규칙이 남는다. 문서는 서로 모순되는 규칙이 있으면 Claude가 임의로 하나를 고를 수 있다고 경고하므로, 분기마다 한 번 쓰이지 않는 규칙과 충돌하는 규칙을 정리한다. 개인 선호는 CLAUDE.local.md에 두고 .gitignore에 추가한다.

도구 밖에서 API를 직접 호출하는 서비스라면 토큰 비용 관리 방식이 다르다. 요청별 로그와 사용자별 예산 설계는 AI API 비용 관리 방법에서, 다른 도구의 규칙 파일 작성법은 Cursor Rules 작성법에서 다룬다.