はじめに
Claude Codeで作業していると、日常的に2つの困りごとにぶつかる。
- 「試しにこの実装でやらせてみたら、思ったのと違う形に壊れた。元に戻したい」
- 「今日はここまでにして、続きは明日か、別の端末からやりたい」
Claude Codeにはこの両方に対応する機能が揃っている。①には/rewind(チェックポイント)、②には--continue/--resume、そして「今のセッションを残したまま別の道を試す」ための/branch(--fork-session)がある。ただし公式ドキュメントではこれらがCheckpointing・Sessions・CLI referenceという別々のページに分かれていて、「実務でどう組み合わせて1つの安全な作業フローにするか」はどこにも書かれていない。
本記事ではこの3つを「①実験する → ②壊れたら戻す/うまくいったら残す → ③中断しても後で続きをやる」という1本のフローにまとめ、使い捨てのGitリポジトリで実際にclaude -p(非対話モード)を7回実行して検証した(実費合計 約0.65ドル)。さらに検証の過程で、claude --helpにも公式ドキュメントにも出てこない未文書化のフラグ--rewind-files・--resume-session-at・--resume-drops-turnをバイナリの文字列解析で見つけたので、これが実際に動くかどうかも実機で確かめた結果、-pだけで作ったセッションに対しては動かないことが分かった。この限界も含めて正直に書く。
検証環境はClaude Code v2.1.258(執筆時点の最新は2.1.268)。
手順:セッション管理を1本の実務フローにする
ステップ1: セッションに名前をつけて始める
複数の作業を並行する予定があるなら、最初から名前をつけておくと後で--resume <name>や/resume <name>で一発で戻れる。
claude -n auth-refactor
対話セッション中に途中から名付ける場合は /rename auth-refactor でも同じ効果になる(公式ドキュメントSessionsに記載)。
ステップ2: 作業中の安全網 ── /rewind(チェックポイント)
Claude Codeはユーザーのプロンプトを送るたびに、その時点のファイル状態を自動でチェックポイントとして記録する(直近100件を保持)。対話セッションで何かがおかしくなったら、入力欄が空の状態でEscを2回押すか/rewindと打つと、送った各プロンプトの一覧が出て、「コードと会話を両方戻す」「会話だけ戻す」「コードだけ戻す」を選べる。
ただし公式ドキュメントは次の限界を明記している(いずれもCheckpointingの”Limitations”節に記載、自分では未検証・出典明示):
- Bashコマンドによる変更は追跡されない(
rm/mv/cpなどで書き換えたファイルは/rewindで戻せない) - サブエージェントの編集は基本的に復元されない(フォアグラウンドで動く
context: forkスキル以外) - シンボリックリンク・ハードリンク先のファイルは復元されない
- デフォルトでセッション終了後約30日でスナップショットが削除される(
cleanupPeriodDaysで変更可)
ステップ3: 別のアプローチを試したい時 ── /branch
「今の会話は残したまま、別の実装方針も試したい」という時は/branchで分岐できる。会話履歴はその時点までコピーされ、新しいセッションIDに切り替わる。元のセッションはディスク上そのまま残り、/resume <元の名前>でいつでも戻れる。
コマンドラインからは claude --continue --fork-session または claude --resume <id> --fork-session で同じことができる(公式ドキュメント記載)。今回この分岐が非対話(-p)でも実際に機能するかを検証した(下記コピペ用プロンプト4)。
ステップ4: 作業を中断・再開する ── --continue / --resume
--continue(-c)はカレントディレクトリの直近1件を再開し、--resume <id-or-name>は名前・セッションID・.jsonlのパスを指定して、マシン上のどのプロジェクトからでも見つけて再開できる(v2.1.223以降。それ以前は同じプロジェクトディレクトリとそのworktreeしか探索しなかった、と公式ドキュメントに明記)。
ステップ5: スクリプトから続きを問い合わせる
claude -pで作ったセッションはインタラクティブな--continue//resumeの一覧からは基本的に除外される(claude -p --continueを使う場合のみ例外的に含まれる、と公式ドキュメントに明記)。ID さえ控えておけば、後から別プロセスで続きを問い合わせられる。
session_id=$(claude -p "READMEを1行で要約して" --output-format json | jq -r '.session_id')
claude -p --resume "$session_id" --output-format json "その要約をもう少し詳しくして" | jq -r '.result'
つまずき所の実演:隠しフラグ--rewind-filesを試す
/rewindはキー入力前提のUIなので、スクリプトからは呼べない。CHANGELOG.mdを読んでいたところ、v2.1.260の修正項目に見慣れないフラグ名を見つけた。
Fixed
/rewindand--rewind-filesreporting success when checkpoint backup files were missing and nothing was actually restored
--rewind-filesというフラグはclaude --helpのどこにも載っていない(v2.1.258・最新の2.1.268の両方で確認済み)。CLI referenceにもCheckpointingにも記載がない。インストール済みバイナリをstringsで解析すると、このフラグと使い方の説明文字列がそのまま埋め込まれていた。
strings -n 8 "$(which claude)" | grep -A1 "rewind-files <user-message-id>"
実行結果(自分の環境、v2.1.258で実測):
--rewind-files <user-message-id>
Restore files to state at the specified user message and exit (requires --resume)
同様に--resume-session-at・--resume-drops-turnという、これも--helpにも公式ドキュメントにも出てこないフラグの存在も確認できた。存在を推測だけで終わらせず、実際に実行してエラーメッセージを確認した。
claude --rewind-files "test-uuid"
claude --resume-session-at "test-uuid"
実行結果(自分の環境で実測):
Error: --rewind-files requires --resume
Error: --resume-session-at requires --resume
--resumeと組み合わせて実際に使えるかを、使い捨てのGitリポジトリで検証した。claude -pでファイルを作り(hello.txtにv1)、同じセッションを--resumeで呼び出して壊し(v2 - brokenに上書き)、最初のユーザーメッセージのUUIDをjqで取り出して--rewind-filesに渡した。
Error: File rewinding is not enabled.
fileCheckpointingEnabled: trueを--settingsで明示的に指定し直しても、最初のプロンプトからこの設定を付けたセッションを新規に作り直しても、結果は同じだった(2回、独立したセッションで再現)。公式のsettings-referenceではfileCheckpointingEnabledは「/rewindが復元するファイルスナップショットのオン/オフ」としか説明されておらず、-pセッションでの挙動には触れていない。断定はできないが、チェックポイント機能自体がインタラクティブなUI層に紐づいていて、-pだけで進行したセッションにはそもそもスナップショットが作られていない可能性がある。この記事では対話セッションでの--rewind-filesの動作までは確認できていない(自動化スクリプトでの対話セッション再現が安定せず、途中で断念した)。「-p運用のパイプラインで--rewind-filesによるスクリプト経由の巻き戻しを当てにするのは、現時点では避けたほうがよい」ということだけは実測で言える。
GitHub Issue検索では--rewind-filesや「File rewinding is not enabled」に完全一致する報告は見つからなかった(2026-09-11時点)。近い症状としては、Issue #91733(open、2026-09-03: 「Rewindはセッション中に編集された未追跡ファイルの内容を復元しない」)や、Issue #87575(open、2026-08-18: 「autoモードのシステムプロンプトがBashで編集されたファイルの/rewindをサイレントに失敗させる」)がある。いずれも他ユーザーの報告であり、自分の実機検証結果とは区別して書いている。
コピペ用プロンプト集
以下は上から順に試せる構成。1本目は課金・外部リソース不要で数秒、2本目以降は使い捨てのGit環境とclaude -p実行(実費が発生)を伴う。
1. まず自分の環境を確認する(無料・数秒)
claude --version
claude --help | grep -A1 "rewind\|fork-session\|resume "
期待結果: バージョン番号が表示され、grepの出力に--fork-sessionと--resumeは載るが--rewind-filesは載らない。
成功判定: --rewind-filesが--helpに出てこないことを自分の目で確認できれば、この記事の前提(未文書化フラグ)が再現できている。
2. 使い捨てリポジトリでセッションを開始し、IDを取得する
mkdir -p /tmp/cc_session_demo && cd /tmp/cc_session_demo
git init -q && git config user.email t@e.com && git config user.name t
echo init > README.md && git add . && git commit -q -m init
claude -p --output-format json "hello.txtというファイルを作り、中身を1行だけ'v1'にして。" \
> turn1.json
jq -r '.session_id, .result' turn1.json
cat hello.txt
期待結果: session_id(UUID形式)と「hello.txt を作成し…」という応答、hello.txtの中身がv1。
成功判定: cat hello.txtがv1と表示されればステップ1完了。
3. 同じセッションに追記して編集する
SID=$(jq -r '.session_id' turn1.json)
claude -p --resume "$SID" --output-format json "hello.txtを 'v2 - broken' に書き換えて。" \
> turn2.json
cat hello.txt
期待結果: v2 - brokenに上書きされる。
成功判定: --resumeで会話が引き継がれ、ファイル名を再指定しなくても正しいファイルが編集される。
4. 分岐(--fork-session)で別アプローチを試す
claude -p --continue --fork-session --output-format json \
"hello.txtの中身を今すぐ報告して(lsは使わないこと)。" > turn3_fork.json
jq -r '.session_id, .result' turn3_fork.json
echo "元のセッションID: $SID"
実際の実行結果(自分の環境):
13ea0b24-4be8-4a79-a2d3-902089ca5fdf
hello.txtの中身: `v2 - broken`
元のセッションID: 83b19823-5daa-4386-8a6d-1325e123bb4a
成功判定: 新しいsession_idが元の$SIDと異なり、かつ会話履歴(v2 - brokenという事実)は正しく引き継がれていれば分岐成功。元の$SIDでclaude -p --resume "$SID" ...を実行しても、分岐後の会話とは無関係に独立して続けられる(自分の検証でも元セッションは影響を受けず正常に応答した)。
5. --rewind-filesを試して、つまずき所を自分の目で確認する
TRANSCRIPT=$(find ~/.claude/projects -name "$SID.jsonl" | head -1)
UUID1=$(jq -sr '[.[] | select(.type=="user")][0].uuid' "$TRANSCRIPT")
echo "最初のユーザーメッセージUUID: $UUID1"
claude --resume "$SID" --rewind-files "$UUID1"
echo "exit_code=$?"
cat hello.txt
期待結果: Error: File rewinding is not enabled.が表示され、hello.txtはv2 - brokenのまま変化しない(exit_code=1)。
成功判定: このエラーが再現すれば、「-pだけで作ったセッションでは、この未文書化フラグは使えない」という本記事の指摘を自分の環境でも確認できたことになる。逆にもし将来のバージョンでこの挙動が変わって実際にファイルが復元された場合は、その事実の方が新しい発見なので記録しておいてほしい。
6. 後で別ディレクトリ・別プロセスから続きを問い合わせる
cd /tmp && claude -p --resume "$SID" --output-format json \
"念のため確認:hello.txtの最初の内容と現在の内容をそれぞれ教えて。" | jq -r '.result'
期待結果: /tmp/cc_session_demoから移動した/tmpでも同じセッションを解決できる(v2.1.223以降、公式ドキュメント記載のクロスプロジェクト検索)。「最初の内容: v1」「現在の内容: v2 – broken」のように過去の編集を正しく覚えている。
成功判定: 作業ディレクトリを変えても--resumeが同じセッションを見つけて、正しい会話履歴を返せば成功。
活用例
- 個人の試行錯誤: 実装方針で迷ったら、まず
/branchで分岐してから試す。ダメだったら分岐先を捨てて元のセッションに/resumeで戻ればよく、「うまくいった方だけ」が本線に残る。 - 一晩置いて再開する作業: 大きめのリファクタを
-nで名前付きで始めておき、翌日claude --resume <name>で再開する。セッションIDを覚える必要がなく、名前だけで戻れる。 - CI/スクリプトからの後追い確認:
claude -p ... --output-format json | jq -r '.session_id'でIDをログに残しておけば、後からclaude -p --resume <id>で「あの時のセッションに要約を聞く」といった後追い調査ができる(公式ドキュメントの想定用途)。 - チェックポイントに頼りすぎない: Bashで直接ファイルを操作させるタスク(
rm/mvを伴うリファクタなど)は/rewindで戻せないので、事前にgit commitしておくか、git statusで差分を確認してから進める習慣にする。
注意点(限界・つまずき所まとめ)
/rewindはBash経由の変更・大半のサブエージェントの編集・シンボリック/ハードリンクを対象外とする(公式ドキュメント明記)。Gitの代わりにはならない、と公式ドキュメントも明言している。--rewind-files・--resume-session-at・--resume-drops-turnは--helpにも公式ドキュメントにも載っていない未文書化フラグ。存在はバイナリの文字列解析と実行時のエラーメッセージで確認できたが、claude -pだけで作ったセッションに対しては--rewind-filesが「File rewinding is not enabled.」で失敗することを実機で確認した(fileCheckpointingEnabled: trueを明示しても変わらず)。将来のバージョンで挙動が変わる可能性があるため、自分の使い方で試す前に必ず使い捨て環境で再現確認すること。- 未文書化フラグである以上、将来のリリースで予告なく仕様変更・削除される可能性がある。本番の自動化スクリプトに組み込むのは避け、あくまで手元の調査・復旧の補助として使うのが無難。
- GitHub Issue #91733・#93045(いずれもopen)は
/rewindが特定条件(未追跡ファイル、削除されたGit管理下ファイル)で復元に失敗する報告で、自分の実行環境では再現確認していない。あくまで関連する既知の報告として紹介する。
締め:今日の一歩
まずはコピペ用プロンプト1(claude --version + --helpのgrep)を実行し、自分の手元で--rewind-filesが--helpに出てこないことを確認してほしい。それだけで「ドキュメント化されている機能とされていない機能の境界線」が体感できる。そのうえで余裕があれば使い捨てリポジトリを1つ作り、/rewindの代わりに--continue --fork-sessionで安全に分岐する流れを試してみるとよい。壊れても本線のセッションは無傷、というのが実務では一番効く安心材料になる。
Comments