Claude Code checkpointの制限 — Bash変更・サブエージェント編集は復元されない

/rewind でコードを巻き戻したのに、ファイルの中身が変わっていない。Claude Codeのcheckpoint機能を使っているとこの状況に遭遇することがあります。原因は不具合ではなく、checkpointが追跡していない変更が最初から存在するためです。

Claude Codeのcheckpointは、Claudeがファイル編集ツールで加えた変更をユーザープロンプトごとに自動で保存点として記録し、/rewind で戻せる仕組みです。ただし対象は「Claudeが直接編集ツールで触ったファイル」に限られます。公式ドキュメントが明記する対象外は次の4つです。

• Bashコマンド経由の変更
• バックグラウンドのサブエージェント編集
• シンボリックリンクやハードリンク
• セッション外からの変更

/rewind コマンド自体の使い方はBash・サブエージェント・シンボリックリンクの3制限を扱っていますが、本記事はそこに加えてセッション外変更の扱いと、対象外ケース全体をGitとどう役割分担するかまで踏み込みます。

Bashコマンドで変更したファイルはなぜ戻らないのか

Claude Codeがcheckpointとして記録するのは、編集ツール(Edit・Write等)による変更だけです。Bashツール経由で実行されたファイル操作は追跡されません。

rm file.txt
mv old.txt new.txt
cp source.txt dest.txt

たとえばClaudeにこうしたコマンドを実行させた場合、rm で消えたファイルも mv でリネームされたファイルも、checkpointの記録には残りません。/rewind の画面を開いても、これらの変更を戻す選択肢自体が表示されない状態になります。ビルドスクリプトのクリーンアップコマンド、パッケージマネージャーの初期化、一括リネームスクリプトなど、Claudeに「Bash経由でまとめて片付けさせる」場面ほどこの抜け穴に当たりやすくなります。編集ツールとBashツールは同じセッション内で併用されるのが普通です。その結果、「一部のファイルはcheckpointに乗っているのに、別のファイルは乗っていない」という非対称な状態が生まれる点も覚えておく必要があります。

サブエージェントの編集が復元されないのはどんなときか

Sub-agentsがファイル編集ツールで加えた変更は、通常はメインセッションのcheckpointに含まれません。復元されるかどうかは、そのサブエージェントがどう実行されたかで変わります。

• フォアグラウンドで動くforkスキル: context: fork を設定したスキルで background: false を指定した場合です。メインセッションの手番の中で作業ツリーを直接編集するため、/rewind で通常どおり戻せます
• それ以外のサブエージェント: バックグラウンドで動くforkスキル(既定の挙動)、既定の各種Sub-agent、バックグラウンドで実行した /code-review --fix が該当します。checkpointの外側で編集を適用するため /rewind では戻せず、取り消すにはgitを使う必要があります

/code-reviewの実行経路を使い分けている場合は注意が必要です。--fix をバックグラウンドで走らせるかフォアグラウンドで走らせるかによって、この挙動が変わります。フォアグラウンド実行なら通常のcheckpointに乗りますが、バックグラウンド実行(既定)の適用結果はgit管理下でしか取り消せません。

シンボリックリンク・ハードリンクのファイルが巻き戻せない理由

/rewind メニューで「Restore code」か「Restore code and conversation」を選ぶと、checkpointが記録していたパスへ順に書き戻していきます。ただしそのパスがシンボリックリンクやハードリンクになっている場合、Claude Codeは書き戻しをスキップします。

スキップされる条件は3つです。

スキップされたファイルは現在の中身のまま残り、Restored the code, but skipped N files という警告が表示されます。件数しか表示されないため、どのパスがスキップされたかは別途確認する必要があります。/debug でデバッグログを有効にしてから復元を実行し、~/.claude/debug/<session-id>.txt を開くとパス一覧が得られます。macOSやLinuxなら、次のコマンドでリンクを直接洗い出す方法もあります。

find . -type l
find . -type f -links +1

dotfileマネージャーがプロジェクトへシンボリックリンクした設定ファイルや、pnpmがハードリンクで配置したファイルは典型例です。自分で作ったリンクだと分かっていれば、中身は変更されていないと判断してよく、そのセッションでの変更を取り消したいときはClaudeに指示するか自分で編集します。心当たりのないリンクが対象になっていた場合は、checkpoint後に何かが上書きした可能性があるため、中身を確認してから信用するのが安全です。v2.1.216より前のバージョンでは、/rewind はリンク先まで書き戻していた上に、この部分復元自体を報告していませんでした。バージョンを跨いで運用しているチームでは、古い挙動を前提にした手順書が残っていないか一度見直す価値があります。

