claude-code를 대규모 프로젝트에 사용하다 보면 토큰 비용이 순식간에 치솟는다. 컨텍스트 창이 쌓일수록 비용도 선형 이상으로 증가하기 때문이다. 이 글은 코드 품질을 희생하지 않으면서 토큰 소비를 줄이는 23가지 실전 방법을 소개한다. 개발자와 AI 코딩 어시스턴트를 도입하려는 팀 모두에게 유용하다.

1부. 컨텍스트 관리 핵심 전술

1. 태스크 전환 시 채팅 초기화

태스크가 바뀔 때는 /clear로 세션을 새로 시작한다. 이전 디버깅 로그가 남아 있으면 그만큼 토큰을 낭비한다. 세션을 나중에 다시 이어가고 싶다면 먼저 이름을 지정해 두자.

/rename auth-debug-apr30
/clear

나중에 재개할 때는 /resume 명령을 사용한다.

2. 긴 태스크엔 /compact로 압축

오래 이어진 대화는 /compact로 요약한다. 요약 시 무엇을 보존하고 무엇을 버릴지 CLAUDE.md에 지시해 두면 품질이 올라간다.

# Compact instructions

When compacting, preserve:
- current task goal
- files changed
- commands already run
- failing tests and exact errors
- decisions made
- next action list

Drop:
- old exploration paths
- repeated logs
- irrelevant discussion

3. 자동 압축 임계값 낮추기

기본값은 95% 용량에서 자동 압축이 시작된다. 이를 70%로 낮추면 더 여유 있는 상태를 유지할 수 있다. 로그가 많은 워크플로라면 50%도 고려한다.

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
# 노이즈가 많은 워크플로
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

4. 사용량 모니터링

큰 태스크 전에 현재 컨텍스트 상태를 확인하는 습관을 들인다.

• /context — 무엇이 컨텍스트 공간을 차지하는지 확인
• /usage — 현재 세션 비용 추적

5. 터미널에 실시간 상태 표시

~/.claude/settings.json에 상태 표시줄을 추가하면 컨텍스트 사용률과 모델 정보를 실시간으로 볼 수 있다.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context'"
  }
}

채팅 안에서 바로 생성하려면 다음 명령을 사용한다.

/statusline show model name and context percentage

2부. 지시문·파일 최적화

6. 글로벌 지시문 간소화

Anthropic은 CLAUDE.md를 200줄 이내로 유지하도록 권장한다. 파일이 클수록 매 세션마다 토큰 비용이 올라간다. 꼭 필요한 정보만 남기자.

# Project essentials

- Package manager: pnpm
- Test command: pnpm test
- Typecheck: pnpm typecheck
- Main app code: src/
- API handlers: src/api/
- Do not edit generated files in src/generated/

7. 경로 범위 규칙 사용

전역 규칙 대신 특정 경로에만 적용되는 규칙을 .claude/rules/ 폴더에 배치한다. 해당 파일을 수정할 때만 로드되므로 불필요한 토큰 소비를 막는다.

paths:
  - "src/api/**/*.ts"

# API rules

- Validate all request inputs.
- Use the standard error response shape.
- Add tests for authorization failures.

8. 특수 워크플로는 스킬로 분리

자주 반복하는 특수 워크플로는 .claude/skills/<skill-name>/SKILL.md에 스킬로 정의한다. 스킬은 호출할 때만 로드되므로 기본 컨텍스트를 깔끔하게 유지한다. disable-model-invocation: true를 설정하면 명시적으로 호출할 때만 실행된다.

name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(pnpm test *) Read Grep Edit

Fix GitHub issue $ARGUMENTS.

Steps:
1. Use gh issue view to read the issue.
2. Identify the smallest relevant files.
3. Write or update tests first.
4. Implement the fix.
5. Run the targeted test.
6. Summarize files changed.

호출: /fix-issue 123

3부. 도구·출력 제한

9. MCP 서버 대신 CLI 도구 우선

MCP 서버보다 gh, git 같은 CLI 도구를 선호한다. CLI 도구는 오버헤드가 적다. 사용하지 않는 MCP 서버는 비활성화한다.

Use `gh` to inspect PR 42 and return only the failing check names.

10. 서버 출력 상한 설정

도구 출력이 채팅 컨텍스트를 넘치게 만들지 않도록 상한을 설정한다.

export MAX_MCP_OUTPUT_TOKENS=8000

11. 터미널 출력 상한 설정

긴 테스트 로그는 토큰을 빠르게 소모한다.

export BASH_MAX_OUTPUT_LENGTH=20000

12. 로그 필터링

원시 로그를 통째로 넘기지 말고, 오류 줄만 추출해 Claude에 전달한다.

