# Claude Code 完全チュートリアル

このチュートリアルでは、2026年最強のAIプログラミングアシスタント **Claude Code** を基礎から高度なテクニックまで解説します。

---

## 1. Claude Code とは

### コード補完ではなく、エージェント型のコーディングアシスタント

Claude Code は Anthropic 公式の CLI（コマンドラインインターフェース）型 **エージェント型コーディングアシスタント**（Agentic Coding Assistant）です。従来のコード補完ツール（GitHub Copilot など）とは違い、経験豊富な開発者のように動きます：

- **タスクを自分で理解する**：要件を伝えると実行計画を立てる
- **コードを直接操作する**：プロジェクト内の任意のファイルを読み・編集し・作成する
- **ターミナルコマンドを実行する**：テスト実行、依存関係のインストール、ビルド
- **プロジェクトを深く理解する**：デフォルトで 20 万トークンのコンテキストウィンドウ（`claude-opus-5` / `claude-sonnet-5` などは 100 万まで拡張可能）
- **サブエージェントを動かす**：複雑なタスクを複数の専門サブエージェントに分割して並列処理する

### 誰が使っているか

2025 年 5 月のリリース以来、Claude Code は Netflix、Spotify、KPMG、ロレアル、Salesforce をはじめとする世界の主要企業で中核的な開発ツールになりました。わずか 6 か月で年間売上 10 億ドルの節目に到達しています。

### 2025〜2026 年の主なアップデート

| アップデート | 内容 |
|------|------|
| **Plan Mode** | まず分析・調査し、それから方針を立ててミスを減らす |
| **Agent Teams** | 複数エージェントの並列協調、git worktree による分離 |
| **Voice Mode** | 音声での対話。スペースキーを押しながら話す |
| **Computer Use** | デスクトップ・ブラウザ・開発ツールの操作 |
| **Hooks システム** | 17 種類のライフサイクルイベントでワークフローを自動化 |
| **MCP プロトコル** | 外部のツールやサービスに接続 |
| **Skills** | 共有可能なワークフローテンプレートとしての知識モジュール |
| **Extended Thinking** | 複雑な問題では内部で深く推論してから答える |
| **Opus 5 / Sonnet 5** | 現行フラッグシップと日常のデフォルト（4.8 / 4.6 も販売中） |
| **1M Context Beta** | `claude-sonnet-5` / `claude-opus-5` などが 100 万トークンのコンテキストに対応 |

### なぜ QCode.cc 経由で使うのか

中国本土から Claude Code を直接使うと、ネットワークが届かない・費用が高いという 2 つの問題があります。QCode.cc を使うと：

- **アジア太平洋ノードで低レイテンシ**。VPN や自前プロキシは不要
- **コストを最大 80% 削減**。公式価格から大幅に節約できる
- **Claude Code と Codex がプラン枠を共有**。1 つのプランで 2 つのツール
- **マルチノードで高可用**（HK / 北米 / 欧州 / グローバル Route 53）

---

## 2. インストールと設定

### システム要件

| 要件 | 内容 |
|------|------|
| OS | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2） |
| Node.js | 18.0 以降（22 LTS 推奨） |
| Git | 2.x 以降 |
| ディスク容量 | 約 200MB |

### Claude Code のインストール

