はじめに / 対象と前提
Claude Codeでエージェントに複数ファイルの変更を任せていて、「あ、この変更やっぱり違った」となった経験がある人向けの記事。
- 想定読者: Claude Codeを日常的に使っていて、大きめのリファクタや複数ファイルにまたがる変更をエージェントに任せたことがある人
- 前提環境: 2026年7月時点のClaude Code CLI(checkpoint/rewind機能搭載バージョン)、macOS/Linux両方で確認済み
- checkpoint機能は比較的新しい機能なので、古いバージョンでは
/rewindやEsc Esc操作が効かないことがある。claude --versionで確認しておくと安心
TL;DR
- Claude Codeには「Esc Esc」または
/rewindでセッション内の過去のチェックポイントまでコードを巻き戻せる機能がある - ただし戻るのはファイルの中身だけ。Bashで実行したコマンドの副作用(パッケージインストール、コンテナ起動、
git commitなど)は一切戻らない - 巻き戻しはターン単位の丸ごとスナップショットなので、良い変更と悪い変更が同じターンに混ざっていると両方消える
手順 / 動かし方
適当なgitリポジトリで再現できる。
mkdir rewind-demo && cd rewind-demo
git init -q
echo "# rewind demo" > README.md
git add -A && git commit -qm "init"
claude
セッション内で複数ターンに分けて指示を出す。
- 1ターン目:「
utils.pyにadd(a, b)関数を追加して」→ ファイル作成 - 2ターン目:「requestsライブラリを使うようにして、
pip install requestsも実行して」→ Bashでインストールが走る - 3ターン目:「
add関数にバグを仕込んでしまった(意図せずa - bになっていた)」という想定で確認
ここでEscを2回押すとチェックポイント一覧が出る(/rewindでも同じメニューが開く)。
❯ Esc Esc
Rewind to a checkpoint
> 3. utils.py に add() を追加(直前)
2. requests 導入 + pip install 実行
1. 初期状態
2番目のチェックポイントを選んで戻すと、utils.pyの中身は「requests導入直後」の状態に戻る。ここでgit statusとpip listを見比べる。
git status # utils.py の変更は戻っている
pip show requests # → 消えていない、インストールされたまま残る
ファイルの中身は巻き戻ったのに、pip installで入れたパッケージ実体はそのまま残っている。これがこの機能の一番のクセ。
ハマりどころ
1. Bashの副作用は戻らない
pip install / npm install / docker run / git commitなどBash経由で実行した操作の結果は、rewindの対象外。checkpointはエージェントのEdit/Write操作によるファイルスナップショットを管理しているだけで、シェルの状態や外部プロセスの状態までは追跡していない。
-
git commitした場合、コミット自体は消えない(HEADはrewindの影響を受けない)。rewind後に別の変更を積むと、消したはずの変更がコミット履歴上には残るというねじれが起きる - DBマイグレーションを走らせた場合も同様に、rewindしてもスキーマは戻らない
回避策: パッケージインストール・マイグレーション・外部API呼び出しのような「取り消せない」Bash操作をエージェントに頼む前は、一呼吸置いて本当に必要か確認する。どうしても必要なら先にgit commitしておき、rewindではなくgit revertベースで戻せるようにしておくほうが安全。
2. ターン単位の丸ごとスナップショットで部分ロールバック不可
1ターンでファイルAの良い変更とファイルBのバグ混入が同時に起きた場合、rewindするとAの良い変更も一緒に消える。checkpointはファイル単位ではなく、そのターン時点の全体スナップショットを保存・復元する仕組みだから。
回避策: リスクの高い変更(既存ロジックの書き換えなど)と、安全な変更(ドキュメント追加など)は意識的にターンを分けて依頼する。1ターン1タスクを心がけると、rewindの粒度が実用的になる。
3. 手動編集との衝突
Claude Codeの外側(自分のエディタ)で人間が手動編集したファイルは、checkpointのスナップショット管理の対象外。そのままrewindすると、意図せず手動編集分が古い状態に巻き戻されて消えることがある。
回避策: rewindを使う前にgit statusで未追跡・未コミットの手動変更がないか必ず確認する。あれば先にコミットかstashしてからrewindする。
背景・補足
なぜBashの副作用まで面倒を見てくれないのか。checkpointはおそらくエージェント自身が行ったEdit/Write系のツール呼び出しに対して、ファイルの差分スナップショットを保存・復元しているだけのレイヤーで、gitのようなフルのバージョン管理やコンテナ・プロセスの状態管理までは持っていないと考えると腑に落ちる。「コードの巻き戻し」に特化した軽量な機能であり、システム全体のスナップショット(VMイメージのようなもの)ではない、という理解で使うと事故が減る。
まとめ
- checkpoint/rewindは便利だが「ファイルの巻き戻し」専用機能であり、Bashの副作用は戻せない
- パッケージインストールやDB操作など取り消せない系のBash操作の前は一呼吸置く
- 大きな変更ほど1ターン1タスクを意識すると、rewindの粒度が扱いやすくなる
- 保険として
git commitを併用しておくと、rewindで拾いきれない部分もgit側でカバーできる