Claude Code 토큰 절약 가이드 [중급편] — 설정과 워크플로우 최적화 7가지

안녕하세요, 자바파커입니다.

"compact도 하고, clear도 하고, 프롬프트도 짧게 쓰는데... 그래도 토큰이 빠르게 줄어요."

초급편의 기본 습관을 적용하고 나면, 다음으로 눈을 돌려야 할 곳은 설정과 워크플로우입니다. Claude Code가 불필요하게 읽는 파일을 차단하고, 작업 구조 자체를 최적화하는 단계입니다.

이 글은 [초급 → 중급 → 고급] 시리즈의 두 번째 편입니다. 초급편을 아직 안 읽으셨다면 먼저 확인해보세요.

1. .claudeignore로 불필요한 파일 차단하기

Claude Code는 프로젝트를 분석할 때 파일을 읽습니다. 문제는 읽을 필요 없는 파일까지 읽는다는 것입니다.

node_modules, dist, 빌드 산출물, 로그 파일... 이런 것들이 컨텍스트에 포함되면 토큰이 낭비됩니다.

.gitignore처럼 .claudeignore 파일을 프로젝트 루트에 만들면 됩니다.

# .claudeignore — Claude Code가 무시할 파일/폴더

# 빌드 산출물
dist/
build/
.next/
out/

# 의존성
node_modules/
vendor/
.venv/

# 로그 & 캐시
*.log
.cache/
.turbo/
coverage/

# 대용량 데이터
*.csv
*.sql
data/

# 미디어 파일 (읽어도 의미 없음)
*.mp4
*.mp3
*.zip

# 락 파일 (보통 수정할 일 없음)
package-lock.json
yarn.lock
pnpm-lock.yaml

.claudeignore의 효과

실제 프로젝트에서 측정한 결과입니다.

파일 탐색 범위가 줄어들면 Claude가 관련 파일을 찾는 과정에서 소모하는 토큰도 크게 줄어듭니다.

2. 서브에이전트로 컨텍스트 분리하기

Claude Code에는 서브에이전트(Subagent) 기능이 있습니다. 메인 대화의 컨텍스트를 오염시키지 않고 별도의 작업을 수행할 수 있습니다.

서브에이전트가 토큰을 줄이는 원리

[메인 대화] ────────────────────────────────
  │
  ├─→ [서브에이전트 1] 파일 검색 → 결과만 반환
  │     (자체 컨텍스트에서 작업, 메인에 영향 없음)
  │
  ├─→ [서브에이전트 2] 테스트 실행 → 결과만 반환
  │
  └─→ 메인 대화는 결과 요약만 받음 → 컨텍스트 최소

서브에이전트는 자체 컨텍스트에서 작업하고, 메인 대화에는 결과 요약만 돌아옵니다. 대규모 코드 탐색이나 테스트 실행처럼 출력이 긴 작업에서 특히 효과적입니다.

서브에이전트를 유도하는 프롬프트

Claude Code는 복잡한 작업에서 자동으로 서브에이전트를 사용하지만, 명시적으로 유도할 수도 있습니다.

이 프로젝트에서 사용하지 않는 의존성을 찾아줘.
각 의존성별로 사용 여부를 별도로 조사해서 결과만 알려줘.

"별도로 조사해서 결과만"이라는 표현이 서브에이전트 활용을 유도합니다.

3. 모델 전환으로 토큰 단가 낮추기

모든 작업에 최상위 모델을 쓸 필요는 없습니다. Claude Code에서는 작업 중간에 모델을 전환할 수 있습니다.

모델별 특성과 추천 용도

실전 전환 전략

# 기본 모델 설정 (설정에서)
claude config set model claude-sonnet-4-6

# 복잡한 작업이 필요할 때만 Opus로 전환
claude --model claude-opus-4-6

또는 대화 중에 /model 명령어로 전환할 수 있습니다.

전략: 일상 작업은 Sonnet, 복잡한 설계나 디버깅에만 Opus를 사용하면 비용 효율이 크게 개선됩니다. 단순 포매팅이나 이름 변경 같은 작업은 Haiku로도 충분합니다.

4. autocompact 설정하기

초급편에서 /compact를 수동으로 실행하는 법을 다뤘습니다. 이걸 자동화할 수 있습니다.

// ~/.claude/settings.json
{
  "preferences": {
    "autoCompact": true
  }
}

autocompact 동작 방식

• 컨텍스트 크기가 임계점을 넘으면 자동으로 대화를 압축
• 사용자가 신경 쓰지 않아도 토큰이 관리됨
• 압축 시점은 Claude가 자동 판단

커스텀 압축 프롬프트

단순 true 대신 문자열을 넣으면 압축 시 지시사항을 줄 수 있습니다.