```bash
# npm でインストール（推奨）
npm install -g @anthropic-ai/claude-code

# 中国のユーザーは淘宝ミラーで高速化
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

### QCode.cc の設定

ターミナルで環境変数を設定します：

```bash
# ~/.bashrc または ~/.zshrc に追記
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
export ANTHROPIC_AUTH_TOKEN=cr_あなたのAPIキー
```

> **なぜ `ANTHROPIC_API_KEY` ではなく `ANTHROPIC_AUTH_TOKEN` なのか**：QCode.cc の `cr_` で始まるキーは **サードパーティゲートウェイのキー** であり、Anthropic 公式のキーではありません。Claude Code は `ANTHROPIC_AUTH_TOKEN` を見つけると `Authorization: Bearer <token>` ヘッダーでゲートウェイに送ります。`ANTHROPIC_API_KEY` の場合は `x-api-key` を送るため、ログイン済みの Anthropic アカウントと OAuth の競合が起きることがあります。**`ANTHROPIC_AUTH_TOKEN` の使用が QCode 公式の推奨です**。

> **API キー**は [QCode.cc コンソール](https://qcode.cc/dashboard) で取得できます。`cr_` で始まります。

> **接続先の選択**：デフォルトは `https://api.qcode.cc/api`（グローバル Route 53 が自動で最寄りに振り分け）。中国本土のユーザーには `asia.qcode.cc`（アジアノード、HK/JP の近い方、最低レイテンシ）を推奨します。その他の接続ドメイン（`us` / `eu` / `asia`）と BASE_URL のルールは [エンドポイントと API フォーマット](/docs/getting-started/endpoints-and-api-paths) を参照してください。

設定を反映します：

```bash
source ~/.bashrc  # または source ~/.zshrc
```

### インストールの確認

```bash
# バージョン確認
claude --version
# バージョン番号が表示されます（実際の値は環境により異なります。https://github.com/anthropics/claude-code/releases を参照）

# 動作テスト
claude -p "こんにちは、自己紹介をしてください"
```

Claude から応答が返ってくれば、インストールと設定は成功です。

### シェル補完（任意）

```bash
# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

# Fish
claude completion fish > ~/.config/fish/completions/claude.fish
```

---

## 3. はじめての使用

### 起動

任意のプロジェクトディレクトリで実行します：

```bash
cd ~/my-project
claude
```

Claude Code はプロジェクト構造を自動でスキャンし、対話モードに入ります。

### 画面の見方

```text
╭─────────────────────────────────────────╮
│ claude                                   │
│                                          │
│ プロジェクト: my-project                  │
│ モデル: claude-sonnet-5                  │
│ コンテキスト: 12,345 / 1,000,000 tokens  │
╰─────────────────────────────────────────╯

> _
```

自然言語をそのまま入力すれば、Claude が理解して実行します。

### 最初のタスク：プロジェクトを理解する

```text
> このプロジェクトのアーキテクチャを分析して、主要モジュールとその関係を教えて
```

Claude は自動的に：
1. `package.json`、`README.md`、ディレクトリ構造を読む
2. 主要なソースファイルに目を通す
3. 構造化されたアーキテクチャ分析を提示する

### 権限の確認

Claude が操作を実行しようとすると、確認を求めてきます：

```text
Claude が実行しようとしています：
  ツール: Bash
  コマンド: npm test

  [y] 許可  [n] 拒否  [a] このセッションでは常に許可
```

- **y**：今回だけ許可する
- **n**：拒否する
- **a**：このセッション中は同種の操作を常に許可する（日常の開発におすすめ）

### よく使う権限モード

| モード | 内容 | 向いている場面 |
|------|------|---------|
| デフォルト | 操作のたびに確認 | 初回利用、機密性の高いプロジェクト |
| `--allowedTools` | 許可するツールを指定 | 範囲を限定した自動化 |
| `--dangerously-skip-permissions` | 確認をすべてスキップ | Docker の隔離環境、CI/CD |

---

## 4. コア機能

### 4.1 Plan Mode（プランモード）

Plan Mode は、Claude にまず分析・調査させてから実行方針を立てさせるモードで、複雑なタスクに向いています。

```bash
# プランモードに入る
> /plan

# プロンプトで促してもよい
> まず要件を分析して実施方針を立ててください。いきなりコードは変えないで
```

**流れ**：
1. Claude がコードベースと要件を分析する
2. 実施方針を提示する（どのファイルを作成／変更するか、手順の順序）
3. あなたが方針をレビューし、修正を伝える
4. 確認後、Claude が方針どおりに実行する

**例**：

