Documentation 2026-07-28 23:57 UTC to 2026-07-29 07:01 UTC

12 12 

13<Warning>13<Warning>

14 開発コンテナは実質的な保護を提供していますが、すべての攻撃に完全に耐性のあるシステムはありません。14 開発コンテナは実質的な保護を提供していますが、すべての攻撃に完全に耐性のあるシステムはありません。

15 `--dangerously-skip-permissions` で実行する場合、開発コンテナは、[`~/.claude`](/ja/claude-directory) に保存されている Claude Code の認証情報を含む、コンテナ内でアクセス可能なものを悪意のあるプロジェクトが流出させることを防ぎません。15 `--dangerously-skip-permissions` で実行する場合、開発コンテナは、[`~/.claude`](/docs/ja/claude-directory) に保存されている Claude Code の認証情報を含む、コンテナ内でアクセス可能なものを悪意のあるプロジェクトが流出させることを防ぎません。

16 信頼できるリポジトリで開発する場合にのみ開発コンテナを使用し、Claude のアクティビティを監視してください。16 信頼できるリポジトリで開発する場合にのみ開発コンテナを使用し、Claude のアクティビティを監視してください。

17 `~/.ssh` やクラウド認証情報ファイルなどのホストシークレットをコンテナにマウントすることは避け、リポジトリスコープまたは短期間有効なトークンを使用してください。17 `~/.ssh` やクラウド認証情報ファイルなどのホストシークレットをコンテナにマウントすることは避け、リポジトリスコープまたは短期間有効なトークンを使用してください。

18</Warning>18</Warning>

20<Accordion title="開発コンテナがエディタとどのように連携するか">20<Accordion title="開発コンテナがエディタとどのように連携するか">

21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="ホスト上のエディタが Docker 開発コンテナに接続する図。Claude Code、ターミナル、ビルドツールはコンテナ内で実行されます。ホストリポジトリはコンテナにバインドマウントされ、ワークスペースとして機能します。" width="640" height="300" data-path="images/devcontainer-architecture.svg" />21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="ホスト上のエディタが Docker 開発コンテナに接続する図。Claude Code、ターミナル、ビルドツールはコンテナ内で実行されます。ホストリポジトリはコンテナにバインドマウントされ、ワークスペースとして機能します。" width="640" height="300" data-path="images/devcontainer-architecture.svg" />

22 22 

23 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=ef00c8e25b1ea7a3a152895f1488831b" className="hidden dark:block" alt="ホスト上のエディタが Docker 開発コンテナに接続する図。Claude Code、ターミナル、ビルドツールはコンテナ内で実行されます。ホストリポジトリはコンテナにバインドマウントされ、ワークスペースとして機能します。" width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />23 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="ホスト上のエディタが Docker 開発コンテナに接続する図。Claude Code、ターミナル、ビルドツールはコンテナ内で実行されます。ホストリポジトリはコンテナにバインドマウントされ、ワークスペースとして機能します。" width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />

24 24 

25 開発コンテナは Docker コンテナとして実行され、マシン上または GitHub Codespaces などのクラウドホスト上で実行されます。Dev Containers 仕様をサポートするエディタ（VS Code、GitHub Codespaces、JetBrains IDE、Cursor など）がそのコンテナに接続します。通常どおりエディタでファイルを参照および編集しますが、統合ターミナル、言語サーバー、ビルドツールはすべてホストではなくコンテナ内で実行されます。プレーン Vim などの開発コンテナをサポートしていないエディタはこのワークフローの対象外です。25 開発コンテナは Docker コンテナとして実行され、マシン上または GitHub Codespaces などのクラウドホスト上で実行されます。Dev Containers 仕様をサポートするエディタ（VS Code、GitHub Codespaces、JetBrains IDE、Cursor など）がそのコンテナに接続します。通常どおりエディタでファイルを参照および編集しますが、統合ターミナル、言語サーバー、ビルドツールはすべてホストではなくコンテナ内で実行されます。プレーン Vim などの開発コンテナをサポートしていないエディタはこのワークフローの対象外です。

26 26 

27 Claude Code はコンテナ内で実行されるため、プロジェクトのツールチェーンの残りの部分と同じファイル、依存関係、ツールが表示されます。VS Code では、[Claude Code 拡張機能パネル](/ja/vs-code)を使用するか、統合ターミナルで `claude` を実行できます。どちらもコンテナ内で実行され、同じ `~/.claude` 設定を共有します。27 Claude Code はコンテナ内で実行されるため、プロジェクトのツールチェーンの残りの部分と同じファイル、依存関係、ツールが表示されます。VS Code では、[Claude Code 拡張機能パネル](/docs/ja/vs-code)を使用するか、統合ターミナルで `claude` を実行できます。どちらもコンテナ内で実行され、同じ `~/.claude` 設定を共有します。

28</Accordion>28</Accordion>

29 29 

30<h2 id="add-claude-code-to-your-dev-container">30<h2 id="add-claude-code-to-your-dev-container">

75認証プロンプトで表示される内容は、プロバイダーによって異なります：75認証プロンプトで表示される内容は、プロバイダーによって異なります：

76 76 

77* **Anthropic**：Claude または Anthropic Console アカウントでブラウザ経由でサインイン77* **Anthropic**：Claude または Anthropic Console アカウントでブラウザ経由でサインイン

78* **[Amazon Bedrock、Google Cloud の Agent Platform、または Microsoft Foundry](/ja/third-party-integrations)**：Claude Code はクラウドプロバイダーの認証情報を使用し、ブラウザプロンプトはありません78* **[Amazon Bedrock、Google Cloud の Agent Platform、または Microsoft Foundry](/docs/ja/third-party-integrations)**：Claude Code はクラウドプロバイダーの認証情報を使用し、ブラウザプロンプトはありません

79 79 

80クラウドプロバイダーの場合、ホストから認証情報ファイルをマウントするのではなく、`containerEnv`、Codespaces シークレット、またはクラウドのワークロード ID を通じて認証情報をコンテナに渡します。Claude Code が読み取る認証情報チェーンについては、[Amazon Bedrock](/ja/amazon-bedrock)、[Google Cloud の Agent Platform](/ja/google-vertex-ai)、または [Microsoft Foundry](/ja/microsoft-foundry) を参照してください。80クラウドプロバイダーの場合、ホストから認証情報ファイルをマウントするのではなく、`containerEnv`、Codespaces シークレット、またはクラウドのワークロード ID を通じて認証情報をコンテナに渡します。Claude Code が読み取る認証情報チェーンについては、[Amazon Bedrock](/docs/ja/amazon-bedrock)、[Google Cloud の Agent Platform](/docs/ja/google-vertex-ai)、または [Microsoft Foundry](/docs/ja/microsoft-foundry) を参照してください。

81 81 

82どのパスが組織に適しているかを決定するには、[API プロバイダーを選択する](/ja/admin-setup#choose-your-api-provider)を参照してください。82どのパスが組織に適しているかを決定するには、[API プロバイダーを選択する](/docs/ja/admin-setup#choose-your-api-provider)を参照してください。

83 83 

84<Note>84<Note>

85 ブラウザサインインが完了しても、コールバックがコンテナに到達しない場合は、ブラウザに表示されているコードをコピーして、ターミナルの `Paste code here if prompted` プロンプトに貼り付けます。これは、エディタのポート転送が localhost コールバックをルーティングしない場合に発生する可能性があります。85 ブラウザサインインが完了しても、コールバックがコンテナに到達しない場合は、ブラウザに表示されているコードをコピーして、ターミナルの `Paste code here if prompted` プロンプトに貼り付けます。これは、エディタのポート転送が localhost コールバックをルーティングしない場合に発生する可能性があります。

89 再構築時に認証と設定を保持する89 再構築時に認証と設定を保持する

90</h2>90</h2>

91 91 

92デフォルトでは、コンテナのホームディレクトリは再構築時に破棄されるため、エンジニアは毎回サインインし直す必要があります。Claude Code は認証トークン、ユーザー設定、セッション履歴を [`~/.claude`](/ja/claude-directory) に保存します。そのパスに名前付きボリュームをマウントして、再構築時にこの状態を保持します。92デフォルトでは、コンテナのホームディレクトリは再構築時に破棄されるため、エンジニアは毎回サインインし直す必要があります。Claude Code は認証トークン、ユーザー設定、セッション履歴を [`~/.claude`](/docs/ja/claude-directory) に保存します。そのパスに名前付きボリュームをマウントして、再構築時にこの状態を保持します。

93 93 

94以下の例は、`node` ユーザーのホームディレクトリにボリュームをマウントします：94以下の例は、`node` ユーザーのホームディレクトリにボリュームをマウントします：

95 95 

99]99]

