ユタラボ
⚙️ 業務自動化レシピ

長いAI作業を途中から再開する：チェックポイント設計入門

AIエージェントの長い作業が中断しても最初からやり直さずに済むよう、目的、完了事項、変更ファイル、検証結果、保留、次の一手を記録し、安全に再開するチェックポイント設計を解説します。更新時刻や差分を残す方法も紹介します。

一言でいうと

長いAI作業では、会話の記憶より「ディスクに残した現在地」を頼りにします。

作業の目的、変更したファイル、検証結果、保留事項、次の一手を小さな区切りごとに保存します。再開時は、その記録と実際のファイルを比べます。一致した場合だけ、一件ずつ先へ進めます。

この記録点が「チェックポイント」です。

会話を再び開けること、コードを巻き戻せること、ディスク上の実状態が正しいことは、同じではありません。この違いを理解すると、中断が「最初からやり直す事故」ではなく、「確認できる場所で一度止まっただけ」に変わります。

製品の再開機能と作業の現在地は別に残す

AIエージェントへ調査、実装、テスト、文書化をまとめて頼むと、作業が長くなることがあります。途中でアプリが閉じることもあります。利用上限や通信の問題で止まることもあります。翌日に続きを始めようとしても、「どこまで終わったのか」が分からなければ、古い会話を何度も読み直すことになります。

製品内の再開機能は便利です。ただし、それだけを作業台帳にしてはいけません。

たとえばClaude Codeには、ユーザーが指示を送る前のコード状態を保存し、/rewindで戻れるチェックポイント機能があります。一方で、Bashコマンドによる変更、通常のサブエージェントによる編集、外部の編集、並行セッションの編集などには追跡上の制限があります。Claude Codeの公式説明も、製品内チェックポイントはGitの代わりではないと案内しています。

2026年7月27日時点の公式説明では、最近100件のファイルスナップショットを保持し、セッションとともに既定30日後に削除するとされています。これは変わり得る製品仕様です。利用時は最新の公式案内で確認してください。

ここで分けたいものは三つです。

記録の種類主な役割それだけでは分からないこと
会話履歴何を相談し、何を指示したかを読む指示どおりのファイルが今も残っているか
製品内チェックポイント対応範囲の変更を素早く巻き戻す外部編集や追跡対象外の変更まで含む全履歴
CHECKPOINT.mdとGit目的、差分、検証、次の一手を実状態と照合するAI製品の内部状態や未保存の会話

会話履歴は「相談の記録」です。製品内チェックポイントは「対応範囲の巻き戻し」です。CHECKPOINT.mdは「作業の現在地」です。Gitは「ファイル変更の台帳」です。

この四つは競合しません。役割を分けて併用します。

長い登山にたとえると、作業計画は地図です。CHECKPOINT.mdは現在地を示す標識です。Gitの差分は足跡です。テストログは高度計や天候計の記録です。地図だけ持っていても、現在地が分からなければ安全には進めません。

長い作業を始める前に完了条件と停止条件を決める

良いチェックポイントは、中断した瞬間だけでは作れません。開始前に「何をもって終わりとするか」を決めておく必要があります。

OpenAIのモデルガイダンスは、複数段階のツール作業で、許可する行動、必要な証拠、出力形式、再試行、停止条件などを明示する設計を案内しています。これは特定のAIだけの話ではありません。長い作業を安全に区切るときにも使える考え方です。

開始前に、次の五点を短く固定します。

項目固定する内容再開時に確かめること
目的何の問題を解くか目的が途中で変わっていないか
成果物作成・変更するファイル実物が存在し、想定した場所にあるか
完了条件合格を示す検証同じ検証を再実行して通るか
許可された操作読み取り、範囲内の編集、テストなど依頼された範囲を越えていないか
停止条件削除、公開、課金、認証、知らない差分など人の確認が必要な状態ではないか