使い分け早見表 — 変更の種類ごとに復元経路が違う

ここまでの内容を、変更の種類ごとに「/rewind で戻るか」「戻らない場合の対処」の軸で並べると次のとおりです。

「編集ツールかBashか」「フォアグラウンドかバックグラウンドか」という2つの軸さえ押さえておけば、目の前の変更がcheckpointの対象かどうかをその場で判断できます。

セッションの外からの変更はどう扱われるか

checkpointが追跡するのは、現在のセッション内で編集されたファイルだけです。Claude Codeの外で自分が手動編集したファイルや、別の並行セッションが加えた変更は、たまたま同じファイルを現在のセッションも編集していない限り記録されません。複数のセッションやWorktreeを並行して走らせている場合、この境界を意識しておかないと「戻したはずなのに変更が残っている」という状況を誤解しやすくなります。

Worktreeを使って複数の作業ツリーを同時に動かしている構成では、この境界がとくに効いてきます。各Worktreeはディレクトリごと独立しているため、あるWorktreeのセッションで /rewind を実行しても、別のWorktreeで進めている変更には一切影響しません。裏を返せば、ひとつのWorktree内でエディタから直接手を入れた変更は、そのセッションのcheckpointに乗らないまま残り続けます。「Claudeにまとめてやり直させたい」場面では、手動編集を挟まずセッション内で完結させたほうが、/rewind の挙動を予測しやすくなります。

checkpointとGitはどう役割分担すべきか

checkpointは「この手番の前まで一気に戻したい」という短期の試行錯誤に向いた仕組みで、コミット単位での恒久的な履歴管理を代替するものではありません。上記4つの対象外ケースはどれも、checkpointが追跡していない変更はgitでしか戻せないという同じ結論に行き着きます。Bashコマンドで消したファイル、バックグラウンドで動いたサブエージェントの編集、リンク先のファイル、セッション外の変更はすべて同様です。作業前にこまめにコミットしておく習慣が、checkpointの死角を実質的に埋める最も確実な方法になります。checkpointをワークフロー全体の中でどう組み込むかは、単体で考えないほうが位置付けを掴みやすくなります。計画・実行・レビューの流れとあわせて検討します。

よくある質問

/rewindで「Restored the code, but skipped N files」と出たら、まず何から切り分ければいいですか

先に find . -type l と find . -type f -links +1 でプロジェクト内のシンボリックリンク・ハードリンクを洗い出し、警告が出たタイミングと重なるパスがないか確認します。該当が見当たらない、または件数が合わない場合は /debug でデバッグログを有効にしてから復元をやり直し、~/.claude/debug/<session-id>.txt でスキップされたパスを直接特定します。自分で作ったリンクだと分かれば中身は変更されていないので、そのセッションでの変更を取り消したい場合だけClaudeに指示するか自分で編集します。

バックグラウンドで動くSkillの編集をあとから元に戻すにはどうすればいいですか

/rewind では戻せないため、gitで対象ファイルをrevertします。フォアグラウンドで動かしたい場合は、そのSkillのfrontmatterに background: false を追加します。メインセッションの手番の中で編集されるようになり、checkpointの対象に入ります。

checkpointの保存件数・保持期間そのものについては/rewind コマンドの解説記事にまとめています。

checkpointはいつまで残りますか

セッションと一緒に保存されるため、一度セッションを終えても /resume で再開すれば /rewind を使えます。ただしセッションごと30日で自動削除されるのが既定で、この期間は cleanupPeriodDays 設定で変更できます。

別の並行セッションが同じファイルを編集していた場合はどうなりますか

現在のセッションのcheckpointはあくまで自分のセッション内での変更を追跡するものです。別セッションが同じファイルを編集していた場合、/rewind は自分のセッションが把握している状態までしか戻せません。並行編集を避けたいファイルがあるときは、Worktreeでディレクトリごと分けるか、片方のセッションが終わってからもう片方を動かす順番にするほうが事故が起きにくくなります。

/rewindで戻す前に、変更が本当にcheckpoint対象か確認する方法はありますか

/rewind メニューを開くと、選んだプロンプト地点に「追跡済みのファイル変更」があるかどうかで選択肢が変わります。ファイル変更が追跡されていない地点では「Restore code」「Restore code and conversation」は表示されません。代わりに「Restore conversation」と要約系の選択肢だけが並びます。この表示自体が、その手番でBashコマンドしか実行していなかった(=編集ツールによる変更が無かった)ことのヒントになります。