⚡ Claude Code Guide
← 早見表 コマンド一覧 →

01 基礎概念 — Claude Code とは

Claude Code の4つの形態

Claude Code は Anthropic が提供する AI コーディングアシスタント。4つの形態で利用できる。

形態 説明 使い方
CLI ターミナル文字だけでパソコンと対話する画面。コマンドを打ち込むと結果が文字で返ってくる。Claude Code CLIはここで動く上で動作。你的のメイン環境（WSL2） claude コマンドターミナルに入力してコンピュータに与える一行の指示。lsやcdのように『プログラム名+補足指定』で構成されるで起動
Desktop App Windows/Mac用のデスクトップアプリ スタンドアロンで起動
IDE拡張 VS Code・JetBrains用プラグイン本体に後から差し込んで機能を足す追加部品。Claude Codeにもプラグイン機構がある IDE内のパネルで操作
Web App claude.ai/code でブラウザから利用 ブラウザでアクセス

このガイドは主に CLI（WSL2環境） を前提に書かれている。

Desktop App と CLI の違い

⚠️ 公式の仕様「どう動くべきか」の取り決め。仕様書＝要件と動作の定義を書いた文書 を比較しています。個人のコスト最適化速さ・コスト・品質等の指標が良くなるように調整すること構成（GLM/MiniMaxルーティング等）は 15_コスト最適化構成 を参照。

比較表

項目 Desktop App CLI
起動方法 アプリをダブルクリック ターミナルで claude コマンド
画面 GUI（タブ・サイドバー・ビジュアルdiff） ターミナル（テキストのみ）
並行セッションClaude Codeの1回の対話単位。起動から終了までの会話と作業状態のこと。長く使うと内容が混ざるため、トピックの区切りで新セッションに引き継ぐ運用をする タブで視覚的に管理 バックグラウンドエージェント与えられた目標に向かって、自分で手順を組み立てて作業を進めるAIプログラム。質問に答えるだけのチャットAIと違い、「調べる→書く→確認する」を自律的に行う
変更差分変更前後の違い。git diffのように「何がどう変わったか」を示すもの 横並びビジュアル表示 テキストdiff（色付き）
コンテキスト上限 モデル依存（現行主力モデルは1M・Haiku 4.5のみ200k） 同左（モデル依存）
スクリプト自動実行できる小さなプログラム。手順を書いたテキストファイルの形をしている連携 不可 可（パイプコマンドの結果を次のコマンドへ流し込む「｜」記号の仕組み。「検索する → 結果を数える」のように処理をつなげられる・cronクロン。Linuxで「毎日6時」「30分ごと」等の定期実行を予約する仕組み。予約実行の登録表（crontab）に書いて運用する・hookClaude Codeの特定のタイミング（ツール実行前後・セッション開始時等）で自動処理を差し込む仕組み。「保存前にチェック」「終了時に記録」等を機械的に強制できる）
対応OS Windows / macOS のみ 全OS（Linux/WSL2/Mac/Windows）
設定ファイルプログラムの動作を決める設定値を書いたファイル。コード本体を書き換えずに、設定だけ変えられるようにする claude_desktop_config.json settings.json
HookClaude Codeの特定のタイミング（ツール実行前後・セッション開始時等）で自動処理を差し込む仕組み。「保存前にチェック」「終了時に記録」等を機械的に強制できる / Skill ✅ 対応 ✅ 対応
MCPModel Context Protocol（エムシーピー）の略。AIに外部ツール（検索・GitHub・データベース等）を繋ぐための共通接続規格。USBのような「差せば繋がる」仕組みでAIの能力を拡張するサーバー ✅ 対応 ✅ 対応

設定ファイルの場所

ファイル Desktop App CLI
メイン設定 AppData\Local\Packages\<pkg>\claude_desktop_config.json ~/.claude/settings.json
MCP起動コマンド wsl -d Ubuntu -- bash ...（WSL経由） bash ...（直接）

どちらを選ぶか

場面 おすすめ
視覚的な差分確認が欲しい Desktop App
ターミナル作業はCLIの方が慣れている CLI
Linux / WSL2 で使いたい CLI のみ
スクリプトやcronで自動化したい CLI のみ
複数プロジェクトを並行管理 Desktop App（タブ）