たとえば「CSVを読み込み、月ごとの合計を表示するローカルツールを作る」だけでは、完了の判定が曖昧です。次のように書き換えます。

  1. 目的を「指定されたCSVから月別合計を確認できるようにする」と決めます。
  2. 成果物をsrc/load_csv.py、tests/test_load_csv.py、README.mdに限定します。
  3. 完了条件を「正常、空ファイル、不正な日付のテストがすべて通る」と決めます。
  4. 許可する操作を、対象フォルダの読み取り、三ファイルの編集、ローカルテストに限定します。
  5. 削除、外部公開、追加料金、認証、対象外ファイルの変更が必要なら止めると決めます。

この五点があれば、再開時に古い会話を最初から解釈し直す必要が減ります。「目的に対して何が不足しているか」を、成果物と検証結果から判定できるためです。

作業は、検証できる単位へ分けます。「完成するまで作る」という一行では大きすぎます。

  1. 要件をPLAN.mdに固定する。
  2. 最小の画面を作り、表示を確認する。
  3. 入力処理を追加し、正常系を試す。
  4. 失敗する入力のテストを追加する。
  5. 全テストを実行する。
  6. 利用手順を書く。

各区切りには、一つ以上の合格条件を置きます。「画面を作る」なら、ローカルでページが開き、入力欄が表示されることです。「テストする」なら、決めたコマンドの終了コードと合格件数を確認することです。

区切りが大きすぎると、中断時に未確認の変更が増えます。細かすぎると、記録ばかりになります。初心者は20〜40分で一度検証できる大きさから試してもよいでしょう。ただし、この時間は公式仕様ではありません。固定の分数より、検証が一つ終わった直後、別工程へ移る前、戻しにくい変更の前を優先します。

CHECKPOINT.mdに残す七つの項目

チェックポイントは長い日記ではありません。翌日の自分や別のAIが、読んだ直後に実状態を確認できる記録です。

残す内容は、次の七組に整理できます。

  1. 目的と完了条件: 何を作り、何が通れば終わりかを書きます。
  2. 更新日時と基準位置: いつの記録か、どのGitコミットを基準にしたかを書きます。
  3. 状態: 未着手、進行中、完了、保留のどれかを選びます。
  4. 完了したこと: 実物と検証がある事実だけを書きます。
  5. 変更ファイル: 今回の目的に関係するファイルだけを書きます。
  6. 検証コマンドと結果: 成功も失敗も、再実行できる形で書きます。
  7. 保留と次の一手: 判断待ちと、再開後に行う一操作を分けます。

状態の意味も固定しておくと、AIごとの解釈の差を減らせます。

状態意味書いてはいけない状態
未着手まだ変更も検証もしていない調査しただけなのに実装済みとする
進行中変更はあるが合格条件を満たしていない「ほぼ完了」で不足を隠す
完了成果物があり、決めた検証を通過した未実行のテストを通過扱いにする
保留人の判断、認証、費用、外部サービスなどが必要AIだけで決められないことを推測して進める

次は、記入済みの最小例です。

# チェックポイント

更新日時: 2026-07-27 14:30:00 +09:00
基準位置: Gitコミット a1b2c3d
状態: 進行中

### 目的
CSVを読み込み、月ごとの合計を表示するローカルツールを作る。

### 完了条件
- 正常なCSV、空ファイル、不正な日付のテストが通る。
- READMEの手順だけでローカル起動できる。

### 完了したこと
- CSV読み込み関数を追加した。
- 正常なCSVのテストを3件追加した。

### 変更したファイル
- src/load_csv.py
- tests/test_load_csv.py

### 検証
- コマンド: python -m pytest tests/test_load_csv.py
- 結果: 3 passed
- 終了コード: 0
- ログ: logs/latest-test.txt

### 保留
- 空のCSVを渡した場合の表示文が未決。

### 次の一手
tests/test_load_csv.py に空ファイルのテストを1件追加する。

大切なのは、予定と実績を混ぜないことです。「追加する予定」は完了事項ではありません。「テストを書いた」ことと「テストが通った」ことも別です。原因が分からない失敗は、「原因未判明」と書けば十分です。分かったふりをするより、再開に役立ちます。

