Loading...
    • 開発者ガイド
    • API リファレンス
    • MCP
    • リソース
    • リリースノート
    Search...
    ⌘K
    はじめに
    Claude の紹介クイックスタート
    モデルと料金
    モデル概要モデルの選び方Claude 4.6 の新機能移行ガイドモデルの廃止料金
    Claude で構築する
    機能概要Messages API の使用停止理由の処理プロンプトのベストプラクティス
    コンテキスト管理
    コンテキストウィンドウコンパクションコンテキスト編集
    機能
    プロンプトキャッシング拡張思考適応型思考エフォートメッセージのストリーミングバッチ処理引用多言語サポートトークンカウントエンベディングビジョンPDF サポートFiles API検索結果構造化出力
    ツール
    概要ツール使用の実装方法きめ細かいツールストリーミングBash ツールコード実行ツールプログラムによるツール呼び出しコンピュータ使用ツールテキストエディタツールWeb フェッチツールWeb 検索ツールメモリツールツール検索ツール
    Agent Skills
    概要クイックスタートベストプラクティスエンタープライズ向け SkillsAPI での Skills の使用
    Agent SDK
    概要クイックスタートTypeScript SDKTypeScript V2(プレビュー)Python SDK移行ガイド
    ストリーミング入力リアルタイムでレスポンスをストリーミング停止理由の処理権限の処理ユーザー承認と入力フックによる実行制御セッション管理ファイルチェックポイントSDK での構造化出力Agent SDK のホスティングAI エージェントの安全なデプロイシステムプロンプトの変更SDK での MCPカスタムツールSDK でのサブエージェントSDK でのスラッシュコマンドSDK での Agent Skillsコストと使用量の追跡Todo リストSDK でのプラグイン
    API での MCP
    MCP コネクタリモート MCP サーバー
    サードパーティプラットフォームの Claude
    Amazon BedrockMicrosoft FoundryVertex AI
    プロンプトエンジニアリング
    概要プロンプトジェネレータープロンプトテンプレートの使用プロンプト改善ツール明確かつ直接的に例を使う(マルチショットプロンプティング)Claude に考えさせる(CoT)XML タグを使うClaude に役割を与える(システムプロンプト)複雑なプロンプトを連鎖させる長文コンテキストのヒント拡張思考のヒント
    テストと評価
    成功基準の定義テストケースの開発評価ツールの使用レイテンシの削減
    ガードレールの強化
    ハルシネーションの削減出力の一貫性を高めるジェイルブレイクの軽減ストリーミング拒否プロンプト漏洩の防止Claude をキャラクターに保つ
    管理とモニタリング
    Admin API 概要データレジデンシーワークスペースUsage and Cost APIClaude Code Analytics APIゼロデータリテンション
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    ガイド

    チェックポイントによるファイル変更の巻き戻し

    エージェントセッション中のファイル変更を追跡し、任意の以前の状態にファイルを復元する

    Was this page helpful?

    • ユーザーメッセージにUUIDがない
    • 「No file checkpoint found for message」エラー
    • 「ProcessTransport is not ready for writing」エラー

    ファイルチェックポイントは、エージェントセッション中にWrite、Edit、NotebookEditツールを通じて行われたファイル変更を追跡し、任意の以前の状態にファイルを巻き戻すことができます。試してみたいですか?インタラクティブな例にジャンプしてください。

    チェックポイントを使用すると、以下のことができます:

    • 不要な変更を元に戻す - ファイルを既知の正常な状態に復元する
    • 代替案を探索する - チェックポイントに復元して別のアプローチを試す
    • エラーから回復する - エージェントが誤った変更を行った場合

    Write、Edit、NotebookEditツールを通じて行われた変更のみが追跡されます。Bashコマンド(echo > file.txtやsed -iなど)を通じて行われた変更は、チェックポイントシステムによってキャプチャされません。

    チェックポイントの仕組み

    ファイルチェックポイントを有効にすると、SDKはWrite、Edit、またはNotebookEditツールを通じてファイルを変更する前にバックアップを作成します。レスポンスストリーム内のユーザーメッセージには、復元ポイントとして使用できるチェックポイントUUIDが含まれます。

    チェックポイントは、エージェントがファイルを変更するために使用する以下の組み込みツールで動作します:

    ツール説明
    Write新しいファイルを作成するか、既存のファイルを新しい内容で上書きする
    Edit既存のファイルの特定の部分に対して的を絞った編集を行う
    NotebookEditJupyterノートブック(.ipynbファイル)のセルを変更する

    ファイルの巻き戻しは、ディスク上のファイルを以前の状態に復元します。会話自体は巻き戻しません。rewindFiles()(TypeScript)またはrewind_files()(Python)を呼び出した後も、会話履歴とコンテキストはそのまま残ります。

    チェックポイントシステムは以下を追跡します:

    • セッション中に作成されたファイル
    • セッション中に変更されたファイル
    • 変更されたファイルの元の内容

    チェックポイントに巻き戻すと、作成されたファイルは削除され、変更されたファイルはその時点の内容に復元されます。

    チェックポイントの実装

    ファイルチェックポイントを使用するには、オプションで有効にし、レスポンスストリームからチェックポイントUUIDをキャプチャし、復元が必要な場合にrewindFiles()(TypeScript)またはrewind_files()(Python)を呼び出します。

    以下の例は完全なフローを示しています:チェックポイントを有効にし、レスポンスストリームからチェックポイントUUIDとセッションIDをキャプチャし、後でセッションを再開してファイルを巻き戻します。各ステップの詳細は以下で説明します。

    一般的なパターン

    これらのパターンは、ユースケースに応じてチェックポイントUUIDをキャプチャして使用するさまざまな方法を示しています。

    リスクのある操作前のチェックポイント

    このパターンは、各エージェントターンの前に更新しながら、最新のチェックポイントUUIDのみを保持します。処理中に問題が発生した場合、最後の安全な状態にすぐに巻き戻してループから抜け出すことができます。

    複数の復元ポイント

    Claudeが複数のターンにわたって変更を行う場合、最初まで戻るのではなく、特定のポイントに巻き戻したい場合があります。例えば、Claudeがターン1でファイルをリファクタリングし、ターン2でテストを追加した場合、リファクタリングは保持しつつテストだけを元に戻したい場合があります。

    このパターンは、すべてのチェックポイントUUIDをメタデータとともに配列に保存します。セッション完了後、任意の以前のチェックポイントに巻き戻すことができます:

    試してみる

    この完全な例では、小さなユーティリティファイルを作成し、エージェントにドキュメントコメントを追加させ、変更を表示してから、巻き戻すかどうかを尋ねます。

    始める前に、Claude Agent SDKがインストールされていることを確認してください。

    制限事項

    ファイルチェックポイントには以下の制限事項があります:

    制限事項説明
    Write/Edit/NotebookEditツールのみBashコマンドを通じて行われた変更は追跡されない
    同一セッションチェックポイントはそれを作成したセッションに紐づく
    ファイル内容のみディレクトリの作成、移動、削除は巻き戻しで元に戻されない
    ローカルファイルリモートまたはネットワークファイルは追跡されない

    トラブルシューティング

    チェックポイントオプションが認識されない

    enableFileCheckpointingまたはrewindFiles()が利用できない場合、古いSDKバージョンを使用している可能性があります。

    解決策:最新のSDKバージョンに更新してください:

    • Python: pip install --upgrade claude-agent-sdk
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk@latest

    ユーザーメッセージにUUIDがない

    message.uuidがundefinedまたは欠落している場合、チェックポイントUUIDを受信していません。

    原因:replay-user-messagesオプションが設定されていません。

    解決策:オプションにextra_args={"replay-user-messages": None}(Python)またはextraArgs: { 'replay-user-messages': null }(TypeScript)を追加してください。

    「No file checkpoint found for message」エラー

    このエラーは、指定されたユーザーメッセージUUIDのチェックポイントデータが存在しない場合に発生します。

    一般的な原因:

    • CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING環境変数が設定されていない
    • 再開して巻き戻しを試みる前にセッションが適切に完了していない

    解決策:環境変数が設定されていることを確認し(環境変数を設定するを参照)、例に示されているパターンを使用してください:最初のユーザーメッセージUUIDをキャプチャし、セッションを完全に完了してから、空のプロンプトで再開し、rewindFiles()を一度呼び出します。

    「ProcessTransport is not ready for writing」エラー

    このエラーは、レスポンスの反復処理が完了した後にrewindFiles()またはrewind_files()を呼び出した場合に発生します。ループが完了するとCLIプロセスへの接続が閉じられます。

    解決策:空のプロンプトでセッションを再開し、新しいクエリで巻き戻しを呼び出します:

    # 空のプロンプトでセッションを再開し、巻き戻す
    async with ClaudeSDKClient(ClaudeAgentOptions(
        enable_file_checkpointing=True,
        resume=session_id
    )) as client:
        await client.query("")
        async for message in client.receive_response():
            await client.rewind_files(checkpoint_id)
            break

    次のステップ

    • セッション:セッションの再開方法を学びます。これはストリーム完了後の巻き戻しに必要です。セッションID、会話の再開、セッションのフォークについて説明しています。
    • 権限:Claudeが使用できるツールとファイル変更の承認方法を設定します。編集がいつ行われるかをより細かく制御したい場合に便利です。
    • TypeScript SDKリファレンス:query()のすべてのオプションとrewindFiles()メソッドを含む完全なAPIリファレンスです。
    • Python SDKリファレンス:ClaudeAgentOptionsのすべてのオプションとrewind_files()メソッドを含む完全なAPIリファレンスです。
    import asyncio
    import os
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
    
    async def main():
        # ステップ1: チェックポイントを有効にする
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",  # プロンプトなしでファイル編集を自動承認
            extra_args={"replay-user-messages": None},  # レスポンスストリームでチェックポイントUUIDを受信するために必要
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        checkpoint_id = None
        session_id = None
    
        # クエリを実行し、チェックポイントUUIDとセッションIDをキャプチャ
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            # ステップ2: 最初のユーザーメッセージからチェックポイントUUIDをキャプチャ
            async for message in client.receive_response():
                if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                    checkpoint_id = message.uuid
                if isinstance(message, ResultMessage) and not session_id:
                    session_id = message.session_id
    
        # ステップ3: 後で、空のプロンプトでセッションを再開して巻き戻す
        if checkpoint_id and session_id:
            async with ClaudeSDKClient(ClaudeAgentOptions(
                enable_file_checkpointing=True,
                resume=session_id
            )) as client:
                await client.query("")  # 接続を開くための空のプロンプト
                async for message in client.receive_response():
                    await client.rewind_files(checkpoint_id)
                    break
            print(f"Rewound to checkpoint: {checkpoint_id}")
    
    asyncio.run(main())
    1. 1

      環境変数を設定する

      ファイルチェックポイントにはCLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING環境変数が必要です。スクリプトを実行する前にコマンドラインで設定するか、SDKオプションで直接設定できます。

      オプション1: コマンドラインで設定

      Python
      export CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=1

      オプション2: SDKオプションで設定

      SDKを設定する際にenvオプションを通じて環境変数を渡します:

      import os
      
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
      )
    2. 2

      チェックポイントを有効にする

      チェックポイントを有効にし、チェックポイントUUIDを受信するようにSDKオプションを設定します:

      オプションPythonTypeScript説明
      チェックポイントを有効にするenable_file_checkpointing=TrueenableFileCheckpointing: true巻き戻し用にファイル変更を追跡する
      チェックポイントUUIDを受信するextra_args={"replay-user-messages": None}extraArgs: { 'replay-user-messages': null }ストリームでユーザーメッセージUUIDを取得するために必要
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          permission_mode="acceptEdits",
          extra_args={"replay-user-messages": None}
      )
      
      async with ClaudeSDKClient(options) as client:
          await client.query("Refactor the authentication module")
    3. 3

      チェックポイントUUIDとセッションIDをキャプチャする

      replay-user-messagesオプションが設定されている場合(上記参照)、レスポンスストリーム内の各ユーザーメッセージにはチェックポイントとして機能するUUIDがあります。

      ほとんどのユースケースでは、最初のユーザーメッセージUUID(message.uuid)をキャプチャします。これに巻き戻すと、すべてのファイルが元の状態に復元されます。複数のチェックポイントを保存して中間状態に巻き戻すには、複数の復元ポイントを参照してください。

      セッションID(message.session_id)のキャプチャはオプションです。ストリームが完了した後に巻き戻したい場合にのみ必要です。メッセージを処理中にすぐにrewindFiles()を呼び出す場合(リスクのある操作前のチェックポイントの例のように)、セッションIDのキャプチャはスキップできます。

      checkpoint_id = None
      session_id = None
      
      async for message in client.receive_response():
          # 各ユーザーメッセージでチェックポイントを更新(最新を保持)
          if isinstance(message, UserMessage) and message.uuid:
              checkpoint_id = message.uuid
          # 結果メッセージからセッションIDをキャプチャ
          if isinstance(message, ResultMessage):
              session_id = message.session_id
    4. 4

      ファイルを巻き戻す

      ストリーム完了後に巻き戻すには、空のプロンプトでセッションを再開し、チェックポイントUUIDを指定してrewind_files()(Python)またはrewindFiles()(TypeScript)を呼び出します。ストリーム中に巻き戻すこともできます。そのパターンについてはリスクのある操作前のチェックポイントを参照してください。

      async with ClaudeSDKClient(ClaudeAgentOptions(
          enable_file_checkpointing=True,
          resume=session_id
      )) as client:
          await client.query("")  # 接続を開くための空のプロンプト
          async for message in client.receive_response():
              await client.rewind_files(checkpoint_id)
              break

      セッションIDとチェックポイントIDをキャプチャしている場合、CLIからも巻き戻すことができます:

      claude --resume <session-id> --rewind-files <checkpoint-uuid>
    import asyncio
    import os
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage
    
    async def main():
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",
            extra_args={"replay-user-messages": None},
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        safe_checkpoint = None
    
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            async for message in client.receive_response():
                # 各エージェントターンの開始前にチェックポイントを更新
                # 前のチェックポイントを上書きする。最新のみを保持
                if isinstance(message, UserMessage) and message.uuid:
                    safe_checkpoint = message.uuid
    
                # 独自のロジックに基づいて巻き戻すタイミングを決定
                # 例:エラー検出、バリデーション失敗、またはユーザー入力
                if your_revert_condition and safe_checkpoint:
                    await client.rewind_files(safe_checkpoint)
                    # 巻き戻し後にループを終了、ファイルは復元済み
                    break
    
    asyncio.run(main())
    import asyncio
    import os
    from dataclasses import dataclass
    from datetime import datetime
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
    
    # より良い追跡のためにチェックポイントメタデータを保存
    @dataclass
    class Checkpoint:
        id: str
        description: str
        timestamp: datetime
    
    async def main():
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",
            extra_args={"replay-user-messages": None},
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        checkpoints = []
        session_id = None
    
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            async for message in client.receive_response():
                if isinstance(message, UserMessage) and message.uuid:
                    checkpoints.append(Checkpoint(
                        id=message.uuid,
                        description=f"After turn {len(checkpoints) + 1}",
                        timestamp=datetime.now()
                    ))
                if isinstance(message, ResultMessage) and not session_id:
                    session_id = message.session_id
    
        # 後で:セッションを再開して任意のチェックポイントに巻き戻す
        if checkpoints and session_id:
            target = checkpoints[0]  # 任意のチェックポイントを選択
            async with ClaudeSDKClient(ClaudeAgentOptions(
                enable_file_checkpointing=True,
                resume=session_id
            )) as client:
                await client.query("")  # 接続を開くための空のプロンプト
                async for message in client.receive_response():
                    await client.rewind_files(target.id)
                    break
            print(f"Rewound to: {target.description}")
    
    asyncio.run(main())
    1. 1

      テストファイルを作成する

      utils.py(Python)またはutils.ts(TypeScript)という新しいファイルを作成し、以下のコードを貼り付けます:

      def add(a, b):
          return a + b
      
      def subtract(a, b):
          return a - b
      
      def multiply(a, b):
          return a * b
      
      def divide(a, b):
          if b == 0:
              raise ValueError("Cannot divide by zero")
          return a / b
    2. 2

      インタラクティブな例を実行する

      ユーティリティファイルと同じディレクトリにtry_checkpointing.py(Python)またはtry_checkpointing.ts(TypeScript)という新しいファイルを作成し、以下のコードを貼り付けます。

      このスクリプトは、Claudeにユーティリティファイルにドキュメントコメントを追加するよう依頼し、その後、巻き戻して元に戻すオプションを提供します。

      import asyncio
      from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
      
      async def main():
          # チェックポイントを有効にしてSDKを設定
          # - enable_file_checkpointing: 巻き戻し用にファイル変更を追跡
          # - permission_mode: プロンプトなしでファイル編集を自動承認
          # - extra_args: ストリームでユーザーメッセージUUIDを受信するために必要
          options = ClaudeAgentOptions(
              enable_file_checkpointing=True,
              permission_mode="acceptEdits",
              extra_args={"replay-user-messages": None}
          )
      
          checkpoint_id = None  # 巻き戻し用のユーザーメッセージUUIDを保存
          session_id = None     # 再開用のセッションIDを保存
      
          print("Running agent to add doc comments to utils.py...\n")
      
          # エージェントを実行し、レスポンスストリームからチェックポイントデータをキャプチャ
          async with ClaudeSDKClient(options) as client:
              await client.query("Add doc comments to utils.py")
      
              async for message in client.receive_response():
                  # 最初のユーザーメッセージUUIDをキャプチャ - これが復元ポイント
                  if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                      checkpoint_id = message.uuid
                  # 後で再開できるようにセッションIDをキャプチャ
                  if isinstance(message, ResultMessage):
                      session_id = message.session_id
      
          print("Done! Open utils.py to see the added doc comments.\n")
      
          # 変更を巻き戻すかユーザーに尋ねる
          if checkpoint_id and session_id:
              response = input("Rewind to remove the doc comments? (y/n): ")
      
              if response.lower() == "y":
                  # 空のプロンプトでセッションを再開し、巻き戻す
                  async with ClaudeSDKClient(ClaudeAgentOptions(
                      enable_file_checkpointing=True,
                      resume=session_id
                  )) as client:
                      await client.query("")  # 空のプロンプトで接続を開く
                      async for message in client.receive_response():
                          await client.rewind_files(checkpoint_id)  # ファイルを復元
                          break
      
                  print("\n✓ File restored! Open utils.py to verify the doc comments are gone.")
              else:
                  print("\nKept the modified file.")
      
      asyncio.run(main())

      この例は、チェックポイントの完全なワークフローを示しています:

      1. チェックポイントを有効にする:enable_file_checkpointing=Trueとpermission_mode="acceptEdits"でSDKを設定し、ファイル編集を自動承認する
      2. チェックポイントデータをキャプチャする:エージェントの実行中に、最初のユーザーメッセージUUID(復元ポイント)とセッションIDを保存する
      3. 巻き戻しを確認する:エージェントの完了後、ユーティリティファイルを確認してドキュメントコメントを確認し、変更を元に戻すかどうかを決定する
      4. 再開して巻き戻す:はいの場合、空のプロンプトでセッションを再開し、rewind_files()を呼び出して元のファイルを復元する
    3. 3

      例を実行する

      環境変数を設定し、ユーティリティファイルと同じディレクトリからスクリプトを実行します。

      スクリプトを実行する前に、ユーティリティファイル(utils.pyまたはutils.ts)をIDEまたはエディタで開いてください。エージェントがドキュメントコメントを追加するとファイルがリアルタイムで更新され、巻き戻しを選択すると元に戻るのが確認できます。

      エージェントがドキュメントコメントを追加し、巻き戻すかどうかを尋ねるプロンプトが表示されます。はいを選択すると、ファイルは元の状態に復元されます。