Claude Code 속도 최적화: 느린 세션을 진단하고 실무 속도를 높이는 방법

Claude Code가 느려졌다고 느낄 때 먼저 의심할 것은 모델 성능이 아닙니다. 실제 원인은 대화 기록이 커졌거나, 읽는 파일 범위가 너무 넓거나, 테스트 로그를 그대로 넣었거나, 지시가 너무 모호한 경우가 많습니다. 이 사이트에서도 글 작성, 번역, 빌드, 배포, 디버깅을 한 세션에 계속 쌓았을 때 응답이 무거워졌습니다. 이후에는 /usage와 /context로 상태를 보고, 단계가 끝날 때 목적을 적어 /compact 하는 방식으로 바꾸었습니다. 이 글은 초보자도 바로 적용할 수 있도록 느린 원인 진단, 읽기 범위 제한, CLAUDE.md 작성, 서브에이전트 활용, 그리고 피해야 할 실수를 순서대로 정리합니다.

튜닝 전에 먼저 진단하기

먼저 진단입니다. /usage는 현재 사용량을 보는 기본 입구입니다. API 사용자는 세션 token과 로컬 추정 비용을 보고, 구독 사용자는 플랜 사용량과 사용 내역을 봅니다. 최종 청구서가 아니라 작업의 무게를 보는 계기판으로 이해하면 됩니다. 다음은 /context입니다. 대화 기록, memory, MCP, 도구 정의, 규칙 중 무엇이 컨텍스트를 차지하는지 확인합니다. 문제가 큰 CLAUDE.md나 사용하지 않는 MCP라면 모델만 바꾸어서는 해결되지 않습니다. /compact는 긴 대화를 요약해 줄이지만, 무엇을 남길지 말해야 효과적입니다. 변경 파일, 실패한 테스트, 결정 사항, 미해결 질문을 보존하라고 지시하면 속도와 이어가기 품질을 함께 잡을 수 있습니다.

# Run these inside Claude Code before changing the workflow
/usage
/context
/compact Preserve changed files, test failures, decisions, and open questions

빠른 기본 workflow 만들기

기본 루프는 단순합니다. 큰 작업을 시작할 때 /usage와 /context를 확인하고, 자연스러운 구간에서 설명을 붙여 /compact 하며, 전혀 다른 작업으로 이동할 때 /clear 합니다. 두 번째는 범위를 좁히는 습관입니다. 프로젝트 전체를 이해하라고 시키지 말고, 먼저 읽을 파일, 실행할 테스트, 읽지 말아야 할 디렉터리, 마지막에 돌려줄 증거를 지정합니다. 세 번째는 CLAUDE.md를 작게 유지하는 것입니다. 공식 memory 문서의 취지는 모든 세션에 필요한 사실만 항상 읽히게 하는 것입니다. 긴 절차나 드문 playbook은 rules나 skills로 분리해야 매 요청이 가벼워집니다.

claude -p "Fix only the null-check bug in src/api/auth.ts.
Read src/api/auth.ts and tests/auth.test.ts first.
Do not scan node_modules, dist, coverage, or unrelated feature folders.
Return the changed files, commands run, and remaining risks."

CLAUDE.md에는 항상 필요한 사실만 넣기

아래 예시는 일부러 짧게 작성했습니다. memory를 영구 문서 창고로 만들지 않고, Claude에게 안정적인 저장소 지도를 주기 위한 형태입니다.

# CLAUDE.md

## Project commands
- Build: npm run build
- Test: npm run test
- Type check: npm run typecheck

## Fast navigation
- API code: src/api/
- UI components: src/components/
- Tests: tests/

## Do not read unless explicitly requested
- node_modules/
- dist/
- coverage/
- .wrangler/

## Compact instructions
When compacting, preserve changed files, failing tests, decisions, credentials policy, and next actions.

작은 benchmark로 측정하기

느낌만으로 최적화하지 마세요. 같은 유형의 작업을 넓은 prompt와 scoped prompt로 각각 실행하고, 시간, 읽은 파일 수, 마지막 증거의 품질을 비교합니다.

$runs = @(
  @{ Name = "wide"; Prompt = "Find and fix the auth bug in this project" },
  @{ Name = "scoped"; Prompt = "Fix the null-check bug in src/api/auth.ts only" }
)

foreach ($run in $runs) {
  $elapsed = Measure-Command { claude -p $run.Prompt }
  [pscustomobject]@{
    Name = $run.Name
    Seconds = [math]::Round($elapsed.TotalSeconds, 1)
  }
}

실무에서 쓰는 세 가지 use case

작은 버그 수정

대상 파일, 실패 테스트, 완료 조건만 전달합니다. 탐색 파일 수가 줄어들고, 수정 후 리뷰도 빨라집니다.

큰 리팩터링

조사, 수정, 테스트, 리뷰를 분리합니다. 각 단계 뒤 /compact를 실행해 결정과 남은 문제만 이어갑니다.

콘텐츠와 번역 파이프라인

번역, 목록 조사, 반복 검증은 서브에이전트에 맡기고, 메인 세션은 판단과 최종 확인만 담당하게 합니다.

피해야 할 실패 사례

첫 번째 실수는 /compact를 아무 설명 없이 누르는 것입니다. 보존할 정보를 지정하지 않으면 실패 명령이나 설계 이유가 사라질 수 있습니다.
두 번째 실수는 CLAUDE.md에 모든 것을 넣는 것입니다. 오래된 장애, 개인 메모, 드문 절차는 매번 읽는 비용이 됩니다.
세 번째 실수는 속도를 위해 검증을 없애는 것입니다. 로그 전체가 아니라 실패 줄과 기대 결과, 재현 명령만 남겨야 합니다.

확인한 공식 문서

Claude Code costs and /usage: https://code.claude.com/docs/en/costs
Claude Code monitoring and telemetry: https://code.claude.com/docs/en/monitoring-usage
Claude Code memory and CLAUDE.md: https://code.claude.com/docs/en/memory

이번 rewrite에서 확인한 것

이 글은 Claude Code의 Costs, Monitoring, Memory 공식 문서를 확인해 /usage, /context, /compact, CLAUDE.md 중심으로 갱신했습니다.

다음 단계

팀에서 Claude Code를 빠르게 만들고 싶다면 더 큰 모델이나 자동화를 먼저 늘리지 마세요. prompt 형태, memory 파일, verification receipt를 먼저 표준화하세요.