「次の一手」は、読んだ直後に実行できる粒度にします。「例外処理を進める」では広すぎます。「空ファイルのテストを一件追加する」なら、再開直後の迷いが減ります。

基準位置には、可能ならGitのコミットIDを残します。コミットIDは、履歴上の地点を示す短い記号です。記録後に別の人や別セッションが変更しても、どこを基準に比較すればよいか分かります。

ただし、チェックポイントへ何でも貼り付けてはいけません。パスワード、APIキー、トークン、Cookie、個人情報は記録しません。共有用のログでは値を伏せます。そのうえで「どの項目を伏せたか」と「正規の再取得方法」だけを残します。

GitとPowerShellで停止・再開を安全にする

手で書く情報は、抜けることがあります。時刻、変更一覧、差分の大きさ、テスト出力など、機械で取れる情報はコマンドへ任せます。

停止時に現在地を採る

PowerShellでは、次の順で確認できます。

Get-Date -Format "yyyy-MM-dd HH:mm:ss K"
git status --porcelain=v1
git diff --stat
git diff --cached --stat
git rev-parse --short HEAD

Get-Date -Formatは、現在日時を一定の書式で出力します。Microsoft LearnのGet-Date説明にあるとおり、書式を指定できるため、手入力による日付のばらつきを減らせます。末尾のKは、+09:00のような時差を確認するために使っています。

git status --porcelain=v1は、変更ファイルと未追跡ファイルを、スクリプトで扱いやすい短い形式で表示します。Gitのgit-status公式文書では、git statusがHEADとインデックス、インデックスと作業ツリーの差、未追跡ファイルを表示すると説明されています。インデックスとは、次のコミットへ入れる変更を準備する場所です。

二つのgit diffは役割が異なります。

  • git diff --statは、作業ツリーとインデックスの差を要約します。主に、まだステージしていない変更を見るために使います。
  • git diff --cached --statは、インデックスと基準コミットの差を要約します。ステージ済みの変更を見るために使います。

Gitのgit-diff公式文書によると、--statはファイル名と変更量の要約です。差分の本文ではありません。また、未追跡ファイルの内容も表示しません。そのため、git diff --statだけを「全変更の確認」と呼ぶことはできません。変更一覧はgit statusでも確認します。

検証結果を画面とログへ残す

テスト出力は、画面に表示しながらファイルへ保存できます。

New-Item -ItemType Directory -Force .\logs | Out-Null
python -m pytest 2>&1 | Tee-Object -FilePath .\logs\latest-test.txt
$testExitCode = $LASTEXITCODE
"終了コード: $testExitCode"

Tee-Objectは、コマンドの出力をファイルへ保存しながら、同じ出力を画面側の処理へも渡します。Microsoft LearnのTee-Object説明で確認できる動作です。

ただし、ログファイルが作られたことは、テスト成功の証明ではありません。

次の三つを分けて残します。

  1. 実行したコマンド。
  2. 合格件数、または失敗した検査名。
  3. 終了コード。

$LASTEXITCODEは、直前に実行したネイティブプログラムやPowerShellスクリプトの終了コードを保持する自動変数です。ただし、スクリプトの呼び出し方やexitの使い方で規則が変わります。詳しくはPowerShellの自動変数の公式説明で確認できます。

終了コードは、対象コマンドの直後に別の変数へ退避します。別のコマンドを先に実行すると、確認したい値を取り違える恐れがあるためです。さらに、実際のテストランナーが表示する合格数や失敗名も確認します。環境によってパイプラインの扱いに差が出る可能性があるため、終了コードだけに依存しません。

PowerShellの版は次のコマンドで確認できます。

$PSVersionTable.PSVersion

PowerShell 6以降のTee-Objectは、ファイル出力の既定としてBOMなしUTF-8を使います。古いWindows PowerShell 5.1も同じだと決め付けないでください。日本語が文字化けする場合は、使っている版と保存されたファイルの文字コードを先に確認します。