```text
> /plan
> このプロジェクトに JWT を使ったユーザー認証機能を追加したい

Claude: 現在のプロジェクト構造を分析して方針を立てます...

📋 実施方針：
1. src/middleware/auth.ts を作成 — JWT 検証ミドルウェア
2. src/services/auth-service.ts を作成 — 認証のビジネスロジック
3. src/routes/index.ts を変更 — ログイン／登録ルートを追加
4. src/models/user.ts を作成 — ユーザーデータモデル
5. 依存関係を追加：jsonwebtoken, bcrypt
6. テストファイルを作成

この方針でよろしいですか？調整は必要ですか？
```

### 4.2 Extended Thinking（拡張思考）

Opus 5（および販売中の 4.8 / 4.7）は拡張思考の能力を内蔵しており（adaptive thinking + effort パラメータの利用を推奨。詳しくは [Adaptive Thinking 設定ガイド](/docs/usage/adaptive-thinking)）、複雑な問題ではまず内部で深く推論します。

```text
> この並行処理のバグを 2 日追っています。src/worker.ts の競合状態を分析してください

[Claude が内部で数千トークンの推論を行い、実行経路・ロック機構・タイミングの問題を分析する]

Claude: 原因が分かりました。worker.ts の 127 行目で...
```

**自動的に働く場面**：
- 複雑なデバッグ作業
- アーキテクチャレベルの分析
- 多段階の推論が必要なとき

### 4.3 サブエージェント（Sub-agents）

Claude は特定のタスク向けに専門のサブエージェントを生成できます：

```text
> この PR をレビューして、あわせてセキュリティ上の脆弱性も確認して

Claude: 2 つのサブエージェントを並列で起動します：
  - サブエージェント 1：コード品質のレビュー
  - サブエージェント 2：脆弱性スキャン
```

サブエージェントは独立したコンテキストで動くため、メインの会話を汚しません。

### 4.4 主要コマンド早見表

| コマンド | 機能 | 例 |
|------|------|------|
| `/model` | モデルを切り替える | `/model opus` |
| `/plan` | プランモードに入る | `/plan` |
| `/compact` | コンテキストを圧縮する | `/compact` |
| `/cost` | 現在の費用を見る | `/cost` |
| `/clear` | コンテキストを消去する | `/clear` |
| `/init` | CLAUDE.md を生成する | `/init` |
| `/review` | コードレビュー | `/review` |
| `/help` | ヘルプを表示 | `/help` |
| `Esc` | 現在の操作をキャンセル | |
| `Ctrl+C` | 応答を中断 | |

### 4.5 コンテキスト管理

Claude Code のコンテキストウィンドウは 200K トークンです。長い会話では管理が必要になります：

```bash
# 現在のコンテキスト使用量を見る
/cost

# コンテキストを圧縮する（重要な情報を残して空きを作る）
/compact

# まったく新しいセッションを始める
/clear
```

**ベストプラクティス**：
- コンテキスト使用量が 70% を超えたら `/compact` を実行する
- タスクが変わるときは `/clear` で新しいセッションを始める
- 複雑なプロジェクトでは背景情報を CLAUDE.md に書く（`/compact` で消えない）

---

## 5. CLAUDE.md — Claude にプロジェクトを理解させる

### なぜ CLAUDE.md が必要か

Claude Code は起動のたびにプロジェクト内の `CLAUDE.md` を自動で読み、アーキテクチャ・コーディング規約・独自の取り決めを把握します。これがないと、毎回プロジェクトの背景を説明し直すことになります。

### すばやく作る

```bash
# Claude がプロジェクトを分析して自動生成
/init
```

### ファイルの階層

| 場所 | 適用範囲 | Git 管理 |
|------|---------|---------|
| `~/.claude/CLAUDE.md` | グローバル（全プロジェクト） | 含めない |
| `プロジェクトルート/CLAUDE.md` | このプロジェクト | Git にコミット |
| `.claude/CLAUDE.md` | このプロジェクト（個人用） | .gitignore に追加 |
| `サブディレクトリ/CLAUDE.md` | そのサブディレクトリのみ | 必要に応じて |