詳細: 自作MCPサーバー構造メモ

⚠️ Windows Desktop版とWSL2版は「別のホームディレクトリフォルダのこと。ファイルを階層的に整理する入れ物。Linux系ではフォルダをディレクトリと呼ぶのが普通を持つ別OS」

両者は同じPC上で動いていても、ファイルシステム的には完全に別人格である点に注意。

Windows Desktop版 WSL2版（CLI）
Bashツールの実体 Git Bash（MINGW64・Windows上で動作） Linux bashバッシュ。Linux等で使われる標準的なシェル（コマンド入力を受け付ける程序）の名前。シェルスクリプトを書く時の定番（WSL2仮想マシン）
ホームディレクトリ C:\Users\<user> /home/<user>
互いのファイルの見え方 \\wsl.localhost\Ubuntu\home\<user>\... 経由でのみ見える 通常はWindows側を直接見ない

この構造の違いが、handoff（セッション引き継ぎ）を介した環境またぎで具体的な不具合として表面化する。WSL2版で書かれたhandoff/SKILL.md/SSOTには~/projects/...のようなWSL基準のパスが書かれており、これをWindows Desktop版が読むと:

  1. パス解決の失敗: ~/projects/...がWindows側のC:\Users\...に誤解決され、ファイルが見つからない → 05_フック「PreToolUseでのコマンド書き換え」で自動変換するフックを導入済み
  2. GitHub認証「あなたは誰か」を確認すること。パスワードや鍵で本人であることを確かめる手続きの失敗: SSH鍵がWSL側のホームにしか存在せず、Windows側からはgit pushがPermission deniedになる → 08_設定ファイルでHTTPエイチティーティーピー。Webの通信で使われる基本的な約束事（プロトコル）。ブラウザとサーバー、プログラム同士のやり取りの共通言語S+gh CLI方式により解決済み

詳細: 2026-06-30_Windows-Desktop版WSLパス変換フック実装設計や仕様を、実際に動くコードに作り込むこと。「実装済み」＝コードとして完成している状態 / 2026-06-30_Windows-Desktop版GitHub認証問題解決

graph TD User["👤 ユーザー"] --> CLI["💻 Claude Code CLI"] CLI --> SP["📋 システムプロンプト"] CLI --> MCP["🔌 MCPツール定義"] CLI --> SK["🎯 スキル定義"] CLI --> MEM["🧠 メモリ読込"] CLI --> LLM["🤖 LLM"] LLM --> Tools["🔧 ツール実行"] Tools --> Files["📁 ファイル操作"] Tools --> Shell["💻 シェル実行"] Tools --> API["🌐 API呼出"] Tools --> Agent["🤖 サブエージェント"] LLM --> Resp["💬 レスポンス"] Resp --> User

アーキテクチャ

ユーザー（あなた）
  │
  ▼
Claude Code CLI（ターミナル）
  │
  ├─ システムプロンプトを読み込み（CLAUDE.md等）
  ├─ MCPツール定義を読み込み（83ツール）
  ├─ スキル定義を読み込み（30+スキル）
  ├─ メモリを読み込み（MEMORY.md等）
  │
  ▼
LLM（Claude Sonnet / Opus / Haiku）
  │
  ├─ ツール実行要求（Read, Edit, Bash, Agent等）
  │    ├─ ローカルファイル操作
  │    ├─ シェルコマンド実行
  │    ├─ MCPツール呼び出し（GitHub, Brave Search等）
  │    └─ サブエージェント起動
  │
  ▼
レスポンス（テキスト + ファイル変更）
  │
  ▼
ユーザーに表示

「Claude Code の本体」を一言で

上の図を LLM 視点 に翻訳すると、こうなる:

LLM が「ファイルを読む・書く・コマンドを撃つ」という道具を自分で選んで使い、 結果を見て次の行動を決めるループ同じ処理の繰り返し、または一連の作業サイクルのこと。プログラミングではfor文等の繰り返し構造、開発では「計画→実装→検証」の反復サイクルを指す

