Claude Code 튜토리얼 — 종량제 키를 사용하는 일상: 모델 전환, 비용 계산, 컨텍스트 관리

Claude Code 사용법은 네 단계로 요약할 수 있습니다. 프로젝트 폴더에서 claude를 실행하고, 한 번 /init를 실행해 CLAUDE.md를 생성하게 한 다음, 작업을 중국어로 설명하면서 파일 경로를 포함하고, 제안된 변경을 검토한 후 수락 여부를 결정하세요. Claude Code는 터미널 안에 상주하는 프로그래밍 도우미로 파일을 읽고 수정하며 테스트를 실행하고, 실행 전에 먼저 동의를 구합니다. Pro/Max 구독으로 로그인하거나 종량제 API 키를 설정해 사용할 수 있습니다. 키를 사용할 때는 매 단계가 토큰 단위로 과금되므로 일상적인 사용의 핵심은 작업별 모델 전환, 세션 하나의 비용 파악, 간결한 컨텍스트 유지라는 세 가지입니다.

온라인의 Claude Code 가이드는 거의 모두 구독 로그인을 전제로 합니다. 이 페이지는 다른 사용자를 위한 것입니다. 구독이 없거나 5시간 사용량 창의 제한을 피하고 싶어 종량제 키를 사용하는 사람을 대상으로 합니다. 아직 설치하지 않았다면 먼저 Claude Code 설치 가이드를 확인하고, 설치 및 연결을 완료한 뒤 돌아오세요.

처음 사용하기: 네 가지 작업

# 1. 一定要在專案資料夾裡啟動——它能看、能改的範圍就是這個資料夾
cd ~/work/my-app
claude

# 2. 第一個指令：讀過整個 repo，產生 CLAUDE.md
> /init

# 3. 之後直接用中文交代任務，附上檔案路徑最準
> 把 src/api/user.ts 的輸入驗證改用 zod，測試也一起修好

# 4. 牽涉很多檔案的任務，先按 Shift+Tab 切到計畫模式，確認做法再動手

파일을 수정하거나 명령을 실행할 때마다 먼저 확인을 요청합니다. 방향이 잘못되었다면 Esc를 눌러 중지한 뒤 /rewind로 이전 체크포인트로 돌아갈 수 있습니다. 코드와 대화가 함께 되돌아갑니다. /init가 생성하는 CLAUDE.md는 초안일 뿐이며, 아래에 이를 짧게 만드는 방법을 설명하는 절이 있습니다.

API 키 사용 시 세션 하나의 과금 방식

Claude Code는 요청을 한 번 보낼 때마다 시스템 프롬프트, CLAUDE.md, 전체 대화 및 읽은 파일 내용을 다시 전송하고 새 내용은 마지막에 추가합니다. 변경되지 않은 앞부분은 캐시를 사용합니다. 캐시 읽기에는 입력 가격의 10%, 캐시 쓰기에는 입력 가격의 1.25배가 부과됩니다. 따라서 세션 비용의 대부분은 ‘이전 대화를 다시 읽는 것’에서 발생하는 경우가 많습니다.

아래 표는 Anthropic 공식 비용 문서의 세션 예시(입력 1,200, 출력 5,300, 캐시 읽기 940,000, 캐시 쓰기 50,000 token)를 사용해 Kunavo 요금으로 네 모델에서 각각 계산한 것입니다:

Claude Sonnet 5에서 이 세션 청구액의 약 85%가 캐시 읽기 및 쓰기입니다. 다시 말해 비용을 결정하는 것은 입력한 글자 수가 아니라 대화의 길이입니다. 이것이 뒤에서 ‘컨텍스트 위생’을 설명하는 이유입니다.

자신의 수치를 확인하려면 Claude Code에서 /usage(/cost는 별칭)을 실행하세요. 네 가지 토큰 수가 표시됩니다. 단, 옆에 표시되는 금액은 Claude Code가 Anthropic 정가를 기준으로 로컬에서 추정한 값입니다. Kunavo를 사용할 때 실제 차감액은 백엔드의 사용량 페이지를 기준으로 하며, 각 모델의 토큰 수(캐시 읽기 및 쓰기 포함)와 차감 금액이 표시됩니다.

작업별 모델 전환