100```100```

101 101 

102`/home/node` をコンテナの `remoteUser` のホームディレクトリに置き換えます。ボリュームを `~/.claude` 以外の場所にマウントする場合は、[`CLAUDE_CONFIG_DIR`](/ja/env-vars) をマウントパスに設定して、Claude Code がそこで読み書きするようにします。102`/home/node` をコンテナの `remoteUser` のホームディレクトリに置き換えます。ボリュームを `~/.claude` 以外の場所にマウントする場合は、[`CLAUDE_CONFIG_DIR`](/docs/ja/env-vars) をマウントパスに設定して、Claude Code がそこで読み書きするようにします。

103 103 

104プロジェクトごとに状態を分離して、すべてのリポジトリ間で 1 つのボリュームを共有しないようにするには、ソース名に `${devcontainerId}` 変数を含めます。[リファレンス設定](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)はこの目的で `source=claude-code-config-${devcontainerId}` を使用しています。104プロジェクトごとに状態を分離して、すべてのリポジトリ間で 1 つのボリュームを共有しないようにするには、ソース名に `${devcontainerId}` 変数を含めます。[リファレンス設定](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)はこの目的で `source=claude-code-config-${devcontainerId}` を使用しています。

105 105 

106GitHub Codespaces では、`~/.claude` は codespace の停止と開始の間で保持されますが、コンテナを再構築するときはまだクリアされるため、上記のボリュームマウントがそこにも適用されます。codespace 間で認証を実行するには、[Codespaces シークレット](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)として `ANTHROPIC_API_KEY` または [`claude setup-token`](/ja/authentication#generate-a-long-lived-token) からの `CLAUDE_CODE_OAUTH_TOKEN` を保存します。Codespaces はシークレットを自動的にコンテナ内の環境変数として利用可能にします。106GitHub Codespaces では、`~/.claude` は codespace の停止と開始の間で保持されますが、コンテナを再構築するときはまだクリアされるため、上記のボリュームマウントがそこにも適用されます。codespace 間で認証を実行するには、[Codespaces シークレット](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)として `ANTHROPIC_API_KEY` または [`claude setup-token`](/docs/ja/authentication#generate-a-long-lived-token) からの `CLAUDE_CODE_OAUTH_TOKEN` を保存します。Codespaces はシークレットを自動的にコンテナ内の環境変数として利用可能にします。

107 107 

108<h2 id="enforce-organization-policy">108<h2 id="enforce-organization-policy">

109 組織ポリシーを適用する109 組織ポリシーを適用する

111 111 

112開発コンテナは、同じイメージと設定がすべてのエンジニアのマシンで実行されるため、組織ポリシーを適用するのに便利な場所です。112開発コンテナは、同じイメージと設定がすべてのエンジニアのマシンで実行されるため、組織ポリシーを適用するのに便利な場所です。

113 113 

114Claude Code は Linux で `/etc/claude-code/managed-settings.json` を読み取り、[設定階層](/ja/settings#how-scopes-interact)で最高の優先度で適用するため、そこの値はエンジニアが `~/.claude` またはプロジェクトの `.claude/` ディレクトリで設定したものをオーバーライドします。Dockerfile からファイルをコピーして配置します：114Claude Code は Linux で `/etc/claude-code/managed-settings.json` を読み取り、[設定階層](/docs/ja/settings#how-scopes-interact)で最高の優先度で適用するため、そこの値はエンジニアが `~/.claude` またはプロジェクトの `.claude/` ディレクトリで設定したものをオーバーライドします。Dockerfile からファイルをコピーして配置します：

115 115 

116```dockerfile Dockerfile theme={null}116```dockerfile Dockerfile theme={null}

117RUN mkdir -p /etc/claude-code117RUN mkdir -p /etc/claude-code

118COPY managed-settings.json /etc/claude-code/managed-settings.json118COPY managed-settings.json /etc/claude-code/managed-settings.json

119```119```

120 120 

121Dockerfile はリポジトリに存在するため、書き込みアクセス権を持つ誰でもこのステップを変更または削除できます。エンジニアがリポジトリファイルを編集してバイパスできないポリシーについては、[サーバー管理設定](/ja/server-managed-settings)または MDM を通じて管理設定を配信します。利用可能なキーと他の配信パスについては、[管理設定ファイル](/ja/settings#settings-files)を参照してください。121Dockerfile はリポジトリに存在するため、書き込みアクセス権を持つ誰でもこのステップを変更または削除できます。エンジニアがリポジトリファイルを編集してバイパスできないポリシーについては、[サーバー管理設定](/docs/ja/server-managed-settings)または MDM を通じて管理設定を配信します。利用可能なキーと他の配信パスについては、[管理設定ファイル](/docs/ja/settings#settings-files)を参照してください。

122 122 

123コンテナ内のすべての Claude Code セッションに適用される[環境変数](/ja/env-vars)を設定するには、`devcontainer.json` の `containerEnv` に追加します。以下の例は、テレメトリとエラーレポートをオプトアウトし、Claude Code がインストール後に自動更新されるのを防ぎます：123コンテナ内のすべての Claude Code セッションに適用される[環境変数](/docs/ja/env-vars)を設定するには、`devcontainer.json` の `containerEnv` に追加します。以下の例は、テレメトリとエラーレポートをオプトアウトし、Claude Code がインストール後に自動更新されるのを防ぎます：

124 124 

125```json devcontainer.json theme={null}125```json devcontainer.json theme={null}

126"containerEnv": {126"containerEnv": {

131 131 

132Dev Container Feature は常に最新の Claude Code リリースをインストールします。再現可能なビルドのために特定の Claude Code バージョンをピン留めするには、機能を使用する代わりに Dockerfile から `npm install -g @anthropic-ai/claude-code@X.Y.Z` でインストールし、上記のように `DISABLE_AUTOUPDATER` を設定します。132Dev Container Feature は常に最新の Claude Code リリースをインストールします。再現可能なビルドのために特定の Claude Code バージョンをピン留めするには、機能を使用する代わりに Dockerfile から `npm install -g @anthropic-ai/claude-code@X.Y.Z` でインストールし、上記のように `DISABLE_AUTOUPDATER` を設定します。

133 133 

134権限ルール、ツール制限、MCP サーバーアローリストを含むポリシーコントロールの完全なリストについては、[組織向けに Claude Code をセットアップする](/ja/admin-setup)を参照してください。134権限ルール、ツール制限、MCP サーバーアローリストを含むポリシーコントロールの完全なリストについては、[組織向けに Claude Code をセットアップする](/docs/ja/admin-setup)を参照してください。

135 135 

136[MCP サーバー](/ja/mcp)をコンテナ内で利用可能にするには、リポジトリルートの `.mcp.json` ファイルで[プロジェクトスコープ](/ja/mcp#mcp-installation-scopes)で定義して、開発コンテナ設定と一緒にチェックインします。ローカル stdio サーバーが依存するバイナリを Dockerfile にインストールし、リモートサーバードメインをネットワークアローリストに追加します。136[MCP サーバー](/docs/ja/mcp)をコンテナ内で利用可能にするには、リポジトリルートの `.mcp.json` ファイルで[プロジェクトスコープ](/docs/ja/mcp#mcp-installation-scopes)で定義して、開発コンテナ設定と一緒にチェックインします。ローカル stdio サーバーが依存するバイナリを Dockerfile にインストールし、リモートサーバードメインをネットワークアローリストに追加します。

137 137 

138<h2 id="restrict-network-egress">138<h2 id="restrict-network-egress">

139 ネットワークエグレスを制限する139 ネットワークエグレスを制限する

140</h2>140</h2>

141 141 

142コンテナのアウトバウンドトラフィックを Claude Code が必要とするドメインのみに制限できます。推論と認証ドメインについては[ネットワークアクセス要件](/ja/network-config#network-access-requirements)を参照し、オプションのテレメトリとエラーレポート接続およびそれらを無効にする方法については[テレメトリサービス](/ja/data-usage#telemetry-services)を参照してください。142コンテナのアウトバウンドトラフィックを Claude Code が必要とするドメインのみに制限できます。推論と認証ドメインについては[ネットワークアクセス要件](/docs/ja/network-config#network-access-requirements)を参照し、オプションのテレメトリとエラーレポート接続およびそれらを無効にする方法については[テレメトリサービス](/docs/ja/data-usage#telemetry-services)を参照してください。

143 143 

144リファレンスコンテナには、Claude Code と開発ツールが必要とするドメイン以外のすべてのアウトバウンドトラフィックをブロックする [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) スクリプトが含まれています。コンテナ内でファイアウォールを実行するには追加の権限が必要なため、リファレンスは `runArgs` を通じて `NET_ADMIN` と `NET_RAW` 機能を追加します。ファイアウォールスクリプトとこれらの機能は Claude Code 自体には必須ではありません。これらを除外して、代わりに独自のネットワークコントロールに依存することができます。144リファレンスコンテナには、Claude Code と開発ツールが必要とするドメイン以外のすべてのアウトバウンドトラフィックをブロックする [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) スクリプトが含まれています。コンテナ内でファイアウォールを実行するには追加の権限が必要なため、リファレンスは `runArgs` を通じて `NET_ADMIN` と `NET_RAW` 機能を追加します。ファイアウォールスクリプトとこれらの機能は Claude Code 自体には必須ではありません。これらを除外して、代わりに独自のネットワークコントロールに依存することができます。

145 145 

151 151 

152権限プロンプトをスキップすると、実行前にツール呼び出しを確認する機会が失われます。Claude はバインドマウントされたワークスペース内のあらゆるファイルを変更でき、これはホストに直接表示され、コンテナのネットワークポリシーが許可するものに到達できます。このフラグを上記の[ネットワークエグレス制限](#restrict-network-egress)と組み合わせて、バイパスされたセッションが到達できるものを制限します。152権限プロンプトをスキップすると、実行前にツール呼び出しを確認する機会が失われます。Claude はバインドマウントされたワークスペース内のあらゆるファイルを変更でき、これはホストに直接表示され、コンテナのネットワークポリシーが許可するものに到達できます。このフラグを上記の[ネットワークエグレス制限](#restrict-network-egress)と組み合わせて、バイパスされたセッションが到達できるものを制限します。

153 153 

154安全チェックを無効にせずにプロンプトを減らしたい場合は、代わりに[自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)を検討してください。これは、実行前にアクションを確認するための分類器を備えています。エンジニアが `--dangerously-skip-permissions` をまったく使用できないようにするには、[管理設定](/ja/settings#permission-settings)で `permissions.disableBypassPermissionsMode` を `"disable"` に設定します。154安全チェックを無効にせずにプロンプトを減らしたい場合は、代わりに[自動モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)を検討してください。これは、実行前にアクションを確認するための分類器を備えています。エンジニアが `--dangerously-skip-permissions` をまったく使用できないようにするには、[管理設定](/docs/ja/settings#permission-settings)で `permissions.disableBypassPermissionsMode` を `"disable"` に設定します。

155 155 

156<h2 id="try-the-reference-container">156<h2 id="try-the-reference-container">

157 リファレンスコンテナを試す157 リファレンスコンテナを試す

193 193 

194Claude Code が開発コンテナで実行されたら、以下のページは組織ロールアウトの残りの部分をカバーしています。認証パスの選択、リポジトリ外での管理ポリシーの配信、使用状況の監視、Claude Code が保存および送信するものの理解です。194Claude Code が開発コンテナで実行されたら、以下のページは組織ロールアウトの残りの部分をカバーしています。認証パスの選択、リポジトリ外での管理ポリシーの配信、使用状況の監視、Claude Code が保存および送信するものの理解です。

195 195 

196* [組織向けに Claude Code をセットアップする](/ja/admin-setup)：認証プロバイダーを選択し、ポリシーがデバイスに到達する方法を決定し、ロールアウトを計画します196* [組織向けに Claude Code をセットアップする](/docs/ja/admin-setup)：認証プロバイダーを選択し、ポリシーがデバイスに到達する方法を決定し、ロールアウトを計画します

197* [サーバー管理設定](/ja/server-managed-settings)：Claude.ai 管理コンソールから管理ポリシーを配信して、エンジニアがリポジトリファイルを編集してバイパスできないようにします197* [サーバー管理設定](/docs/ja/server-managed-settings)：Claude.ai 管理コンソールから管理ポリシーを配信して、エンジニアがリポジトリファイルを編集してバイパスできないようにします

198* [使用状況の監視と監査アクティビティ](/ja/monitoring-usage)：OpenTelemetry メトリクスをエクスポートして、チームが実行しているものを確認します198* [使用状況の監視と監査アクティビティ](/docs/ja/monitoring-usage)：OpenTelemetry メトリクスをエクスポートして、チームが実行しているものを確認します

199* [ネットワークアクセス要件](/ja/network-config#network-access-requirements)：プロキシとファイアウォール用の完全なドメインアローリスト199* [ネットワークアクセス要件](/docs/ja/network-config#network-access-requirements)：プロキシとファイアウォール用の完全なドメインアローリスト

200* [テレメトリサービスとオプトアウト](/ja/data-usage#telemetry-services)：Claude Code がデフォルトで送信するもの、およびそれを無効にする環境変数200* [テレメトリサービスとオプトアウト](/docs/ja/data-usage#telemetry-services)：Claude Code がデフォルトで送信するもの、およびそれを無効にする環境変数

201* [`.claude` ディレクトリを探索する](/ja/claude-directory)：ボリュームマウントが保持するもの（認証情報、設定、セッション履歴を含む）201* [`.claude` ディレクトリを探索する](/docs/ja/claude-directory)：ボリュームマウントが保持するもの（認証情報、設定、セッション履歴を含む）

202* [サンドボックス環境](/ja/sandbox-environments)：開発コンテナと組み込み Bash サンドボックス、カスタムコンテナ、VM を比較します202* [サンドボックス環境](/docs/ja/sandbox-environments)：開発コンテナと組み込み Bash サンドボックス、カスタムコンテナ、VM を比較します

203* [セキュリティモデル](/ja/security)：Claude Code の権限システム、サンドボックス、プロンプトインジェクション保護がどのように組み合わさるか203* [セキュリティモデル](/docs/ja/security)：Claude Code の権限システム、サンドボックス、プロンプトインジェクション保護がどのように組み合わさるか

204* [権限モード](/ja/permission-modes)：プランモードから自動モードからバイパスまでの完全な範囲、および各モードを使用する場合204* [権限モード](/docs/ja/permission-modes)：プランモードから自動モードからバイパスまでの完全な範囲、および各モードを使用する場合

20 20 

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="4 つのターンが成長する水平バーとして表示されます。各ターンのリクエストには、前のターンのすべてと最新の交換が最後に追加されたものが含まれます。ターン 2 と 3 では、変更されていないプリフィックスはキャッシュから読み取られ、新しい交換のみが処理されます。ターン 4 では、システムプロンプトが変更されたため、プリフィックスは一致しなくなり、リクエスト全体が再処理されて書き込まれます。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="4 つのターンが成長する水平バーとして表示されます。各ターンのリクエストには、前のターンのすべてと最新の交換が最後に追加されたものが含まれます。ターン 2 と 3 では、変更されていないプリフィックスはキャッシュから読み取られ、新しい交換のみが処理されます。ターン 4 では、システムプロンプトが変更されたため、プリフィックスは一致しなくなり、リクエスト全体が再処理されて書き込まれます。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22 

23<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=7434a04e08187edd26ec6c3dd332f624" className="hidden dark:block" alt="4 つのターンが成長する水平バーとして表示されます。各ターンのリクエストには、前のターンのすべてと最新の交換が最後に追加されたものが含まれます。ターン 2 と 3 では、変更されていないプリフィックスはキャッシュから読み取られ、新しい交換のみが処理されます。ターン 4 では、システムプロンプトが変更されたため、プリフィックスは一致しなくなり、リクエスト全体が再処理されて書き込まれます。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="4 つのターンが成長する水平バーとして表示されます。各ターンのリクエストには、前のターンのすべてと最新の交換が最後に追加されたものが含まれます。ターン 2 と 3 では、変更されていないプリフィックスはキャッシュから読み取られ、新しい交換のみが処理されます。ターン 4 では、システムプロンプトが変更されたため、プリフィックスは一致しなくなり、リクエスト全体が再処理されて書き込まれます。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24 

25プリフィックスマッチングを最大限に活用するために、Claude Code は各リクエストを順序付けして、ターン間で変更されることがめったにないコンテンツが最初に来るようにします。25プリフィックスマッチングを最大限に活用するために、Claude Code は各リクエストを順序付けして、ターン間で変更されることがめったにないコンテンツが最初に来るようにします。

26 26 

32 32 

33会話レイヤーへの変更は、システムプロンプトとプロジェクトコンテキストをキャッシュしたままにします。システムプロンプトへの変更は、すべての後続コンテンツが異なるプリフィックスの後ろに配置されるため、すべてを無効にします。3 番目の列は、完全なリストではなく一般的なトリガーを示しており、以下のセクションでは、セッション開始時に固定される出力スタイルなどのコンテンツを含む完全なセットについて説明します。33会話レイヤーへの変更は、システムプロンプトとプロジェクトコンテキストをキャッシュしたままにします。システムプロンプトへの変更は、すべての後続コンテンツが異なるプリフィックスの後ろに配置されるため、すべてを無効にします。3 番目の列は、完全なリストではなく一般的なトリガーを示しており、以下のセクションでは、セッション開始時に固定される出力スタイルなどのコンテンツを含む完全なセットについて説明します。

34 34 

35プリフィックスマッチルールは、このページのほとんどの動作を説明しています。たとえば、[Plan mode](/ja/permission-modes#analyze-before-you-edit-with-plan-mode) と[スキル読み込み](/ja/skills)は、会話メッセージとして命令を追加するため、キャッシュされたプリフィックスはそのままです。35プリフィックスマッチルールは、このページのほとんどの動作を説明しています。たとえば、[Plan mode](/docs/ja/permission-modes#analyze-before-you-edit-with-plan-mode) と[スキル読み込み](/docs/ja/skills)は、会話メッセージとして命令を追加するため、キャッシュされたプリフィックスはそのままです。

36 36 

372 つの設定はプロンプトテキストの一部ではないため、レイヤーテーブルに表示されません。ただし、どちらもキャッシュキーの一部です。372 つの設定はプロンプトテキストの一部ではないため、レイヤーテーブルに表示されません。ただし、どちらもキャッシュキーの一部です。

38 38 

49 49 

50キャッシングはサーバー側で行われ、モデルを提供するインフラストラクチャで行われます。その場所は、認証方法によって異なります。50キャッシングはサーバー側で行われ、モデルを提供するインフラストラクチャで行われます。その場所は、認証方法によって異なります。

51 51 

52* **API キー、Claude サブスクリプション、または[Claude Platform on AWS](/ja/claude-platform-on-aws)**: キャッシュは Anthropic のインフラストラクチャに存在し、[Claude API](https://platform.claude.com/docs) を通じてアクセスされます52* **API キー、Claude サブスクリプション、または[Claude Platform on AWS](/docs/ja/claude-platform-on-aws)**: キャッシュは Anthropic のインフラストラクチャに存在し、[Claude API](https://platform.claude.com/docs) を通じてアクセスされます

53* **Amazon Bedrock または Google Cloud の Agent Platform**: キャッシュはクラウドプロバイダーのサービングインフラストラクチャに存在します53* **Amazon Bedrock または Google Cloud の Agent Platform**: キャッシュはクラウドプロバイダーのサービングインフラストラクチャに存在します

54* **Microsoft Foundry**: リクエストは Anthropic のインフラストラクチャにルーティングされます54* **Microsoft Foundry**: リクエストは Anthropic のインフラストラクチャにルーティングされます

55* **カスタム `ANTHROPIC_BASE_URL` または[LLM gateway](/ja/llm-gateway)**: キャッシュはリクエストが転送される場所に存在し、キャッシングが機能するかどうかはゲートウェイに依存します55* **カスタム `ANTHROPIC_BASE_URL` または[LLM gateway](/docs/ja/llm-gateway)**: キャッシュはリクエストが転送される場所に存在し、キャッシングが機能するかどうかはゲートウェイに依存します

56 56 

57各プロバイダーが保存および処理するものについては、[データ使用](/ja/data-usage)を参照してください。キャッシュがどこに存在するかに関わらず、エントリは非アクティブ期間後に期限切れになり、以下の[キャッシュライフタイム](#cache-lifetime)は TTL とそれを延長する方法について説明します。57各プロバイダーが保存および処理するものについては、[データ使用](/docs/ja/data-usage)を参照してください。キャッシュがどこに存在するかに関わらず、エントリは非アクティブ期間後に期限切れになり、以下の[キャッシュライフタイム](#cache-lifetime)は TTL とそれを延長する方法について説明します。

58 58 

59<h2 id="actions-that-invalidate-the-cache">59<h2 id="actions-that-invalidate-the-cache">

60 キャッシュを無効にするアクション60 キャッシュを無効にするアクション

75 モデルの切り替え75 モデルの切り替え

76</h3>76</h3>

77 77 

78各モデルは独自のキャッシュを持ちます。[`/model`](/ja/model-config#setting-your-model) で切り替えると、次のリクエストはコンテンツが同じであっても、キャッシュヒットなしで会話履歴全体を読み取ります。78各モデルは独自のキャッシュを持ちます。[`/model`](/docs/ja/model-config#setting-your-model) で切り替えると、次のリクエストはコンテンツが同じであっても、キャッシュヒットなしで会話履歴全体を読み取ります。

79 79 

80[`opusplan` モデル設定](/ja/model-config#opusplan-model-setting)は、Plan Mode 中に Opus に、実行中に Sonnet に解決されるため、各 Plan Mode トグルはモデル切り替えであり、新しいキャッシュを開始します。80[`opusplan` モデル設定](/docs/ja/model-config#opusplan-model-setting)は、Plan Mode 中に Opus に、実行中に Sonnet に解決されるため、各 Plan Mode トグルはモデル切り替えであり、新しいキャッシュを開始します。

81 81 

82[Fable 5 での自動モデルフォールバック](/ja/model-config#automatic-model-fallback)もモデル切り替えです。安全性分類器がリクエストにフラグを立てると、Claude Code はデフォルトの Opus モデルで再実行し、セッションはそこで続行されます。82[Fable 5 での自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)もモデル切り替えです。安全性分類器がリクエストにフラグを立てると、Claude Code はデフォルトの Opus モデルで再実行し、セッションはそこで続行されます。

83 83 

84<h3 id="changing-effort-level">84<h3 id="changing-effort-level">

85 努力レベルの変更85 努力レベルの変更

86</h3>86</h3>

87 87 

88キャッシュは[努力レベル](/ja/model-config#adjust-effort-level)とモデルの両方によってキー付けされるため、`/effort` で切り替えると、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。会話が開始されたら、Claude Code はキャッシュを無効にする努力レベルの変更を適用する前に確認ダイアログを表示します。モデルのデフォルトを明示的に設定するなど、既に有効な同じレベルに解決される変更は、ダイアログをスキップしてキャッシュを保持します。88キャッシュは[努力レベル](/docs/ja/model-config#adjust-effort-level)とモデルの両方によってキー付けされるため、`/effort` で切り替えると、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。会話が開始されたら、Claude Code はキャッシュを無効にする努力レベルの変更を適用する前に確認ダイアログを表示します。モデルのデフォルトを明示的に設定するなど、既に有効な同じレベルに解決される変更は、ダイアログをスキップしてキャッシュを保持します。

89 89 

90<h3 id="turning-on-fast-mode">90<h3 id="turning-on-fast-mode">

91 高速モードの有効化91 高速モードの有効化

92</h3>92</h3>

93 93 

94[高速モード](/ja/fast-mode)を有効にすると、キャッシュキーの一部であるリクエストヘッダーが追加されるため、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。これらのキャッシュされていない入力トークンは[高速モードレート](/ja/fast-mode#understand-the-cost-tradeoff)で課金されます。これが、セッションの開始時に有効にする方が、長いセッションの深くで有効にするよりもコストが低い理由です。非 Opus モデルから高速モードを有効にすると、[モデルも切り替わります](#switching-models)。これにより、独自に新しいキャッシュが開始されます。94[高速モード](/docs/ja/fast-mode)を有効にすると、キャッシュキーの一部であるリクエストヘッダーが追加されるため、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。これらのキャッシュされていない入力トークンは[高速モードレート](/docs/ja/fast-mode#understand-the-cost-tradeoff)で課金されます。これが、セッションの開始時に有効にする方が、長いセッションの深くで有効にするよりもコストが低い理由です。非 Opus モデルから高速モードを有効にすると、[モデルも切り替わります](#switching-models)。これにより、独自に新しいキャッシュが開始されます。

95 95 

96コストはキャッシュごとに 1 回適用されます。最初の高速モードターンの後、Claude Code はヘッダーを送信し続け、リクエストの速度設定のみを変更します。これはキャッシュキーの一部ではありません。高速モードをオフにする、[レート制限後の標準速度への自動フォールバック](/ja/fast-mode#handle-rate-limits)、および後で再度有効にすることはすべてキャッシュを保持します。`/clear` と `/compact` はこれをリセットします。これらはとにかくそれらのポイントでキャッシュを再構築するためです。96コストはキャッシュごとに 1 回適用されます。最初の高速モードターンの後、Claude Code はヘッダーを送信し続け、リクエストの速度設定のみを変更します。これはキャッシュキーの一部ではありません。高速モードをオフにする、[レート制限後の標準速度への自動フォールバック](/docs/ja/fast-mode#handle-rate-limits)、および後で再度有効にすることはすべてキャッシュを保持します。`/clear` と `/compact` はこれをリセットします。これらはとにかくそれらのポイントでキャッシュを再構築するためです。

97 97 

98<h3 id="connecting-or-disconnecting-an-mcp-server">98<h3 id="connecting-or-disconnecting-an-mcp-server">

99 MCP サーバーの接続または切断99 MCP サーバーの接続または切断

100</h3>100</h3>

101 101 

102ツール定義はシステムプロンプトレイヤーに存在するため、リクエスト間でリクエスト内のツール定義のセットが変更されるとキャッシュが無効になります。[advisor ツール](/ja/advisor)のトグルは例外です。その定義はキャッシュブレークポイントの後に存在するため、`/advisor` を有効化または無効化してもキャッシュされたプリフィックスはそのままです。[MCP サーバー](/ja/mcp)の変更がこれを行うかどうかは、そのツールが[ツール検索](/ja/mcp#scale-with-mcp-tool-search)によって遅延されるか、プリフィックスに読み込まれるかによって異なります。102ツール定義はシステムプロンプトレイヤーに存在するため、リクエスト間でリクエスト内のツール定義のセットが変更されるとキャッシュが無効になります。[advisor ツール](/docs/ja/advisor)のトグルは例外です。その定義はキャッシュブレークポイントの後に存在するため、`/advisor` を有効化または無効化してもキャッシュされたプリフィックスはそのままです。[MCP サーバー](/docs/ja/mcp)の変更がこれを行うかどうかは、そのツールが[ツール検索](/docs/ja/mcp#scale-with-mcp-tool-search)によって遅延されるか、プリフィックスに読み込まれるかによって異なります。

103 103 

104* **遅延ツール**、サポートされているモデルのデフォルト：サーバーの接続、切断、またはツールリストの変更は、新しいコンテンツのみを追加し、既にキャッシュされているものを妨害しません。104* **遅延ツール**、サポートされているモデルのデフォルト：サーバーの接続、切断、またはツールリストの変更は、新しいコンテンツのみを追加し、既にキャッシュされているものを妨害しません。

105* **プリフィックスに読み込まれるツール**：それらへの変更はキャッシュを無効にします。これは[ツール検索が利用不可または無効](/ja/mcp#configure-tool-search)な場合に発生します。Google Cloud の Agent Platform またはカスタム `ANTHROPIC_BASE_URL` ゲートウェイなど。また、[`alwaysLoad`](/ja/mcp#exempt-a-server-from-deferral)とマークされたサーバーまたはツール、および[しきい値ベースの読み込み](/ja/mcp#configure-tool-search)によって前もって保持される定義についても発生します。105* **プリフィックスに読み込まれるツール**：それらへの変更はキャッシュを無効にします。これは[ツール検索が利用不可または無効](/docs/ja/mcp#configure-tool-search)な場合に発生します。Google Cloud の Agent Platform またはカスタム `ANTHROPIC_BASE_URL` ゲートウェイなど。また、[`alwaysLoad`](/docs/ja/mcp#exempt-a-server-from-deferral)とマークされたサーバーまたはツール、および[しきい値ベースの読み込み](/docs/ja/mcp#configure-tool-search)によって前もって保持される定義についても発生します。

106 106 

107ツールがプリフィックスに読み込まれる場合、無効化の最も一般的な原因は、セッション中にサーバーが接続または切断されることです。これはアクションなしで発生する可能性があります。stdio サーバーのプロセスが終了するか、HTTP セッションが期限切れになるか、サーバーが[一時的な障害後に自動的に再接続](/ja/mcp#automatic-reconnection)します。接続されたサーバーは、ツールリストを変更する[動的ツール更新](/ja/mcp#dynamic-tool-updates)をプッシュすることもできます。107ツールがプリフィックスに読み込まれる場合、無効化の最も一般的な原因は、セッション中にサーバーが接続または切断されることです。これはアクションなしで発生する可能性があります。stdio サーバーのプロセスが終了するか、HTTP セッションが期限切れになるか、サーバーが[一時的な障害後に自動的に再接続](/docs/ja/mcp#automatic-reconnection)します。接続されたサーバーは、ツールリストを変更する[動的ツール更新](/docs/ja/mcp#dynamic-tool-updates)をプッシュすることもできます。

108 108 

109MCP 設定を編集しても、それ自体ではキャッシュは変更されません。新しい設定は再起動後にのみ有効になります。これは、サーバーが接続または切断されるときです。109MCP 設定を編集しても、それ自体ではキャッシュは変更されません。新しい設定は再起動後にのみ有効になります。これは、サーバーが接続または切断されるときです。

110 110 

112 プラグインの有効化または無効化112 プラグインの有効化または無効化

113</h3>113</h3>

114 114 

115[プラグイン](/ja/plugins)は複数のコンポーネントタイプをバンドルし、変更のコストはプラグインが提供するコンポーネントによって異なります。Skills、commands、agents、hooks、LSP サーバー、monitors、themes は決してキャッシュを無効にしません。リクエストに追加するものはすべて既存の会話の後に追加されるため、次のリクエストは新しいコンテンツに対して支払いますが、それでもその前のすべてをキャッシュから読み取ります。115[プラグイン](/docs/ja/plugins)は複数のコンポーネントタイプをバンドルし、変更のコストはプラグインが提供するコンポーネントによって異なります。Skills、commands、agents、hooks、LSP サーバー、monitors、themes は決してキャッシュを無効にしません。リクエストに追加するものはすべて既存の会話の後に追加されるため、次のリクエストは新しいコンテンツに対して支払いますが、それでもその前のすべてをキャッシュから読み取ります。

116 116 

117例外は[MCP サーバー](/ja/plugins-reference#mcp-servers)を提供するプラグインです。1 つを有効化または無効化することは、[MCP サーバーの接続または切断](#connecting-or-disconnecting-an-mcp-server)と同じルールに従います。サーバーのツールが遅延されるとキャッシュが保持され、プリフィックスに読み込まれると次のリクエストは会話全体を再度読み取ります。117例外は[MCP サーバー](/docs/ja/plugins-reference#mcp-servers)を提供するプラグインです。1 つを有効化または無効化することは、[MCP サーバーの接続または切断](#connecting-or-disconnecting-an-mcp-server)と同じルールに従います。サーバーのツールが遅延されるとキャッシュが保持され、プリフィックスに読み込まれると次のリクエストは会話全体を再度読み取ります。

118 118 

119プラグインの変更は、[`/reload-plugins`](/ja/discover-plugins#apply-plugin-changes-without-restarting)を実行するか、新しいセッションを開始するときに適用されます。コスト（追加されたアナウンスメントまたは完全な再読み取り）は、`/plugin install`、`/plugin enable`、または `/plugin disable` を実行するときではなく、リロード後の最初のターンに表示されます。{/* min-version: 2.1.163 */}v2.1.163 以降、リロードが完全な再読み取りをトリガーする場合、`/reload-plugins` は警告を表示し、リロードを適用しません。`--force` を渡して、とにかく適用します。119プラグインの変更は、[`/reload-plugins`](/docs/ja/discover-plugins#apply-plugin-changes-without-restarting)を実行するか、新しいセッションを開始するときに適用されます。コスト（追加されたアナウンスメントまたは完全な再読み取り）は、`/plugin install`、`/plugin enable`、または `/plugin disable` を実行するときではなく、リロード後の最初のターンに表示されます。{/* min-version: 2.1.163 */}v2.1.163 以降、リロードが完全な再読み取りをトリガーする場合、`/reload-plugins` は警告を表示し、リロードを適用しません。`--force` を渡して、とにかく適用します。

120 120 

121セッションの前半で有効にしたプラグインを無効にすると、以前のリクエスト形状が復元されます。そのプリフィックスがまだ[キャッシュライフタイム](#cache-lifetime)内にある場合、次のリクエストは再構築するのではなく、古いキャッシュエントリを読み取ります。121セッションの前半で有効にしたプラグインを無効にすると、以前のリクエスト形状が復元されます。そのプリフィックスがまだ[キャッシュライフタイム](#cache-lifetime)内にある場合、次のリクエストは再構築するのではなく、古いキャッシュエントリを読み取ります。

122 122 

124 ツール全体の拒否124 ツール全体の拒否

125</h3>125</h3>

126 126 

127`Bash` や `WebFetch` のような裸のツール名を[拒否ルール](/ja/permissions#manage-permissions)として追加すると、そのツールは Claude のコンテキストから完全に削除されます。組み込みツール定義はシステムプロンプトレイヤーに読み込まれるため、これらのルールの 1 つを追加または削除するとセッション中にキャッシュが無効になります。変更は、`/permissions` を通じて追加するか、[設定ファイルを直接編集](/ja/settings#when-edits-take-effect)するかにかかわらず、次のターンで有効になります。127`Bash` や `WebFetch` のような裸のツール名を[拒否ルール](/docs/ja/permissions#manage-permissions)として追加すると、そのツールは Claude のコンテキストから完全に削除されます。組み込みツール定義はシステムプロンプトレイヤーに読み込まれるため、これらのルールの 1 つを追加または削除するとセッション中にキャッシュが無効になります。変更は、`/permissions` を通じて追加するか、[設定ファイルを直接編集](/docs/ja/settings#when-edits-take-effect)するかにかかわらず、次のターンで有効になります。

128 128 

129ツール名位置で一致する拒否ルールのみがこの効果を持ちます。裸のツール名、同等の `Bash(*)` 形式、または[ツール名グロブ](/ja/permissions#tool-name-wildcards)（`"*"` など）。`"mcp__*"` のような MCP ツールのみに一致するグロブは、それらのツールを同じ方法で削除しますが、一致したツールが[遅延](#connecting-or-disconnecting-an-mcp-server)されている場合、デフォルトではキャッシュはそのままです。遅延定義はキャッシュされたプリフィックスに含まれていなかったため。`Bash(rm *)` のようなスコープ付き拒否ルール、およびすべての許可ルールと質問ルールは、Claude が見るツールを変更しません。Claude Code は Claude が呼び出しを試みるときにそれらをチェックし、プリフィックスをそのままにします。129ツール名位置で一致する拒否ルールのみがこの効果を持ちます。裸のツール名、同等の `Bash(*)` 形式、または[ツール名グロブ](/docs/ja/permissions#tool-name-wildcards)（`"*"` など）。`"mcp__*"` のような MCP ツールのみに一致するグロブは、それらのツールを同じ方法で削除しますが、一致したツールが[遅延](#connecting-or-disconnecting-an-mcp-server)されている場合、デフォルトではキャッシュはそのままです。遅延定義はキャッシュされたプリフィックスに含まれていなかったため。`Bash(rm *)` のようなスコープ付き拒否ルール、およびすべての許可ルールと質問ルールは、Claude が見るツールを変更しません。Claude Code は Claude が呼び出しを試みるときにそれらをチェックし、プリフィックスをそのままにします。

130 130 

131<h3 id="compacting-the-conversation">131<h3 id="compacting-the-conversation">

132 会話のコンパクト化132 会話のコンパクト化

133</h3>133</h3>

134 134 

135[コンパクト化](/ja/context-window#what-survives-compaction)は、メッセージ履歴を要約に置き換えます。設計上、これは会話レイヤーを無効にします。次のリクエストには、古いものとプリフィックスを共有しない新しい、より短い履歴があるためです。Claude Code はシステムプロンプトレイヤーを再利用し、ディスクからプロジェクトコンテキストを再度読み込みます。これは、セッション開始以降 CLAUDE.md とメモリが変更されていない場合にのみキャッシュヒットします。135[コンパクト化](/docs/ja/context-window#what-survives-compaction)は、メッセージ履歴を要約に置き換えます。設計上、これは会話レイヤーを無効にします。次のリクエストには、古いものとプリフィックスを共有しない新しい、より短い履歴があるためです。Claude Code はシステムプロンプトレイヤーを再利用し、ディスクからプロジェクトコンテキストを再度読み込みます。これは、セッション開始以降 CLAUDE.md とメモリが変更されていない場合にのみキャッシュヒットします。

136 136 

137要約を生成するために、Claude Code は、会話と同じシステムプロンプト、ツール、履歴を持つ 1 回限りのリクエストを送信し、最終ユーザーメッセージとして要約命令を追加します。プリフィックスを共有するため、そのリクエストは既存のキャッシュを読み取り、完全な履歴を再処理しません。コンパクト化の時間のほとんどは、キャッシュミスではなく、要約の生成に費やされます。その後のターンは、はるかに短い要約に対してのみ会話キャッシュを再構築するため、コンパクト化後のターンは遅い部分ではありません。137要約を生成するために、Claude Code は、会話と同じシステムプロンプト、ツール、履歴を持つ 1 回限りのリクエストを送信し、最終ユーザーメッセージとして要約命令を追加します。プリフィックスを共有するため、そのリクエストは既存のキャッシュを読み取り、完全な履歴を再処理しません。コンパクト化の時間のほとんどは、キャッシュミスではなく、要約の生成に費やされます。その後のターンは、はるかに短い要約に対してのみ会話キャッシュを再構築するため、コンパクト化後のターンは遅い部分ではありません。

138 138 

144 Claude Code のアップグレード144 Claude Code のアップグレード

145</h3>145</h3>

146 146 

147新しい Claude Code バージョンは通常、システムプロンプトまたはツール定義を更新するため、アップグレード後の最初のリクエストはキャッシュを最初から再構築します。[自動更新](/ja/setup#auto-updates)は新しいバージョンをバックグラウンドでダウンロードしますが、次の起動時に適用され、セッション中には適用されません。そのため、セッション中のサプライズではなく、再起動後のキャッシュなしの最初のターンとして表示されます。`DISABLE_AUTOUPDATER=1` を設定して、アップグレードが適用されるタイミングを制御します。147新しい Claude Code バージョンは通常、システムプロンプトまたはツール定義を更新するため、アップグレード後の最初のリクエストはキャッシュを最初から再構築します。[自動更新](/docs/ja/setup#auto-updates)は新しいバージョンをバックグラウンドでダウンロードしますが、次の起動時に適用され、セッション中には適用されません。そのため、セッション中のサプライズではなく、再起動後のキャッシュなしの最初のターンとして表示されます。`DISABLE_AUTOUPDATER=1` を設定して、アップグレードが適用されるタイミングを制御します。

148 148 

149<Note>149<Note>

150 アップグレード後に[セッションを再開](/ja/sessions#resume-a-session)すると、履歴が異なるシステムプロンプトの後ろに配置されるため、キャッシュヒットなしで会話履歴全体が再処理されます。コストは再開された会話の長さに応じてスケーリングされるため、長いセッションに戻る最初のターンは、送信する最も高価なリクエストになる可能性があります。150 アップグレード後に[セッションを再開](/docs/ja/sessions#resume-a-session)すると、履歴が異なるシステムプロンプトの後ろに配置されるため、キャッシュヒットなしで会話履歴全体が再処理されます。コストは再開された会話の長さに応じてスケーリングされるため、長いセッションに戻る最初のターンは、送信する最も高価なリクエストになる可能性があります。

151</Note>151</Note>

152 152 

153<h2 id="actions-that-keep-the-cache">153<h2 id="actions-that-keep-the-cache">

177 177 

178プロジェクトルートとユーザーレベルの CLAUDE.md ファイルはセッション開始時に 1 回読み取られ、メモリに保持されます。セッション中に編集してもキャッシュは無効になりませんが、編集も適用されません。Claude はセッション開始時に読み込まれたバージョンで作業を続けます。新しいコンテンツは次の `/clear`、`/compact`、または再起動時に読み込まれます。178プロジェクトルートとユーザーレベルの CLAUDE.md ファイルはセッション開始時に 1 回読み取られ、メモリに保持されます。セッション中に編集してもキャッシュは無効になりませんが、編集も適用されません。Claude はセッション開始時に読み込まれたバージョンで作業を続けます。新しいコンテンツは次の `/clear`、`/compact`、または再起動時に読み込まれます。

179 179 

180[サブディレクトリ内のネストされた CLAUDE.md ファイル](/ja/memory)と[`paths:` frontmatter を持つルール](/ja/memory#path-specific-rules)は、Claude が最初に一致するファイルを読むときに後で読み込まれます。読み込まれる前に編集すると、有効になります。読み込まれた後、コンテンツは会話履歴の一部であるため、セッション中の編集は遡及的に変更されません。180[サブディレクトリ内のネストされた CLAUDE.md ファイル](/docs/ja/memory)と[`paths:` frontmatter を持つルール](/docs/ja/memory#path-specific-rules)は、Claude が最初に一致するファイルを読むときに後で読み込まれます。読み込まれる前に編集すると、有効になります。読み込まれた後、コンテンツは会話履歴の一部であるため、セッション中の編集は遡及的に変更されません。

181 181 

182<h3 id="changing-output-style">182<h3 id="changing-output-style">

183 出力スタイルの変更183 出力スタイルの変更

184</h3>184</h3>

185 185 

186[出力スタイル](/ja/output-styles)はシステムプロンプトの一部であり、Claude Code はセッション開始時に 1 回読み取ります。`/config` または `outputStyle` 設定を使用してセッション中に変更してもキャッシュは無効になりませんが、変更も適用されません。Claude はセッション開始時に読み込まれたスタイルを使用し続けます。新しいスタイルは次の `/clear` または再起動時に読み込まれます。186[出力スタイル](/docs/ja/output-styles)はシステムプロンプトの一部であり、Claude Code はセッション開始時に 1 回読み取ります。`/config` または `outputStyle` 設定を使用してセッション中に変更してもキャッシュは無効になりませんが、変更も適用されません。Claude はセッション開始時に読み込まれたスタイルを使用し続けます。新しいスタイルは次の `/clear` または再起動時に読み込まれます。

187 187 

188<h3 id="changing-permission-mode">188<h3 id="changing-permission-mode">

189 権限モードの変更189 権限モードの変更

190</h3>190</h3>

191 191 

192[権限モード](/ja/permission-modes)間の切り替え（デフォルトから編集受け入れへなど）は、システムプロンプトまたはツール定義を変更しないため、モード変更はキャッシュセーフです。例外は、[`opusplan`](/ja/model-config#opusplan-model-setting) モデル設定を使用した Plan mode です。これは、Plan mode に入るか出るときにモデルを Opus と Sonnet の間で切り替えます。これにより、モード切り替えは[モデル切り替え](#switching-models)になります。192[権限モード](/docs/ja/permission-modes)間の切り替え（デフォルトから編集受け入れへなど）は、システムプロンプトまたはツール定義を変更しないため、モード変更はキャッシュセーフです。例外は、[`opusplan`](/docs/ja/model-config#opusplan-model-setting) モデル設定を使用した Plan mode です。これは、Plan mode に入るか出るときにモデルを Opus と Sonnet の間で切り替えます。これにより、モード切り替えは[モデル切り替え](#switching-models)になります。

193 193 

194<h3 id="invoking-skills-and-commands">194<h3 id="invoking-skills-and-commands">

195 スキルとコマンドの呼び出し195 スキルとコマンドの呼び出し

196</h3>196</h3>

197 197 

198[スキル](/ja/skills)と[コマンド](/ja/commands)は、呼び出しポイントでユーザーメッセージとして命令を注入します。会話内の以前のものは何も変わりません。198[スキル](/docs/ja/skills)と[コマンド](/docs/ja/commands)は、呼び出しポイントでユーザーメッセージとして命令を注入します。会話内の以前のものは何も変わりません。

199 199 

200<h3 id="running-/recap">200<h3 id="running-/recap">

201 `/recap` の実行201 `/recap` の実行

202</h3>202</h3>

203 203 

204[`/recap`](/ja/interactive-mode#session-recap)は、ターミナルに表示するための要約を生成します。`/compact` とは異なり、メッセージ履歴を置き換えるのではなく、コマンド出力として要約を追加するため、キャッシュされたプリフィックスはそのままです。204[`/recap`](/docs/ja/interactive-mode#session-recap)は、ターミナルに表示するための要約を生成します。`/compact` とは異なり、メッセージ履歴を置き換えるのではなく、コマンド出力として要約を追加するため、キャッシュされたプリフィックスはそのままです。

205 205 

206<h3 id="rewinding-the-conversation">206<h3 id="rewinding-the-conversation">

207 会話の巻き戻し207 会話の巻き戻し

208</h3>208</h3>

209 209 

210[`/rewind`](/ja/checkpointing)は、会話を以前のターンに切り詰めます。残りの履歴は、その時点でキャッシュが構築されたのと同じコンテンツであり、システムプロンプトとプロジェクトコンテキストレイヤーは変更されないため、次のリクエストは以前のキャッシュエントリにヒットします。それ以降のすべてのターンはそのプリフィックスを通じて読み取られており、元のターンが TTL より長い前であっても、エントリを温かく保ちました。210[`/rewind`](/docs/ja/checkpointing)は、会話を以前のターンに切り詰めます。残りの履歴は、その時点でキャッシュが構築されたのと同じコンテンツであり、システムプロンプトとプロジェクトコンテキストレイヤーは変更されないため、次のリクエストは以前のキャッシュエントリにヒットします。それ以降のすべてのターンはそのプリフィックスを通じて読み取られており、元のターンが TTL より長い前であっても、エントリを温かく保ちました。

211 211 

212会話と一緒にファイルチェックポイントを復元しても、キャッシュに対する個別の効果はありません。ファイルコンテンツがコンテキストに入るのは Claude が読むときだけであり、[リポジトリ内のファイルの編集](#editing-files-in-your-repository)と同じです。212会話と一緒にファイルチェックポイントを復元しても、キャッシュに対する個別の効果はありません。ファイルコンテンツがコンテキストに入るのは Claude が読むときだけであり、[リポジトリ内のファイルの編集](#editing-files-in-your-repository)と同じです。

213 213 

239 TTL をオーバーライドする239 TTL をオーバーライドする

240</h3>240</h3>

241 241 

242`FORCE_PROMPT_CACHING_5M=1` を設定して、認証に関わらず 5 分の TTL を強制します。これは、キャッシング動作をデバッグする場合、2 つの TTL を比較する場合、または[管理設定](/ja/settings#settings-files)で設定された `ENABLE_PROMPT_CACHING_1H` をオーバーライドする場合に便利です。242`FORCE_PROMPT_CACHING_5M=1` を設定して、認証に関わらず 5 分の TTL を強制します。これは、キャッシング動作をデバッグする場合、2 つの TTL を比較する場合、または[管理設定](/docs/ja/settings#settings-files)で設定された `ENABLE_PROMPT_CACHING_1H` をオーバーライドする場合に便利です。

243 243 

244<h2 id="cache-scope">244<h2 id="cache-scope">

245 キャッシュスコープ245 キャッシュスコープ

249 249 

250同じディレクトリで並行して実行するセッションは、一致するプリフィックスを構築し、互いのキャッシュを読み取ります。順序付きセッションは、起動時の git ステータススナップショットが一致する場合にのみプリフィックスを共有します。システムプロンプトはブランチと最近のコミットもキャプチャするためです。250同じディレクトリで並行して実行するセッションは、一致するプリフィックスを構築し、互いのキャッシュを読み取ります。順序付きセッションは、起動時の git ステータススナップショットが一致する場合にのみプリフィックスを共有します。システムプロンプトはブランチと最近のコミットもキャプチャするためです。

251 251 

252基礎となる API キャッシュはより広いです。キャッシュは組織間で分離され、一部のプロバイダーでは、[組織内のワークスペース間](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching#cache-storage-and-sharing)で分離されます。これらの境界内で、同じモデルとプリフィックスを持つ 2 つのリクエストは同じキャッシュを読み取ります。自動化されたプロセスのフリートを実行する Agent SDK 呼び出し元については、[ユーザーとマシン間でプロンプトキャッシングを改善](/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)を参照して、システムプロンプトのマシンごとのセクションを抑制し、マシン間でキャッシュを共有します。252基礎となる API キャッシュはより広いです。キャッシュは組織間で分離され、一部のプロバイダーでは、[組織内のワークスペース間](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching#cache-storage-and-sharing)で分離されます。これらの境界内で、同じモデルとプリフィックスを持つ 2 つのリクエストは同じキャッシュを読み取ります。自動化されたプロセスのフリートを実行する Agent SDK 呼び出し元については、[ユーザーとマシン間でプロンプトキャッシングを改善](/docs/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)を参照して、システムプロンプトのマシンごとのセクションを抑制し、マシン間でキャッシュを共有します。

253 253 

254<h2 id="check-cache-performance">254<h2 id="check-cache-performance">

255 キャッシュパフォーマンスを確認する255 キャッシュパフォーマンスを確認する

256</h2>256</h2>

257 257 

258キャッシュパフォーマンスは、API がすべての応答で報告する 2 つのトークン数として表示されます。最も直接的な方法は、`current_usage` オブジェクトを読み取る[statusline スクリプト](/ja/statusline)を監視することです。258キャッシュパフォーマンスは、API がすべての応答で報告する 2 つのトークン数として表示されます。最も直接的な方法は、`current_usage` オブジェクトを読み取る[statusline スクリプト](/docs/ja/statusline)を監視することです。

259 259 

260| フィールド | 意味 |260| フィールド | 意味 |

261| ----------------------------- | -------------------------------------------- |261| ----------------------------- | -------------------------------------------- |

264 264 

265読み取りから作成への比率が高いほど、キャッシングが機能しています。作成がターンごとに高いままの場合、プリフィックスで何かが変更されています。[キャッシュを無効にするアクション](#actions-that-invalidate-the-cache)セクションは、通常の原因をリストします。265読み取りから作成への比率が高いほど、キャッシングが機能しています。作成がターンごとに高いままの場合、プリフィックスで何かが変更されています。[キャッシュを無効にするアクション](#actions-that-invalidate-the-cache)セクションは、通常の原因をリストします。

266 266 

267組織全体の可視性については、OpenTelemetry エクスポーターはユーザーとセッションごとにキャッシュ読み取りと作成トークンを報告します。メトリックとイベント属性リファレンスについては、[使用状況の監視](/ja/monitoring-usage)を参照してください。267組織全体の可視性については、OpenTelemetry エクスポーターはユーザーとセッションごとにキャッシュ読み取りと作成トークンを報告します。メトリックとイベント属性リファレンスについては、[使用状況の監視](/docs/ja/monitoring-usage)を参照してください。

268 268 

269<h2 id="subagents-and-the-cache">269<h2 id="subagents-and-the-cache">

270 サブエージェントとキャッシュ270 サブエージェントとキャッシュ

271</h2>271</h2>

272 272 

273[サブエージェント](/ja/sub-agents)は、親とは別に、独自のシステムプロンプトとツールセットを持つ独自の会話を開始します。独自のキャッシュを構築し、最初の呼び出しでキャッシュヒットなしで開始し、独自のターン全体で温まります。サブエージェントは、サブスクリプション上でも 5 分の TTL を使用します。自動 1 時間の TTL はメイン会話に適用されるためです。273[サブエージェント](/docs/ja/sub-agents)は、親とは別に、独自のシステムプロンプトとツールセットを持つ独自の会話を開始します。独自のキャッシュを構築し、最初の呼び出しでキャッシュヒットなしで開始し、独自のターン全体で温まります。サブエージェントは、サブスクリプション上でも 5 分の TTL を使用します。自動 1 時間の TTL はメイン会話に適用されるためです。

274 274 

275親のキャッシュは影響を受けません。親の側から、サブエージェントの呼び出しと結果は会話に追加され、親のプリフィックスはそのままです。275親のキャッシュは影響を受けません。親の側から、サブエージェントの呼び出しと結果は会話に追加され、親のプリフィックスはそのままです。

276 276 

277一方、[フォーク](/ja/sub-agents#fork-the-current-conversation)は、親のシステムプロンプト、ツール、会話履歴を正確に継承するため、最初のリクエストは親のキャッシュを読み取ります。[会話のコンパクト化](#compacting-the-conversation)で説明されているコンパクト化要約呼び出しは、同じプリフィックス共有アプローチを使用します。277一方、[フォーク](/docs/ja/sub-agents#fork-the-current-conversation)は、親のシステムプロンプト、ツール、会話履歴を正確に継承するため、最初のリクエストは親のキャッシュを読み取ります。[会話のコンパクト化](#compacting-the-conversation)で説明されているコンパクト化要約呼び出しは、同じプリフィックス共有アプローチを使用します。

278 278 

279<h2 id="disable-prompt-caching">279<h2 id="disable-prompt-caching">

280 プロンプトキャッシングを無効にする280 プロンプトキャッシングを無効にする

290| `DISABLE_PROMPT_CACHING_OPUS` | Opus のみに対して無効にする |290| `DISABLE_PROMPT_CACHING_OPUS` | Opus のみに対して無効にする |

291| `DISABLE_PROMPT_CACHING_FABLE` | Fable のみに対して無効にする |291| `DISABLE_PROMPT_CACHING_FABLE` | Fable のみに対して無効にする |

292 292 

293組織全体でキャッシングポリシーを設定するには、これらのいずれかまたは [TTL 変数](#cache-lifetime)を [管理設定](/ja/settings#settings-files)の `env` ブロックに入れます。通常の使用では、キャッシングを有効のままにしてください。293組織全体でキャッシングポリシーを設定するには、これらのいずれかまたは [TTL 変数](#cache-lifetime)を [管理設定](/docs/ja/settings#settings-files)の `env` ブロックに入れます。通常の使用では、キャッシングを有効のままにしてください。

294 294 

295<h2 id="related-resources">295<h2 id="related-resources">

296 関連リソース296 関連リソース

297</h2>297</h2>

298 298 

299* [Claude Code の構築から学んだ教訓: プロンプトキャッシングがすべて](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): Plan mode、遅延ツール読み込み、コンパクト化の設計根拠299* [Claude Code の構築から学んだ教訓: プロンプトキャッシングがすべて](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): Plan mode、遅延ツール読み込み、コンパクト化の設計根拠

300* [コンテキストウィンドウを探索](/ja/context-window): コンテキストに読み込まれるもの、いつ読み込まれるか300* [コンテキストウィンドウを探索](/docs/ja/context-window): コンテキストに読み込まれるもの、いつ読み込まれるか

301* [トークン使用量を削減](/ja/costs#reduce-token-usage): コンテキストサイズを管理するためのキャッシング以外の戦略301* [トークン使用量を削減](/docs/ja/costs#reduce-token-usage): コンテキストサイズを管理するためのキャッシング以外の戦略

302* [コストを追跡および削減](/ja/agent-sdk/cost-tracking): Agent SDK 呼び出し元のキャッシュトークン追跡と TTL 設定302* [コストを追跡および削減](/docs/ja/agent-sdk/cost-tracking): Agent SDK 呼び出し元のキャッシュトークン追跡と TTL 設定

303* [プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching): 基礎となる API メカニズム、ブレークポイント、価格設定303* [プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching): 基礎となる API メカニズム、ブレークポイント、価格設定