これが Claude Code の本体（=ハーネス）で、claude コマンドも Desktop App も、すべてこのループを 「人間にどう見せるか」の皮でしかありません。道具のカタログ（tools 配列）と実行結果のフィードバック が揃えば、別のアプリからも同じループを起動できます（Agent SDK / claude -p / MCPサーバー経由など）。

つまり「LLM にエージェント能力を与える」=「道具リストを渡して、応答に tool_use が現れたら実行して、 結果を tool_result として LLM に返す」だけ。このループを 1 回だけ回すのが単発エージェント、 終了条件を満たすまで回し直すのが自律ループ（= Loop Engineering） です。

用語 意味
ハーネス（harness） 上記のループ全体（tool 受付 → LLM 呼出 → 結果フィードバック）
tool calling LLM が応答の途中で「○○を実行して」と道具を要求する仕組み
自律ループ 終了条件（テスト緑・カバレッジテストがコードのどれくらいの割合を確認できているかを表す数字（％）。80%なら、コードの8割が少なくとも1回はテストで実行されたことになる達成等）を満たすまでループを回し続けること
サーキットブレーカ ループ暴走防止（429 検知・コスト上限・同一エラー N 回で停止）

Claude Code 固有の差別化要素は deny/ask/allow の権限ゲート・hooks・CLAUDE.md の自動注入 で、 これらはハーネスの「外側」を固める仕組み。ループ本体自体は Anthropic Agent SDK でも claude -p "..." でも自前実装でも再現できます。

graph LR subgraph "200K トークン コンテキストウィンドウ" A["システムプロンプト
~3%"] B["ツール定義
~20%"] C["メモリ・スキル
~4%"] D["会話履歴
~3%"] E["空き容量
~70%"] end

コンテキストの仕組み

Claude Code は コンテキストウィンドウAIが一度に「覚えていられる」会話・資料の容量上限のこと。作業が長くなると上限に近づき、古い内容の把握が荒くなる（＝自動で要約圧縮される）（現行主力モデルは最大1MトークンAIにとっての「文字数」のようなもの。AIは文章をトークンという小片に区切って処理する。課金や入力上限（コンテキストウィンドウ）はこの単位で数えられる・Haiku 4.5のみ200k）の中で動作する。セッション開始時に以下がロードされる。

コンテキストの構成要素

1M トークン（コンテキストウィンドウ上限・2026-08時点の主力モデル）
├── システムプロンプト      ~5.7k  (0.6%)   ← Claude Codeの基本ルール
├── システムツール定義     ~18.1k  (1.8%)   ← Read, Edit, Bash等のツール説明
├── MCPツール定義          ~21.4k (2.1%)   ← 83個のMCPツール説明
├── カスタムエージェント     ~2.9k  (0.3%)   ← エージェント定義
├── メモリファイル           ~2.5k  (0.3%)   ← CLAUDE.md + MEMORY.md
├── スキル定義               ~2.4k  (0.2%)   ← スキル一覧
├── メッセージ（会話履歴）   ~5.4k  (0.5%)   ← やり取りの履歴
└── 空き                    ~908.6k (90.9%)
    ※ Autocompact用バッファ   33k  (3.3%)

重要なポイント

<a id="autocompact"></a>自動コンパクション

空きが少なくなると、古い会話が自動的に要約される。これをオートコンパクションと呼ぶ。

用語定義: コンテキスト飽和・ペイロード肥大化（10_用語集）

入力と出力の非対称性

詳解: 11_現場の知見

Claude Codeでは入力トークン >> 出力トークンになるのが普通（比率は約13:1）。

理由は毎ターンで「システムプロンプトAIに最初から組み込まれている「基本の指示書」。ユーザーの発話とは別に、AIの振る舞い方の土台を決めている。CLAUDE.md等はここに近い形で常に読み込まれる + MCP定義 + メモリ + 過去会話すべて」を再送するため。チャットAI（ChatGPT等）では出力が多くなりがちだが、コーディングアシスタントでは逆転する。

また、1Mの実質使える量は約960K。システム・MCP・メモリで約40Kが固定消費される。

トークンとは

トークンはテキストの最小単位。日本語1文字 ≒ 1〜2トークン、英単語1語 ≒ 1トークン。

💡 やさしい補足（初心者向け）

この章に出てくる言葉を、できるだけ平たく言い直します。