ハンドオフドキュメント：セッションをまたぐエージェントメモリ
2026年3月21日、本番サイトはキャッシュパージによってパフォーマンスのボトルネックが露呈し、14秒のページ読み込みを提供していました。2つのセッションにわたって根本原因を調査し、遅いコードパスを特定し、修正プランを起草し、そのすべてをハンドオフドキュメントに記録しました。
ハンドオフドキュメントは、セッションの境界を越えて診断を運び、実装するエージェントが同じ誤った結論を再び導き出すのではなく、修正済みの理解を引き継げるようにするものです。 何をすべきかを述べるチケットとは異なり、ハンドオフは何が試され、何が間違っていて、なぜ以前のアプローチが失敗したのかを記録します。マーケットページのハンドオフは4日間で3回の修正を乗り越え、ページ読み込みを14秒から108ミリ秒へと短縮する実装を導きました。
そのハンドオフの初稿は間違っていました。誤ったコードパスを対象としていたのです。コードレビューにより、測定された遅いページはハンドオフが想定していた_fetch_market_data()ではなく、market_hub()によって提供されていたことが判明しました。ハンドオフは改訂されました。
第2稿では、Apple Mapsとティア数について不要なHTMXパーシャルを提案していました。レビューにより、Apple MapsはURLをローカルで署名しているため（遅延すべき外部リクエストがない）、またティア数は単一の集計クエリから取得すべきであることが指摘されました。ハンドオフは再び改訂されました。
第3稿では、weatherエンドポイントを非同期化することを提案していましたが、既存の同期HTTPクライアントがHTMXの背後でもイベントループをブロックし続けることについては言及していませんでした。ハンドオフは3度目の改訂を受けました。
4日後、別のセッションが3度改訂されたハンドオフを読み、修正を実装しました。Austinは14,290msから108msになりました。実装は正しいコードパスを対象とし、正しいクエリアプローチを使用し、不要なHTMXパーシャルを省きました。3回のレビューから得られた修正のすべてが、すでに組み込まれていました。
ハンドオフドキュメントは、4日間と複数のセッションにわたって診断を運びました。これがなければ、実装セッションはゼロから始まり、同じ誤った前提を立て、同じ不要な最適化を提案し、同じ修正を必要としたでしょう。ハンドオフは4日間の調査を、実装エージェントが数秒で読めるドキュメントに圧縮したのです。これは、特定の問題に適用されたcontext window managementです。つまり、診断を正確にするための修正を失わずに、セッションの境界を越えて診断を転送する方法なのです。
ハンドオフに含まれるもの
ハンドオフドキュメントはチケットではありません。チケットは何をすべきかを述べます。ハンドオフは、何が試され、何が学ばれ、何が間違っていて、次に何をすべきかを述べます。その違いは組織的記憶です。
マーケットページのハンドオフには以下が含まれていました。
診断。 6つのマーケットページのコールドレンダーTTFB測定値、381ms（東京、小規模マーケット）から14,290ms（Austin、500社以上）まで。測定値は、問題が企業数に応じてスケールすることを証明し、ボトルネックとしてクエリの形状を指し示しました。
優先順位付けされた根本原因。 インパクト順に並べられた4つの根本原因。クエリの形状（主因）、ブロッキングするweather API（副因）、別のコードパスでのフルテーブルスキャン（第3の要因）、キャッシュヘッダーの欠如（すでに部分的に対処済み）です。各根本原因には、ファイルパス、行番号、スローダウンを引き起こしている特定のコードパターンが含まれていました。
誤った方向転換。 初稿はmarket_hub()ではなく_fetch_market_data()を対象としていました。ハンドオフはこの誤りとその修正を記録し、実装セッションが同じ誤った結論を再び導き出さないようにしました。また、削除されたHTMXパーシャルと、それらが削除された理由も記録していました。Apple Mapsには外部リクエストがないこと、ティア数は集計クエリに含めるべきであることです。
実装プラン。 SQLの例、受け入れ基準、検証手順を含む5つのステップ。ステップ1：Python側のページネーションをデータベースクエリに置き換える。ステップ2：非同期クライアントでHTMX weatherパーシャルを追加する。ステップ3：副次的なコードパスをキャッシュする。ステップ4：エッジキャッシュヘッダーを追加する。ステップ5：同じ6つのURLを再測定する。
context window managementの記事では、このレベルの具体性がなぜ重要かを説明しています。ハンドオフ内のあらゆる曖昧さは、実装エージェントが再導出しなければならない判断となり、コンテキスト予算を消費し、同じ誤った結論のリスクを生みます。
コンテキストの地雷。 共有テンプレートコンテキストには、それをレンダリングしないページを含むすべてのページで、認証済みコイン残高ルックアップが含まれています。ハンドオフはこれをキャッシュ正確性の懸念として記録していました。適切なVaryヘッダーなしのs-maxageは、匿名ユーザーに古い認証データを提供する可能性があります。
なぜチケットでは失敗するのか
同じ作業のチケットはこう述べるでしょう。「マーケットページが遅い。マーケットハブのクエリを最適化せよ。」実装セッションは以下を行う必要があります。
- どのコードパスがマーケットページを提供しているかを発見する（ルーターを読まないと明らかではない）
- コードパスをプロファイリングしてボトルネックを見つける
- さまざまな最適化アプローチを検討する
- 1つを実装する
- そのアプローチに副作用があることを発見する（認証データのキャッシュ正確性）
- アプローチを修正する
ステップ1〜3は、調査セッションですでに完了していました。ハンドオフはその作業を先に進めます。チケットはそれを捨ててしまいます。
失敗モードは怠慢ではありません。失敗モードは、セッションの境界を越えたコンテキストの喪失です。AIエージェントのセッションは、クリーンなコンテキストウィンドウで始まります。前のセッションが発見したことを覚えていません。これは、context is architectureがシステムレベルで扱う同じ問題です。コンテキストウィンドウに入れるものが、出力の品質を決定します。チケットはゴールを提供します。ハンドオフは、ゴールに加えて、それに正しく到達するために必要な蓄積された理解を提供します。
改訂履歴が重要
ハンドオフの改訂履歴は、その現在の内容と同じくらい価値があります。マーケットページのハンドオフは、タイムスタンプと理由とともに3回の改訂を記録していました。
- 記録： 2026-03-21T17:24（元の調査）
- 改訂： 2026-03-21T18:20（コードレビューによる修正：誤ったコードパス、不要なHTMX）
- 改訂： 2026-03-25T06:30（実装完了、クエリ修正デプロイ）
改訂履歴は実装セッションに対してこう告げます。「この診断は異議を唱えられ、修正された。現在のバージョンはそれらの修正を取り込んでいる。」改訂のないハンドオフは間違っているかもしれません。3回の改訂を経たハンドオフは、ストレステストを受けたものなのです。
誤った方向転換は価値の一部です。「Apple MapsはURLをローカルで署名するため、/_map HTMXを検討したが却下した」と述べるハンドオフは、実装セッションが同じ最適化を提案し、レビューされ、却下されるのを防ぎます。ハンドオフは却下を前倒しにするのです。
ハンドオフを書くべきタイミング
すべてのタスクにハンドオフが必要なわけではありません。1セッションで済むバグ修正には、セッションをまたぐ永続性は不要です。ハンドオフが価値を持つのは次の場合です。
調査が高コストな場合。 パフォーマンスのボトルネックのプロファイリング、セキュリティ脆弱性の追跡、複数システムのインタラクションのデバッグなどです。調査に相応の労力がかかったのなら、ハンドオフがその労力を保存します。
実装が別のセッションで行われる場合。 今日調査を終えて明日実装するなら、ハンドオフがそのギャップを埋めます。なければ、明日のセッションはゼロから始まります。
診断が自明でない場合。 正しい修正が、3つの一見妥当な代替案がなぜ間違っているかを理解することを要求するなら、ハンドオフがその理解を捉えます。compound contextシステムは、ハンドオフがプロジェクト知識のより広い蓄積にどう適合するかを説明しています。「クエリを修正せよ」と述べるチケットは、なぜクエリに特定の修正が必要なのかを説明しません。
複数の人（またはエージェント）が取り組む可能性がある場合。 ハンドオフは共有理解のドキュメントです。それを読むあらゆるセッションは、完全な調査コンテキストを引き継ぎます。
複利コンテキストとしてのハンドオフ
ハンドオフはcompound contextシステムへの預け入れです。各ハンドオフは診断時間を捉え、再利用可能なアーティファクトに変換します。実装セッションは、ほぼゼロコストで診断を引き出せるのです。
時間をかけて、ハンドオフは調査履歴へと蓄積されていきます。マーケットページのハンドオフは、キャッシュパージインシデント、nightcheckの測定、破壊的なAPIガード、コードレビューシステムを参照しています。これらはそれぞれが以前のセッションの産物です。ハンドオフは、新しいセッションが追えるナラティブへとそれらをつなぎます。
ハンドオフは理解を置き換えません。実装セッションは依然として、コードを読み、修正を書き、結果を検証する必要があります。ハンドオフが置き換えるのは再発見です。セッションは、すでに知られていることを発見する必要はありません。Ralph agent architectureは、夜間実行ループの主要なセッション間永続化メカニズムとしてハンドオフを使用しています。AI engineering hubは、hooks、skills、memoryシステムからなるより広範なインフラストラクチャにハンドオフがどう適合し、エージェント支援型の開発が時間とともに複利で蓄積していくかを文書化しています。
FAQ
ハンドオフはどれくらいの長さにすべきですか？
診断、誤った方向転換、実装プランを捉えるのに十分な長さで、エージェントが1回のコンテキストロードで読める程度の短さです。マーケットページのハンドオフは103行でした。ほとんどのハンドオフは50〜150行です。
ハンドオフはどこに保存しますか？
プロジェクトのメモリディレクトリ~/.claude/projects/{project}/memory/handoff-{topic}.mdに保存します。メモリシステムはfrontmatterの説明に基づいて関連ファイルをロードするため、明示的な参照がなくても将来のセッションから発見可能です。
ハンドオフはドキュメントを置き換えますか？
いいえ。ドキュメントはシステムの仕組みを記述します。ハンドオフは、特定の問題について何が学ばれ、それについて何をすべきかを記述します。ドキュメントは恒久的なものです。ハンドオフは実装セッションによって消費され、その後は歴史的コンテキストとなります。
ハンドオフが古くなったらどうしますか？
ハンドオフのステータスフィールドがこれを追跡します。アクティブなハンドオフはPLANNEDまたはIN PROGRESSとマークされます。完了したハンドオフは実装コミットハッシュとともにRESOLVEDとマークされます。古くなったハンドオフは歴史的コンテキストとして可視ですが、アクション不可能です。
Sources
この記事は、2026年3月25日にデプロイされたクエリ形状の修正を導いたマーケットページパフォーマンスハンドオフ（handoff-market-page-perf.md）に基づいています。このハンドオフは4日間で3回の改訂サイクルを経て、132倍のパフォーマンス向上を達成する実装へとつながりました。Compound Contextで参照されています。