Claude Code ガイド

Appearance

プロンプトキャッシュ無効化の修正（ツール定義変更時） ​

原文（日本語に翻訳） ​

ツールの説明や入力スキーマが変更された場合にプロンプトキャッシュが正しく無効化されていなかった問題を修正しました。以前はツール名が変更された場合のみ無効化されていました。

原文（英語） ​

Fixed prompt cache not correctly invalidating when tool descriptions or input schemas changed, only when tool names changed

概要 ​

Claudeのプロンプトキャッシング機能において、ツールの名前は変更されていないが、説明文（description）や入力スキーマ（input schema）が変更された場合、キャッシュが無効化されず古い定義が使われ続けていた問題が修正されました。これにより、ツール定義の変更が確実に反映されるようになりました。

基本的な使い方 ​

ツール定義の更新が正しく反映される ​

bash
# MCP ツールの定義を更新
# ~/.claude/mcp/servers/my-tools/tools.json

# バージョン1: 元の定義
{
  "name": "search_code",
  "description": "Search for code patterns",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pattern": {"type": "string"}
    }
  }
}

# バージョン2: 説明とスキーマを改善（名前は同じ）
{
  "name": "search_code",  // 名前は変更なし
  "description": "Search for code patterns with regex support and file filtering",  // 説明を改善
  "inputSchema": {
    "type": "object",
    "properties": {
      "pattern": {"type": "string"},
      "filePattern": {"type": "string"},  // 新しいパラメータ
      "regex": {"type": "boolean"}  // 新しいパラメータ
    }
  }
}

# 以前: キャッシュが残り、古い定義が使われる
# 現在: キャッシュが無効化され、新しい定義が使われる

実践例 ​

MCPサーバーツールの機能拡張 ​

既存ツールに新しいパラメータを追加：

bash
# MCPサーバー設定
~/.claude/settings.json

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

# ツール定義を更新（サーバー側）
# query_database ツールに timeout パラメータを追加

# Claude Codeセッション
claude

> "データベースから最新の100件を取得して"

# 以前の問題:
# - 古いキャッシュが使われ、timeout パラメータが認識されない
# - Claudeは timeout を指定できない

# 修正後:
# - 新しいツール定義が読み込まれる
# - Claudeは timeout パラメータを利用可能

カスタムツールの改善とデプロイ ​

開発中のツールを段階的に改善：

javascript
// v1: 基本的な実装
{
  name: "format_code",
  description: "Format code",
  inputSchema: {
    properties: {
      code: { type: "string" }
    }
  }
}

// v2: オプションを追加
{
  name: "format_code",  // 同じ名前
  description: "Format code with configurable style options",  // 改善
  inputSchema: {
    properties: {
      code: { type: "string" },
      style: { enum: ["prettier", "eslint", "custom"] },  // 新規
      indent: { type: "number" }  // 新規
    }
  }
}
bash
# Claude Codeで使用
claude

> "このJavaScriptコードをフォーマットして、インデント4スペースで"

# v2.1.30以前: Claudeはindentパラメータを認識しない
# v2.1.30以降: 新しいスキーマが使われ、正しく動作

プロンプトキャッシングの階層構造 ​

キャッシュの無効化が正しく伝播：

キャッシング階層:
1. Tools（ツール定義）
2. System（システムプロンプト）
3. Messages（会話履歴）

ツール定義の変更 → Tools レベルが無効化
                 → System、Messages も無効化
bash
# ツール定義を更新
# → ツールキャッシュが無効化
# → システムプロンプトキャッシュも無効化
# → すべてのキャッシュが再生成

# 修正前: ツール名が変わらない限りキャッシュが残る
# 修正後: 説明やスキーマの変更でもキャッシュが無効化

デバッグとトラブルシューティング ​

ツール定義の変更が反映されない場合の診断：

bash
# 以前の回避策（不要になった）
# キャッシュを手動でクリア
rm -rf ~/.claude/cache/*

# 現在は不要
# ツール定義を変更すると自動的にキャッシュが無効化される

注意点 ​

  • プロンプトキャッシングとは: Anthropic の機能で、System プロンプト、ツール定義、会話履歴の一部をキャッシュし、APIコストと遅延を削減します。

  • キャッシュの有効期間: キャッシュは5分間有効です。その後は自動的に期限切れとなり、再生成されます。

  • 変更の検出: 以下の変更でキャッシュが無効化されます：

    • ツール名の変更（以前から対応）
    • ツール説明の変更（新規）
    • 入力スキーマの変更（新規）
    • ツールの追加・削除

  • 開発中のツール: ツール定義を頻繁に変更する開発中は、キャッシュヒット率が低下します。これは正常な動作です。

  • プロダクション環境: ツール定義が安定している本番環境では、高いキャッシュヒット率が得られます。

  • コストへの影響: キャッシュの無効化により、一時的にAPIコストが上がる可能性がありますが、正確なツール動作を保証します。

  • 確認方法: ツール定義の変更が反映されているか確認するには：

    bash
    claude

> "利用可能なツールを説明して"
# 新しい説明とパラメータが表示されることを確認

関連情報 ​