### 実践テンプレート：React + TypeScript プロジェクト

```markdown
# MyApp

## 技術スタック
- React 19 + TypeScript 5.x + Vite
- スタイル：Tailwind CSS v4
- 状態管理：Zustand
- テスト：Vitest + Testing Library

## よく使うコマンド
- 開発：`pnpm dev`
- テスト：`pnpm test`
- ビルド：`pnpm build`
- Lint：`pnpm lint`

## コーディング規約
- コンポーネントは関数コンポーネントで書き、Props は interface で定義する
- any 型は禁止
- CSS は Tailwind の utility class のみ
- コミット形式：feat: / fix: / docs:

## ディレクトリ構成
- src/components/ — 再利用可能なコンポーネント
- src/pages/ — ページコンポーネント
- src/hooks/ — カスタムフック
- src/lib/ — ユーティリティ関数
- src/api/ — API リクエストのラッパー

## 注意事項
- Node.js 22+、パッケージマネージャーは pnpm
- API リクエストはすべて src/api/client.ts を通す
```

> CLAUDE.md の完全な設定ガイドは [CLAUDE.md 設定ガイド](/docs/usage/claude-md) を参照してください。

---

## 6. モデル選択の実践ガイド

### 3 つのモデルの比較

単価は 2026-08-16 時点で [qcode.cc/models](https://qcode.cc/models) から取得したスナップショットです。**同ページが正**です。4.x も販売中で、既定ではなくなっただけです。

| 項目 | Opus 5 | Sonnet 5 | Haiku 4.5 |
|--------|----------|------------|-----------|
| **位置づけ** | 現行フラッグシップ | 日常のデフォルト | 軽量・高速 |
| **推論能力** | 非常に強い | 強い | 標準的 |
| **コード品質** | 非常に高い | 高い | 中程度 |
| **応答速度** | やや遅い | 中程度 | 速い |
| **コンテキスト** | 1M / 128K | 1M / 128K | 200K |
| **入力価格** | $5.00/M | $2.00/M | $1.00/M |
| **出力価格** | $25.00/M | $10.00/M | $5.00/M |

### モデルの切り替え

```bash
# 対話モード内で切り替える
/model opus    # Opus に切り替え
/model sonnet  # Sonnet に切り替え
/model haiku   # Haiku に切り替え

# 起動時に指定する
claude --model claude-opus-5
```

### 場面別のおすすめ

| 場面 | おすすめモデル | 理由 |
|------|---------|------|
| アーキテクチャ設計 | **Opus** | 深い推論で全体を見る |
| 日常のコーディング | **Sonnet** | コストパフォーマンス最良 |
| バグ修正 | **Sonnet** | 十分な性能で速い |
| 複雑なデバッグ | **Opus** | Extended Thinking |
| コード整形 | **Haiku** | 単純作業は最安のモデルで |
| PR レビュー | **Sonnet** | 速度と品質のバランス |
| 大規模リファクタリング | **Opus** | 全体理解が必要 |
| ドキュメント作成 | **Sonnet** | 十分 |

### 併用戦略（推奨）

```text
1 日のモデル使い分け：
├── Sonnet 5（70%）— 日常開発、バグ修正、テスト作成
├── Opus 5 （15%）— アーキテクチャ判断、難しい問題
└── Haiku 4.5（15%）— 整形、簡単な質問、一括処理
```

会話の途中でいつでも切り替えられます：

```bash
# まず Opus で方針を立てる
/model opus
> このモジュールのアーキテクチャを分析して、リファクタリング方針を立てて

# 方針が固まったら Sonnet に切り替えて実行
/model sonnet
> 方針の第 1 ステップを実行して
```

---

## 7. 高度なテクニック

### Hooks システム

`.claude/settings.json` に自動化フックを設定します：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}
```

> 完全なガイドは [Hooks システム](/docs/advanced/hooks) を参照してください。

### MCP サーバー

Model Context Protocol で外部ツールに接続します：

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}
```