먼저 ~/.claude/settings.json의 env 블록에서 각 별칭을 실제 모델에 연결하세요. 이 파일에 작성하면 편집기 확장 프로그램과 백그라운드 프로세스도 읽을 수 있습니다. 프로젝트에 커밋될 수 있는 .claude/settings.json에는 작성하지 마세요. 별칭은 반드시 연결해야 합니다. Claude Code의 기본 모델과 opus 별칭은 모두 최신 Opus를 가리키며, Kunavo에 아직 등록되지 않았다면 연결 설정이 없을 때 첫 요청이 404를 반환합니다. sonnet 별칭은 Sonnet 5.5를 가리키지만 Kunavo는 이 모델을 제공하지 않으므로 ANTHROPIC_DEFAULT_SONNET_MODEL가 없으면 /model sonnet, opusplan의 실행 단계 및 model: sonnet로 설정된 서브에이전트가 모두 404를 반환합니다. 아래 설정은 opus 별칭을 Claude Opus 5.5 (claude-opus-5-5)에 연결하며 Claude Code v2.1.280 이상이 필요합니다. 이전 버전이라면 먼저 claude update를 실행하세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5"
  }
}

설정한 후에는 한 줄만으로 전환할 수 있습니다:

# 工作階段裡切換（別名會對應到上面設定的模型）
> /model haiku
> /model sonnet
> /model opus

# 也可以直接打完整名稱
> /model claude-fable-5

# 或在啟動時指定
claude --model claude-opus-5-5

/model는 선택을 이후 새 세션의 기본값으로 저장합니다. 이번에만 변경하려면 인자 없이 /model를 실행하고 메뉴에서 s를 누르세요. ANTHROPIC_DEFAULT_HAIKU_MODEL는 Claude Code가 백그라운드에서 수행하는 요약과 제목도 제어하므로 가장 저렴한 모델로 지정하는 것이 가장 경제적입니다.

Kunavo에서 Claude Opus 5.5은(는) $2.80 / $14.00, Claude Sonnet 5은(는) $1.40 / $7.00입니다. Claude Haiku 4.5의 단가는 Claude Sonnet 5의 1/2 정도이고, Claude Fable 5은(는) 그 5배입니다. 공식 가격과 비교하면: Claude Sonnet 5 Anthropic 공식 가격보다 약 30% 저렴, Claude Opus 5.5 Anthropic 공식 가격보다 약 30% 저렴, Claude Haiku 4.5 Anthropic 공식 가격보다 약 30% 저렴, Claude Fable 5 Anthropic 공식 가격보다 약 30% 저렴.

모델 전환은 작업 중간이 아니라 작업 사이에 하세요.모델마다 캐시가 분리되어 있습니다. 작업 중간에 /model하면 다음 요청에서 전체 대화를 캐시되지 않은 가격으로 다시 읽어야 합니다(캐시가 유효한 동안 Claude Code가 먼저 확인을 요청합니다). 먼저 /clear한 뒤 전환하면 다시 읽는 내용은 짧은 새 대화뿐입니다. 사고 token에는 출력 가격이 적용됩니다. 간단한 작업에는 /effort로 사고 수준을 낮출 수 있습니다. 이 설정도 작업 시작 시 지정해야 하며, 대부분의 모델은 중간에 effort를 변경하면 캐시가 무효화됩니다.

CLAUDE.md: 반복해서 전달할 내용만 작성하세요

# CLAUDE.md — 放在專案根目錄，commit 進 git

## 指令
- 測試：npm test（只跑一個檔：npm test -- path/to/file）
- 型別檢查：npx tsc --noEmit
- Lint：npm run lint

## 規則
- 日期一律用 date-fns，不用 moment。
- API handler 只放在 app/api/**/route.ts。
- commit 訊息用繁體中文，前綴 feat / fix / docs。

## 不要動的地方
- db/migrations/ —— 產生出來的檔案，不要手改。

CLAUDE.md는 각 세션이 시작될 때 로드되고 이후 모든 요청에 함께 전송됩니다(대부분 캐시 읽기 가격이 적용됨). Anthropic은 파일 하나를 200행 이내로 유지할 것을 권장합니다. 길수록 컨텍스트를 더 많이 차지하고 준수율도 낮아집니다. 코드에서 알 수 있는 내용(디렉터리 구조, 함수 설명)은 작성할 필요가 없습니다. 사람에게만 보여줄 메모는 <!-- --> 안에 넣을 수 있으며 컨텍스트로 전송되기 전에 제거됩니다.

또 하나의 흔한 오해가 있습니다. 세션 중간에 CLAUDE.md를 수정해도 즉시 적용되지 않습니다. /clear, /compact 또는 재시작을 해야 새 버전을 읽습니다.

컨텍스트 위생: 모든 단계를 저렴하게 유지하기

