AIコーディングエージェントはステートレスです。新しいセッションを開始するたび、エージェントは以前に起こったことを記憶していません。セッションがクラッシュした場合、ターミナルを閉じた場合、文脈が尽きた場合 — エージェントが知っていたすべてが消えます。
長時間にわたる開発ワークフローをエージェントに扱ってほしかった。だからAIが自分の進捗を保存・復元できるチェックポイントシステムを作りました。
長いワークフローの問題
全体の開発サイクルに Claude Code を使用します — 単なる「関数を書く」タスクだけでなく、全体を通じて： Jira のチケットを読んで、設計ドキュメントを作成し、レビューを受け、複数のモジュールにまたがって実装し、テストを実行し、PR を作成します。
それは多くのステップです。そしてそのうちのどれかが失敗する可能性があります：
- セッションが実装途中でクラッシュする
- コードレビューの途中でコンテキストウィンドウがいっぱいになる
- ノートパソコンを閉じて翌日戻る
- レビュワーエージェントがタイムアウトする
チェックポイントがなければ、私は毎回最初からやり直します。チケットをもう一度読み直します。設計を再生成します。すでに終えた作業をやり直します。
私が作ったもの
開発ワークフローをフェーズごとに区切り、2種類の境界を設けました：自動チェックポイント（AI自体が状態を保存します）と 人間のゲート（AIが停止して私の承認を待つ）です。
ワークフローは次のようになります：
コンテキストを収集 → 設計を作成 → 設計をレビュー
→ CHECKPOINT 1: 私が設計を承認または編集します →
実装 → コードをレビュー
→ CHECKPOINT 2: 私がコードを承認または却下します →
問題を修正 → コミット → PRを作成 → PRコメントに返信
各フェーズはその状態と成果物を永続ストレージに保存します。セッションが終了すると、次のセッションは前回の続きから再開します。
チェックポイントの仕組み
状態の保存
各フェーズが完了した後、エージェントはチェックポイントを書き出します — 実行したこと、生成されたもの、次に来るものの記録です。チェックポイントには次が含まれます：
- フェーズ名とステータス（完了、進行中、失敗）
- 生成された成果物（設計ドキュメントのパス、レビューレポート、ブランチ名）
- 再開のために必要な文脈（どのモジュールが完了しているか、現在のレビューロール）
これは会話履歴ではありません。ワークフローの進行状況に関する構造化されたメタデータです。
再開
新しいセッションを開始して「再開」と言うと、エージェントは整合性を取るステップを実行します：
- 保存されたチェックポイントを永続ストレージで確認する
- ディスク上のアーティファクトをスキャンする（設計ドキュメントは存在しますか？機能ブランチはありますか？）
- 整合性を取る — ディスクは真実の源であり、チェックポイントは補足的なもの
- 最初の未完了フェーズを特定してそこへジャンプする
重要な洞察：ディスク上のアーティファクトはメタデータより信頼性が高い。 ディスク上に設計ドキュメントが存在するのに、チェックポイントが設計フェーズを「進行中」と示している場合は、ディスクを信頼してください。ファイルはそこにあります。フェーズは完了しています。
人間のゲート
ワークフローの2か所で私の明示的な承認を要します：
設計レビュー後 — エージェントは設計ドキュメントとレビューフィードを提示し、承認・編集・却下を求めます。私が「編集」と言えば、私の変更を設計ドキュメントに適用し、自動的にレビュを再実行します。私が承認するまでこれを繰り返します。
コードレビュー後 — 同じパターン。承認、問題を修正、または却下。重大な所見がある場合、私がチェックポイントを見たときにはすでにエージェントがそれらを自動修正しています。
これらのゲートは、すべてを自動化すべきではない決定があるため存在します。エージェントは一日中コードを書けますが、設計が妥当かどうかを決定するのは私です。
これが機能する理由
フェーズレベルの粒度
すべてのツール呼び出しやすべてのメッセージごとにチェックポイントを作成するわけではありません。フェーズ境界でチェックポイントを作成します — 「コンテキストを収集」が完了した後、「設計を作成」が完了した後、各モジュールが実装された後です。これによりチェックポイントデータを小さく、意味のあるものに保ちます。
モジュールレベルの進捗
実装は5つまたは6つのモジュールにまたがることがあります。チェックポイントは完了したモジュールを追跡します：
実装進捗（2/5モジュール）:
[完了] module-a
[完了] module-b
[ ] module-c ← ここから再開
[ ] module-d
[ ] module-e
モジュール2の後にセッションが終了した場合、次のセッションは直接モジュール3へスキップします。
タイムアウト回復
ときどきレビュアーエージェントがタイムアウトします — それは完了する前にターン制限に達します。すべてを再実行する代わりに、チェックポイントはどのレビュアーが完了したか、どれが完了しなかったかを記録します。再開時には、失敗したレビュアーだけを再実行して、その所見を既存のレポートに統合することができます。
これまでに学んだこと
チェックポイントは退屈であるべきです。 ユーザーが直接操作する機能ではありません。すべてを信頼性の高いものにするインフラストラクチャです。最高のチェックポイントシステムは、あなたがそれを考えなくても動作します。
ディスクはデータベースよりも真実の情報源として優れています。 ディスク上のファイルは可視で監査可能で、あらゆる故障にも耐えます。「設計フェーズ完了」と言うデータベースレコードは、設計ファイルが存在しない場合には役に立ちません。アーティファクトを確認し、メタデータは確認しないでください。
人間のゲートこそが真の価値です。 自動チェックポイントは素晴らしいですが、ワークフローを一時停止して出力を検査し、「これを戻して修正しろ」と言える能力こそが、AIアシスタントと勝手に動き回るAIの違いを生み出します。
AIエージェントには状態管理が必要です。プロンプトだけでは足りません。 私たちは完璧なプロンプトを作成するのに多くの時間を費やしますが、本当に難しい問題は、AIに良いコードを書かせることではなく、文脈を失うことなく前回の続きから再開し、作業を繰り返したり、すでに下した決定を忘れることを防ぐことです。
— DK