### Skills システム

Skills は再利用可能な知識モジュールです：

```bash
# 利用可能な skill を見る
/skills

# 特定の skill を使う
> /commit    # commit skill でコミットを生成
> /review    # review skill でコードをレビュー
```

### --bare モード

対話機能をすべて省いたスクリプト向けの呼び出しです：

```bash
claude --bare -p "すべての TODO コメントを列挙して" --output-format json
```

---

## 8. 実践例

### 例 1：新しいプロジェクトを理解する

```bash
cd ~/unfamiliar-project
claude
```

```text
> このプロジェクトを分析してください：
> 1. どんな技術スタックを使っているか
> 2. 中心となるモジュールとその責務
> 3. データの流れ
> 4. 簡単なアーキテクチャ図（ASCII）
```

Claude は package.json、ソースディレクトリ、設定ファイルを自動で見て、プロジェクト全体の地図を示します。

### 例 2：Plan Mode で新機能を実装する

```text
> /plan
> API にレート制限を追加したい。要件は：
> - ユーザーごとに 1 分あたり最大 60 リクエスト
> - カウントは Redis に保存
> - 超過時は 429 と Retry-After ヘッダーを返す

Claude:
📋 実施方針：
1. 依存関係のインストール：ioredis
2. src/middleware/rate-limiter.ts を作成
3. src/config/rate-limit.ts を作成（設定値）
4. src/app.ts を変更（ミドルウェアを登録）
5. tests/rate-limiter.test.ts を作成
6. docker-compose.yml を更新（Redis サービスを追加）

確認いただければ着手します。

> 方針で問題ありません。実行してください
```

### 例 3：複雑なバグのデバッグ

```text
/model opus
> ユーザーから「同時注文のときに在庫がまれにマイナスになる」と報告がありました。
> src/services/order-service.ts と src/services/inventory-service.ts を分析して、
> 並行処理のバグを見つけて修正してください。

[Opus が Extended Thinking を使い、実行経路・ロック機構・トランザクション分離レベルを分析する]

Claude: 原因が分かりました。inventory-service.ts の 45 行目で、在庫チェックと減算が同一トランザクションに入っておらず、
TOCTOU の競合状態があります。修正方針は SELECT FOR UPDATE を使うことです...
```

### 例 4：一括リファクタリング

```text
> プロジェクト内のすべての class コンポーネントを関数コンポーネント + Hooks にリファクタリングしたい。
> src/components/ 配下の .tsx ファイルを 1 つずつ処理してください。

Claude は次のように動きます：
1. すべての class コンポーネントを走査
2. 1 つずつ関数コンポーネントに変換
3. lifecycle メソッドを useEffect に置き換え
4. this.state を useState に置き換え
5. テストを実行して壊れていないことを確認
```

### 例 5：テストスイートを丸ごと書く

```text
> src/services/user-service.ts の単体テストを一式書いてください：
> - すべての公開メソッドを網羅
> - 正常系と異常系の両方
> - 外部依存（データベース、キャッシュ）はモック
> - カバレッジ目標 90%+
```

### 例 6：CI/CD の自動化

```bash
# GitHub Actions で使う
claude -p "この PR のコード変更をレビューし、セキュリティと性能を重点的に見て" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep
```

> CI/CD の実践例は [自動化と CI/CD](/docs/advanced/headless) を参照してください。

---

## 9. Claude Code と Codex の併用

Claude Code と OpenAI Codex CLI は 2026 年で最も強力な 2 つの AI コーディングツールで、それぞれ得意分野があります。

**最良の組み合わせ**：Claude Code で計画とレビュー、Codex で実行と一括処理。

```bash
# 1. Claude Code で方針を立てる
claude
> /plan
> ユーザー権限システムの実施方針を設計して

# 2. Codex が方針どおりに実行する
codex "PLAN.md の方針に従って、ステップ 1-3 を実装して"
```