• 관련 없는 작업 사이에는 /clear을 사용하세요.새 대화를 시작하며 자체 비용은 없습니다. 이전 대화는 나중에 /resume로 불러올 수 있습니다.
• 같은 작업이 너무 길어지면 /compact을 사용하세요.보존할 핵심 사항을 지정할 수 있습니다. 예: /compact 保留測試輸出和改過的檔案. 요약 요청 하나가 전송되므로 캐시가 유효할 때 실행하는 것이 가장 저렴합니다. 오래 자리를 비운 뒤 compact하면 요약 요청에서 전체 기록을 캐시되지 않은 가격으로 다시 읽어야 합니다.
• 방향을 잘못 잡았다면 /rewind하세요.이미 캐시된 앞부분으로 돌아가므로 compact보다 저렴합니다.
• 키 모드에서는 캐시가 기본적으로 5분 동안만 유지됩니다.5분 넘게 자리를 비웠다가 돌아오면 첫 단계에서 전체 앞부분을 캐시에 다시 기록합니다(입력 가격의 1.25배). 회의나 식사 전에 /compact 또는 /clear로 마무리하세요.
• /context를 사용해 컨텍스트를 차지하는 항목을 확인하세요.Kunavo를 사용할 때 이 수치는 로컬 추정치입니다. Kunavo는 현재 /v1/messages/count_tokens를 제공하지 않으며 자동 압축과 세션 자체에는 영향이 없습니다.
• 사용하지 않는 MCP 서버는 /mcp에서 끄세요.Anthropic 문서에 따르면 사용자 지정 ANTHROPIC_BASE_URL를 설정하면 도구 검색(tool search)이 비활성화됩니다. MCP 도구 정의가 지연 로드되지 않고 모든 요청에 바로 포함됩니다.
• 작업을 설명할 때 파일 경로를 포함하세요.‘검증을 조금 수정해 줘’라고 하면 여러 곳을 검색하며 많은 파일을 읽게 됩니다. ‘src/api/user.ts의 검증을 zod를 사용하도록 변경해 줘’라고 하면 필요한 부분만 읽습니다.

‘실행해도 되나요?’라는 질문을 줄이고 싶다면 읽기 및 검증 명령만 허용하는 것을 권장합니다. 모든 확인을 한 번에 건너뛰는 플래그는 환경 전체를 버릴 수 있을 때만 사용해야 합니다. 이유는 --dangerously-skip-permissions 설명(영문)을 참조하세요. 캐시 과금 방법은캐시 문서에 설명되어 있습니다.

비용 한도 및 결제

키 관리 페이지에서 Claude Code 전용 키를 만들고 월별 비용 한도를 설정하세요. 한도에 도달하면 이 키의 요청은 402을 반환하고 추가로 차감되지 않으므로, 통제되지 않는 루프도 한도까지만 비용이 발생합니다. 같은 페이지에서 IP 허용 목록도 설정할 수 있습니다.

계정은 선불 방식입니다. 최소 충전액은 $10이고 잔액은 만료되지 않으며 실패한 요청에는 요금이 부과되지 않습니다. 대만에서는 해외 결제가 가능한 카드(Visa, Mastercard, Amex, JCB, UnionPay) 또는 Apple Pay와 Google Pay로 충전할 수 있습니다. 현재 JKOPay나 LINE Pay 같은 현지 결제 수단은 없습니다. 자세한 내용은 Claude Code 요금을 참조하세요.

언제 구독이 더 저렴한가요?

매일 장시간 상호작용하고 한 달에 많은 단계를 실행하는 사람에게는 구독의 고정 월 요금이 보통 종량제보다 저렴합니다. 한 번만 나누면 판단할 수 있습니다. 월 요금 ÷ 단계당 비용 = 손익분기 단계 수입니다. Claude Sonnet 5의 단계당 비용을 약 $0.043(캐시 제외)로 계산하면, 한 달 실행 횟수가 이보다 적을 때는 종량제가 더 저렴하며 작업하지 않은 달에는 $0입니다. 각 요금제의 현재 월 요금과 전체 계산식은 Claude Code 비용 페이지에 있으며 여기서는 반복하지 않습니다.

이 방식의 절충점도 분명히 해야 합니다. Kunavo를 통해 사용하면 공유 용량을 사용하며 전용 할당량이나 계약상 SLA가 없습니다. 보장된 할당량이나 SLA가 필요한 팀은 Anthropic에서 직접 구매해야 합니다. 전체 연결 설정은 Claude Code 통합 문서(영문)를 참조하세요.

자주 묻는 질문