再開時は読む、照合する、一件だけ進める

チェックポイントがあっても、いきなり編集を再開してはいけません。記録後に人や別のAIがファイルを変更している可能性があります。

次の順で進めます。

  1. CHECKPOINT.mdを読み、目的、完了条件、基準位置、次の一手を確認します。
  2. git status --porcelain=v1で現在の変更一覧を採ります。
  3. git diff --statで未ステージ側の要約を見ます。
  4. git diff --cached --statでステージ済み側の要約を見ます。
  5. 記録した基準位置、変更ファイル、現在の差分を照合します。
  6. 前回の検証コマンドを再実行します。
  7. 一致した場合だけ、「次の一手」を一件実行します。
  8. 再検証し、同じCHECKPOINT.mdを更新します。

記録と実状態が一致しない場合は、自動で先へ進みません。知らない変更がある場合も止めます。前回は成功した検証が再現しない場合も止めます。これは失敗ではありません。別の作業者や別セッションの変更を上書きしないための安全装置です。

再開用の依頼文も、短く固定できます。

CHECKPOINT.md、現在のGit状態、直近のテストログを読んでください。
記録した基準位置、変更ファイル、現在の差分が一致するか確認してください。
一致しなければ編集せず、食い違いだけを報告してください。
一致した場合だけ「次の一手」を一件実行してください。
実行後は同じ検証を行い、CHECKPOINT.mdを更新してください。
削除、公開、外部送信、課金、認証が必要なら停止してください。

手書きから小さく自動化する

最初から大きな管理システムを作る必要はありません。小さな個人開発なら、次の構成で始められます。

my-project/
├─ PLAN.md
├─ CHECKPOINT.md
├─ src/
├─ tests/
└─ logs/
   └─ latest-test.txt

PLAN.mdは目的地です。CHECKPOINT.mdは現在地です。logsは計器の記録です。役割を分けると、再開時に読む順番が自然に決まります。

自動化するなら、まず時刻、変更一覧、終了コードの三つに絞ります。対応製品では、決まった出来事の前後にコマンドを動かす「フック」を使える場合があります。GitHub Copilotでは、sessionStart、sessionEnd、postToolUse、errorOccurredなどのフックが公式文書に示されています。

ただし、これはGitHub Copilot固有の例です。すべてのAI製品に同じイベント名や保存場所があるわけではありません。フックがなくても、手書きのCHECKPOINT.mdだけで再開設計は成立します。

自動ログにも秘密情報は残しません。コマンドの全出力を保存する前に、認証情報や個人情報が混じらないかを確認します。外部サービスの応答を丸ごと保存するより、検証に必要な結果だけを残すほうが安全です。

よくある質問

AIの会話を再開できればCHECKPOINT.mdは不要ですか

不要にはなりません。

会話履歴は、指示と説明を読み返すために役立ちます。しかし、外部編集や製品の追跡対象外の変更まで、現在のディスク状態と一致していることは保証しません。製品内チェックポイントにも保存範囲や保持期間があります。

CHECKPOINT.mdには、目的、基準位置、変更ファイル、検証結果、次の一手を短く残します。再開時はgit statusなどで実状態と照合します。会話の再開とファイルの照合を組み合わせることで、思い込みによる上書きを減らせます。

チェックポイントは何分ごとに作ればよいですか

固定の分数より、意味のある区切りを優先します。

おすすめの記録時点は、検証が一つ終わった直後、別工程へ移る前、長い処理の前、戻しにくい変更の前、作業を終える前です。初心者が20〜40分ごとに一度見直す方法は、調整用の目安にはなります。ただし、公式仕様ではありません。

記録が負担なら、文章を増やすのではなく、時刻やGit状態をコマンドで採ります。作業時間より記録時間が長くなるなら、区切りが細かすぎます。

git diff —statだけで全変更を確認できますか

できません。