> **QCode.cc は 1 つのプランで 2 つのツールが枠を共有**するため、切り替えコストはゼロです。
> 詳細な比較は [Codex vs Claude Code 比較](/docs/getting-started/codex-vs-claude-code)。
> Codex の使い方は [Codex 完全ガイド](/docs/ide/codex)。

---

> **チームで使う場合**：3 名以上のチームには [エンタープライズチーム版](https://qcode.cc/enterprise) がおすすめです — 専用ドメイン `e-xxx.qcode.cc`、サブ API Key の管理、アカウント保護、法人振込と請求書に対応。詳しくは [エンタープライズガイド](/docs/reference/enterprise-guide)。

## 10. よくある質問

### インストールに失敗する

**Q: `npm install -g` で権限エラーになる**

```bash
# 方法 1：sudo を使う
sudo npm install -g @anthropic-ai/claude-code

# 方法 2：nvm で Node.js を管理する（推奨）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
npm install -g @anthropic-ai/claude-code
```

### ネットワーク接続の問題

**Q: 接続がタイムアウトする、または拒否される**

```bash
# 設定が正しいか確認
echo $ANTHROPIC_BASE_URL    # https://api.qcode.cc/api のはず
echo $ANTHROPIC_AUTH_TOKEN  # cr_ で始まるはず

# 疎通テスト
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models
# → 200 + JSON のモデル一覧＝アドレス・鍵・ネットワークいずれも正常
```

### コストの管理

**Q: 費用が高くならないか心配**

- 日常は **Sonnet** を使う（Opus より 60% 安い）
- `/cost` でいつでも費用を確認する
- `/compact` でコンテキストを圧縮してトークン消費を減らす
- 単純なタスクは **Haiku**（最安）
- [コスト最適化ガイド](/docs/usage/cost-optimization) も参照

### Claude がプロジェクトを理解しない

**Q: Claude がプロジェクト構造や規約をいつも取り違える**

`CLAUDE.md` を作ってください（第 5 章参照）。プロジェクトの背景・規約・よく使うコマンドを書いておけば、Claude は起動のたびに自動で読み込みます。

### 他のツールとの違い

**Q: Claude Code と Cursor / Copilot はどう違う？**

| ツール | 種別 | 特徴 |
|------|------|------|
| **Claude Code** | CLI エージェント | 自律的に計画・実行し、プロジェクト全体を理解する |
| **Cursor** | IDE | エディタに深く統合、リアルタイム補完 |
| **Copilot** | IDE プラグイン | 行単位の補完、簡単な提案 |

Claude Code は行単位の補完ツールではなく、エージェントレベルのアシスタント（複雑なタスクを自律的に完了できる）です。両者は併用できます：Cursor でリアルタイム編集と補完、Claude Code で複雑なタスクの計画と実行。

> **補足**：QCode.cc の同じ `cr_` キーは Claude Code や Codex CLI に加えて、多数の IDE / CLI / デスクトップアプリ（Cursor を含む）で使えます。Cursor の設定方法（カスタム Base URL + API Key）は [Cursor エディタ接続設定](/docs/ide/cursor)、プロトコル対応マトリクスと全一覧は [ツール互換性一覧](/docs/ide/tool-compatibility) を参照してください。

---

## 関連ドキュメント

- [インストールガイド](/docs/getting-started/installation) — 詳細なインストール手順
- [CLAUDE.md 設定ガイド](/docs/usage/claude-md) — プロジェクト設定の完全ガイド
- [Hooks システム](/docs/advanced/hooks) — 自動化フックの詳細
- [自動化と CI/CD](/docs/advanced/headless) — ヘッドレスモードの使い方
- [モデル選択ガイド](/docs/usage/model-selection) — モデルの詳細比較
- [コスト最適化](/docs/usage/cost-optimization) — 費用を抑えるコツ
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) — 2 つのツールの比較
- [Codex 完全ガイド](/docs/ide/codex) — Codex の使い方全般
- [プランと料金](https://qcode.cc/pricing) — QCode.cc のプラン