Claude Code 사용법 — 입문 글 다음에 할 4가지

Claude Code 사용법을 설명하는 글은 많지만, 대부분 「설치하고 첫 실행을 완료하는 것」에서 끝납니다. 실제로 곤란해지기 시작하는 것은 그다음입니다 — 같은 지시를 매번 작성하고, 확인 대화상자가 너무 많으며, 작업 중 5시간 사용 제한에 도달합니다. 이 페이지는 입문 글이 끝나는 지점에서 시작하여 이 세 가지를 차례로 해결합니다.

먼저 Claude Code는 「채팅에 코드를 붙여 넣는 도구」가 아니라 터미널에서 저장소 안에 상주하는 에이전트입니다. 파일을 읽고 수정하며, 테스트를 실행하고, 커밋까지 수행합니다. 따라서 가장 먼저 해야 할 일은 사용법을 익히는 것이 아니라 프로젝트의 규칙을 전달하는 것입니다.

처음의 3단계 — 시작, /init, 구체적인 요청

설치 직후 할 가치가 있는 것은 이 3가지뿐입니다. 특히 두 번째 단계인 /init를 건너뛰면 이후 모든 세션에서 같은 설명을 반복하게 됩니다.

# 1. プロジェクトのディレクトリで起動する（ここが全ての前提）
cd ~/work/my-app
claude

# 2. 最初の一手は /init — リポジトリを読んで CLAUDE.md を書き出す
> /init

# 3. 以降は普通の日本語で頼む。ファイル名を添えるほど精度が上がる
> src/api/user.ts のバリデーションを zod に置き換えて、テストも直して

/init는 저장소를 읽고 CLAUDE.md를 생성합니다. 생성된 내용은 초안이므로 그대로 두지 말고 반드시 직접 수정하세요. 다음 절에서 그 내용에 대해 설명합니다.

CLAUDE.md — 매번 설명하는 내용을 한 번만 작성하기

CLAUDE.md는 프로젝트 루트에 두는 Markdown 파일이며, 세션마다 자동으로 읽힙니다. 여기에 작성해야 하는 것은 「코드를 읽어도 알 수 없는 내용」뿐입니다.

# CLAUDE.md — プロジェクトのルート、git にコミットする

## コマンド
- テスト: npm test（1 ファイルだけなら npm test -- path/to/file）
- 型チェック: npx tsc --noEmit
- Lint: npm run lint

## 決めごと
- 日付は必ず date-fns。moment は使わない。
- API ハンドラは app/api/**/route.ts のみ。lib に書かない。
- コミットメッセージは日本語、prefix は feat / fix / docs。

## 触ってはいけない場所
- db/migrations/ — 生成物。手で編集しない。

반대로 작성하지 않는 편이 좋은 내용도 분명합니다. 디렉터리 구조나 함수 설명은 코드를 읽으면 알 수 있으므로 필요하지 않습니다. CLAUDE.md는 매번 요청에 포함되므로 길게 작성하면 확실히 토큰을 소비합니다 — 짧게, 규칙만 작성하세요. git에 커밋하면 팀 전체에 동일한 규칙이 적용됩니다.

권한 — 확인 횟수를 줄이되, 너무 많이 건너뛰지는 않기

파일을 수정하거나 명령을 실행할 때마다 확인이 이루어집니다. 이는 안전장치이므로 전부 없애기보다는 「읽기·검증에 해당하는 항목만 허용하는 것」이 실무적인 절충안입니다. 세션 중 「항상 허용」을 선택하면 기억되며, .claude/settings.json에 작성하면 프로젝트 단위로 고정할 수 있습니다.

모든 확인을 건너뛰는 플래그도 제공되지만, 삭제나 원격 저장소에 대한 push까지 확인 없이 실행됩니다. 사용해도 되는 곳은 손상되어도 버릴 수 있는 컨테이너나 일회용 작업 트리 안뿐입니다. 판단 기준과 안전한 사용법은 --dangerously-skip-permissions를 사용해야 하는 경우에 정리되어 있습니다.