{
  "preferences": {
    "autoCompact": "코드 변경 사항과 결정 사항 위주로 유지하고 나머지는 압축"
  }
}

이렇게 하면 중요한 맥락은 보존하면서 불필요한 대화만 정리됩니다.

5. Hook으로 반복 작업 자동화하기

Hook은 특정 이벤트가 발생할 때 자동으로 쉘 명령을 실행하는 기능입니다. Claude가 직접 명령을 실행하는 것보다 토큰 소모가 적습니다.

왜 Hook이 토큰을 줄이는가?

Claude가 직접 린터를 실행하면:

1. 린트 명령어 생성 (출력 토큰)
2. 실행 결과를 읽음 (입력 토큰)
3. 결과 해석 (출력 토큰)

Hook으로 자동화하면:

1. 파일 저장 시 자동 실행 (토큰 0)
2. 에러가 있을 때만 Claude에게 전달

토큰 절약에 효과적인 Hook 예시

// ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

이 설정은 Claude가 파일을 수정할 때마다 자동으로 ESLint를 실행합니다. Claude에게 "린트 돌려줘"라고 매번 말할 필요가 없습니다.

6. 프롬프트에 출력 형식 제한 걸기

Claude의 응답이 길수록 출력 토큰이 늘어납니다. 출력 형식을 제한하면 효과적입니다.

답변 길이 제한

이 함수의 버그를 찾아서 한 줄로 설명해줘.

변경이 필요한 파일 목록만 알려줘. 코드는 아직 수정하지 마.

단계별 작업 지시

# 나쁜 예 — 한 번에 모든 것을 요구
"이 프로젝트 분석하고, 문제점 찾고, 해결책 제안하고, 코드 수정까지 해줘"

# 좋은 예 — 단계별로 나눠서 요청
"이 프로젝트의 성능 문제 3가지만 목록으로 알려줘"
→ (결과 확인 후)
"2번 문제를 수정해줘"

한 번에 모든 걸 요청하면 Claude가 긴 응답을 생성하고, 그 응답이 다음 턴의 컨텍스트가 되어 토큰이 눈덩이처럼 불어납니다.

7. 파일 지정으로 탐색 범위 줄이기

Claude Code는 관련 파일을 찾기 위해 프로젝트를 탐색합니다. 이 탐색 과정 자체가 토큰을 소모합니다.

파일을 직접 지정하면?

# 나쁜 예 — Claude가 파일을 찾아야 함
"로그인 버그 고쳐줘"

# 좋은 예 — 파일을 직접 지정
"src/auth/login.ts의 validateToken 함수에서 만료 체크 로직 수정해줘"

파일 경로와 함수명을 직접 지정하면 탐색 과정을 건너뛰므로 토큰이 절약됩니다.

@파일 참조 활용

IDE 확장(VS Code 등)에서는 @ 기호로 파일을 직접 참조할 수 있습니다.

@src/auth/login.ts 이 파일의 validateToken 함수 수정해줘

이렇게 하면 Claude가 파일을 검색하는 단계 없이 바로 해당 파일을 읽습니다.

중급편 요약 — 설정 체크리스트

초급편의 습관 + 중급편의 설정을 조합하면, 동일한 작업을 기존 대비 1/3 수준의 토큰으로 처리할 수 있습니다.

FAQ

Q. .claudeignore에 너무 많은 파일을 넣으면 Claude가 필요한 파일을 못 읽는 거 아닌가요?

맞습니다. 핵심은 "절대 수정하지 않을 파일"만 넣는 것입니다. node_modules, 빌드 산출물, 미디어 파일처럼 코딩 작업과 관련 없는 것만 넣으세요. 소스 코드는 넣지 마세요.

Q. Haiku 모델로 코딩해도 괜찮나요?

단순한 작업(변수명 변경, import 추가, 포매팅)은 충분합니다. 하지만 복잡한 로직이나 아키텍처 결정이 필요한 작업에서는 품질 차이가 있습니다. 작업 복잡도에 따라 모델을 전환하는 것이 핵심입니다.

Q. autocompact를 켜면 중요한 대화 내용이 사라지나요?

Claude가 자동으로 요약하기 때문에 세부 디테일은 줄어들 수 있습니다. 하지만 코드 변경 사항은 파일에 남아있고, 핵심 결정 사항은 요약에 포함됩니다. 커스텀 프롬프트를 설정하면 어떤 내용을 유지할지 지시할 수 있습니다.

다음 고급편에서는 Memory 시스템, Skill 최적화, 워크트리 격리, 비용 모니터링 자동화 등 아키텍처 레벨의 토큰 관리 전략을 다룹니다.

여러분은 어떤 설정이 가장 효과적이었나요? 댓글로 공유해주세요!