Agent SDK のファイル巻き戻し｜チェックポイントの使い方

公開 2026-11-09更新 2026-11-09著者永上裕之仕事の自動化

この記事の要点

AI にファイルを直させると、「思っていたのと違う直し方をされた」ということが起きます。そんなとき、AI が書き換える前の状態にファイルを戻せる のがチェックポイントの仕組みです。Agent SDK の全体像は Claude Agent SDK とはで解説しました。

この記事では、公式ドキュメント「Rewind file changes with checkpointing」（2026年11月9日確認）にもとづいて、Agent SDK でファイルの変更を巻き戻す方法 と、戻せない変更を整理します。

結論：2つの設定を入れ、戻す地点の ID を取っておく

チェックポイントを有効にすると、AI がファイルを書き換える前に、SDK がそのファイルの控えを取ります。 戻すときは、控えを取った地点の ID を指定します。

設定	Python	TypeScript	役割
チェックポイントを有効にする	enable_file_checkpointing を True	enableFileCheckpointing を true	ファイルの変更を記録する
戻す地点の ID を受け取る	extra_args に replay-user-messages	extraArgs に replay-user-messages	利用者のメッセージに ID が付く

戻すと、AI が新しく作ったファイルは消え、書き換えたファイルはその地点の中身に戻ります。 ただし会話は戻りません。会話の記録と文脈はそのまま残ります。

有効にする：上の2つの設定を入れる。公式の例では、ファイル編集を確認なしで通す acceptEdits モードも合わせて使っている
ID を取る：会話の中で流れてくる利用者のメッセージの uuid を保存する。たいていは 最初の1つ でよい（そこに戻せば変更前の状態になる）。あとで戻すなら、会話の ID（session_id）も保存する
戻す：rewindFiles（Python は rewind_files）に ID を渡して呼ぶ

会話が終わったあとで戻す場合は、空の指示で会話を再開し、その中で戻す関数を呼びます。 再開する側の設定でも、チェックポイントを有効にしておく必要があります。会話の再開のしかたは Agent SDK のセッションで解説しています。

会話の ID と地点の ID があれば、CLI から戻すこともできます。この指定は claude --help には出てきませんが、公式の説明どおりに使えます。

型	やり方	向いている場面
危ない操作の前に印を付ける	毎回の往復の前に、最新の ID だけを持っておく。おかしければすぐその地点に戻して止める	検査に通らなければ即やり直したい
複数の地点を残す	すべての ID を、何をした時点かのメモと一緒に一覧で持つ	「1回目の直しは残し、2回目のテスト追加だけ取り消す」など

戻せるのは、主に会話の中で Write・Edit・NotebookEdit が書き換えたファイルだけ です。公式が挙げる制限は次のとおりです。

戻らない物	中身
コマンドでの変更	sed などのコマンドで書き換えた物は戻らない。ただし同じファイルを先に Write や Edit で書き換えていれば戻る
サブエージェントの変更	子の AI の変更は記録されない（例外は前面で動く一部のスキル）
別の会話	地点は、作った会話の中でだけ使える
フォルダ	フォルダの作成・移動・削除は戻らない
ネットの向こうのファイル	手元にないファイルは記録されない

そのため、「戻せる前提で任せる」なら、ファイルの書き換えは Write・Edit で行わせる のが安全です。コマンドで一括置換させると、戻せないことがあります。何をどこまで許すかは Agent SDK の権限設定で組み立てられます。

症状	原因	直し方
設定や関数が見つからない	SDK の版が古い	SDK を最新に上げる
メッセージに ID が無い	replay-user-messages を入れていない	2つめの設定を足す
No file checkpoint found for this message	元の会話でチェックポイントが無効だった、会話を最後まで終えずに戻そうとした	元の会話で有効にし、最後まで終えてから再開して戻す
File rewinding is not enabled	再開した会話などで有効にしていない	再開する側の設定でも有効にする
ProcessTransport is not ready for writing	会話の受け取りが終わったあとに戻す関数を呼んだ	空の指示で再開し、その中で呼ぶ

CLI でファイルと会話を巻き戻す方法は Claude Code の巻き戻し（rewind）で解説しています。

永上裕之

ユニコスクール株式会社代表取締役。AIエージェント専門のスクール＆コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。