pnpm test 2>&1 | grep -A 5 -E "FAIL|ERROR|Error|failed" | head -120

필터링된 로그를 세션 시작 시 바로 컨텍스트에 주입할 수도 있다.

pnpm test 2>&1 | grep -A 5 -E "FAIL|ERROR|Error|failed" | head -120 | claude

4부. 모델·에이전트 전략

13. 서브에이전트 활용

리서치처럼 자료를 많이 읽어야 하는 태스크는 서브에이전트에 위임한다. 서브에이전트는 격리된 공간에서 작업하고 핵심 요약만 메인 채팅에 반환한다.

Use a subagent to inspect the failing auth tests and logs. Return only:
1. failing test names
2. likely root cause
3. files that need edits
4. shortest fix plan

자주 쓰는 서브에이전트는 .claude/agents/investigator.md에 저장해 두고 /investigator "auth tests are failing" 형태로 호출한다. Claude Code 내 /agents 명령으로 GUI에서 생성할 수도 있다.

14. 저렴한 모델 선택

일반 코딩 작업은 Sonnet으로 충분하다. Opus는 심층 아키텍처 설계 등 고급 추론이 필요할 때만 사용한다.

claude --model haiku

15. 에포트 수준 낮추기

단순 태스크는 에포트 수준을 낮춰 비용을 줄인다.

/effort low

16. 확장 사고 비활성화

간단한 편집에는 확장 사고(extended thinking)를 끈다. 사고 토큰도 출력 토큰으로 과금된다.

export CLAUDE_CODE_DISABLE_THINKING=1

17. 코드 인텔리전스 플러그인 활용

타입 언어 프로젝트에 코드 인텔리전스 플러그인을 설치하면 Claude가 불필요한 파일을 읽지 않고 정확한 심볼 탐색을 할 수 있다.

5부. 파일 접근·워크플로 제어

18. 노이즈 파일 접근 차단

~/.claude/settings.json에서 로그, 빌드 폴더 등 불필요한 파일에 대한 읽기 권한을 차단한다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./node_modules/**)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./coverage/**)",
      "Read(./.next/**)",
      "Read(./tmp/**)",
      "Read(./logs/**)",
      "Read(./*.log)"
    ]
  }
}

19. 광범위한 스캔 지양

“전체 저장소를 읽어봐” 같은 모호한 요청은 대규모 파일 스캔을 유발한다. 정확한 파일 경로를 지정하자.

The login redirect fails. Start with src/auth/session.ts. Read only related files.

20. 검증 대상 사전 제공

Claude에게 어떻게 결과를 확인할지 미리 알려준다. 기대 출력값과 구체적인 테스트 이름을 제공하면 수정 루프를 줄일 수 있다.

21. 잘못된 방향 조기 수정

Claude가 불필요한 파일을 읽기 시작하면 즉시 인터럽트한다. 세션을 안전한 지점으로 되감아 다시 시작하는 것이 결과적으로 더 절약이 된다.

22. 짧은 시스템 프롬프트 사용

긴 도구 설명을 제거하는 숨겨진 설정이다. 사용에 주의가 필요하다.

export CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=1

23. 내장 Git 지시문 제거

커스텀 Git 워크플로를 사용하는 경우, 기본 Git 지시문을 제거해 기본 프롬프트를 줄일 수 있다.

export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1

권장 설정 조합

표준 코딩 태스크용 설정

{
  "permissions": {
    "deny": [
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Read(./node_modules/**)", "Read(./dist/**)", "Read(./build/**)",
      "Read(./coverage/**)", "Read(./.next/**)", "Read(./tmp/**)",
      "Read(./logs/**)", "Read(./*.log)"
    ]
  },
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70",
    "BASH_MAX_OUTPUT_LENGTH": "20000",
    "MAX_MCP_OUTPUT_TOKENS": "8000",
    "CLAUDE_CODE_EFFORT_LEVEL": "medium"
  }
}

적극적 절약 설정

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "BASH_MAX_OUTPUT_LENGTH": "12000",
    "MAX_MCP_OUTPUT_TOKENS": "5000",
    "CLAUDE_CODE_EFFORT_LEVEL": "low"
  }
}

마치며

토큰 절약은 일회성 설정이 아니라 습관이다. 컨텍스트를 자주 점검하고, 모호한 요청 대신 정확한 파일과 범위를 지정하며, 반복 워크플로는 스킬로 분리하는 것이 핵심이다. 이 23가지 팁을 프로젝트 규모에 맞게 조합하면 비용 부담 없이 claude-code의 성능을 최대한 활용할 수 있다.

참고 자료

• 23 Tips for Smart Claude Code Token Saving and Workflow Optimization — Analytics Vidhya (2026-05-10)