사용자 지정 명령 — 같은 요청을 매번 작성하지 않기

리뷰, 릴리스 전 점검, 커밋 메시지 정리처럼 매번 거의 같은 방식으로 요청하는 작업은 명령으로 만들 수 있습니다. .claude/commands/에 Markdown을 놓기만 하면 됩니다.

# .claude/commands/review.md — 置くだけで /review として使える
指定されたファイルをレビューして、次の 3 点だけ指摘してください。

1. 実際に落ちる条件があるバグ（再現手順を添える）
2. 既存のユーティリティで置き換えられる重複
3. テストが無い分岐

スタイルの好みは指摘しないでください。

이제 /review src/api/user.ts라고 입력하면 같은 관점의 리뷰가 반환됩니다. git에 커밋하면 팀에서 공유할 수 있고, 리뷰 기준 자체를 저장소에 둘 수 있습니다. 실무에서 유용한 명령 형식은 Claude Code workflows에 영어로 자세히 설명되어 있습니다.

5시간 창이 닫혔을 때 계속하는 방법

구독 사용 한도는 5시간 롤링 윈도우로 관리되므로 작업이 한창인 오후에 닫힐 수 있습니다. 상위 요금제로 변경해도 그 순간 바로 다시 열리지는 않습니다. 선택지는 사실상 3가지입니다.

세 번째 방법은 구독을 해지하지 않고도 사용할 수 있습니다. 다음 두 줄이 설정되어 있는 동안에만 종량 과금으로 전환되고, 변수를 삭제하면 원래 구독으로 돌아갑니다.

# 5 時間ウィンドウが閉じても作業を続けるための 2 行。
# この変数が設定されている間だけ従量課金になり、消せば元のサブスクに戻る。
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code の既定モデルと opus エイリアスは最新の Opus を、sonnet エイリアスは
# Kunavo が提供していない Sonnet 5.5 を指す。/model sonnet や opusplan の実行
# フェーズ、sonnet 指定のサブエージェントが 404 にならないようモデルを固定する。
# opus は Opus 5.5 に固定（Claude Code v2.1.280 以降が必要。古ければ claude update）。
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# 補助的な処理を一番安いモデルに逃がす 1 行（毎セッション効く）
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

요율은 카탈로그에서 그대로 불러옵니다: Claude Sonnet 5는 1M 토큰당 $1.40 / $7.00, Claude Haiku 4.5는 $0.70 / $3.50입니다. 선불 잔액에서 차감되므로 사용하지 않은 달의 청구액은 0입니다. 구독과 종량 과금 중 어느 쪽이 저렴한지, 단계당 실제 비용과 손익분기점은 Claude Code 요금에서 계산합니다. 창의 작동 방식 자체는 Claude Pro 제한에서, 기본 모델 선택 방법은 Opus와 Sonnet의 차이에서 확인할 수 있습니다.

정확도를 높이는 요청 방식과 낮추는 요청 방식

마지막으로 사용법의 숙련도가 가장 크게 드러나는 부분입니다. 파일명과 경로를 함께 적으면 탐색에 사용하는 토큰이 줄어들어 결과가 더 빠르고 정확해집니다 — 「검증을 수정해」보다 「src/api/user.ts의 검증을 zod로 교체해」라고 하세요.

그리고 큰 요청을 한 번에 보내지 마세요. 변경 → 테스트 → 다음 변경으로 나누면 실패하더라도 돌아갈 지점이 분명해집니다. 오류가 발생했을 때의 원인 분리는 Claude Code 401 오류 같은 개별 페이지에 정리되어 있습니다.

같은 진행 방식을 OpenAI 측 에이전트에서 시도하려면 Codex 사용법에서 ChatGPT 요금제 없이 API 키로 실행하는 절차를 정리해 두었습니다.

자주 묻는 질문