引数なしのgit diff --statは、主に未ステージの差分を要約します。ステージ済みの差分はgit diff --cached --statで別に確認します。未追跡ファイルの存在はgit status --porcelain=v1で確認します。

また、--statは変更量の要約です。実際に何行がどう変わったかを確かめたい場合は、必要なファイルの差分本文も読みます。

テストが失敗した状態もチェックポイントにできますか

できます。失敗地点も有効な現在地です。

状態を「進行中」にします。そのうえで、実行コマンド、失敗した検査名、終了コード、ログの場所を残します。原因が分からなければ「原因未判明」と明記します。

たとえば「5件中4件合格。test_empty_csvが失敗。終了コード1。原因未判明」と書けば、再開後に同じ失敗を再現できます。「だいたい動く」と書くより、はるかに役立ちます。

Gitを使っていない作業ではどう再開しますか

Gitがなくても、現在地は残せます。

  1. 対象フォルダの絶対パスを書きます。
  2. Get-Date -Format "yyyy-MM-dd HH:mm:ss K"で更新日時を残します。
  3. 変更したファイル名を列挙します。
  4. 上書き前のコピーを別フォルダへ保存し、元ファイルとの対応を書きます。
  5. 検証コマンドと結果を残します。
  6. 次の一手を一件だけ書きます。

Gitより差分を照合しにくいため、変更前の退避コピーが重要です。知らない更新時刻や変更ファイルが見つかった場合は、上書きせず止めます。今後も繰り返し変更する作業なら、Gitの導入を検討すると履歴を比べやすくなります。

公式一次情報

確認日: 2026-07-27

まとめ

チェックポイントの目的は、会話を長く保存することではありません。目的、差分、検証、保留、次の一手を、ディスク上の実状態と照合できるようにすることです。

製品内の再開機能は便利です。ただし、追跡対象や保持期間には製品ごとの条件があります。CHECKPOINT.md、Gitの状態、テストログを組み合わせると、特定製品の記憶だけに依存せず再開できます。

まず、次の三つを実行してください。

  • プロジェクト直下にCHECKPOINT.mdを一つ作り、目的、完了条件、変更ファイル、検証結果、保留、次の一手を書きます。
  • 次の検証が終わった直後に、日時、Gitの変更一覧、未ステージとステージ済みの差分要約、終了コードを記録します。
  • 再開時は記録と実状態を照合し、一致した場合だけ「次の一手」を一件進めます。食い違いがあれば編集を止めます。

戻れる場所を先に作れば、長いAI作業は中断に強くなります。止まらない仕組みを目指すのではなく、止まっても正しい場所から再開できる仕組みを作りましょう。

続き（結論と実データ）はnoteに置いています

ここでは手順のところまで書きました。実際に出た数字、うまくいかなかった条件、そのまま使える設定ファイルは、 note の記事にまとめてあります。

noteで続きを読む Xをフォローする

⚙️ 自動化

AIに調べ物を任せるときの設計図：質問・出典・検証を3段階に分ける

AIエージェントへ調査を頼む前に出口を定め、質問を分解し、広い検索と深い確認を使い分け、出典の強さと反証結果まで保存するための実践的な調査手順を初中級者向けに解説します。未確認事項を残す最小の保存形式も紹介します。
⚙️ 自動化

AIエージェントに仕事を任せる技術：依頼票・検収・引き継ぎの実践

AIエージェントへ仕事を任せるときに、目的、担当範囲、合格条件、停止条件を依頼票へまとめ、調査・変更・検証へ分割し、証拠を使って検収と引き継ぎを進める具体的な方法を解説します。人間が持つ仕事との分け方も整理します。
⚙️ 自動化

AIで個人開発を進める実践手順：アイデアを動く試作品に変える

AIを相談相手兼作業助手として使い、日常の面倒から題材を選び、1枚の仕様メモ、最小実装、テスト、機能追加の順に、小さな個人開発を安全に進める実践手順を紹介します。AIへの依頼を作業単位に分けるコツも学べます。