Claude Codeのコンテキスト引き継ぎ：compact・clear・resumeと記録の検証

Claude Codeでコンテキストを引き継ぐときは、残っている作業、メモが参照するファイルの版、未決事項を残す。会話履歴だけでは、再開時にその情報を探し直すことがある。この記事では、HANDOFF.jsonとファイルの版を照合する小さな実行例を提案する。どちらもClaude Codeの組み込み機能ではなく、AIが記録に従うかは検証していない。

#compact・clear・resumeを選ぶ

中断の理由に合う操作を選ぶ。次は2026年10月23日に確認したAnthropic公式資料の説明だ。

公式資料には、上限に近づいたときの自動圧縮と、指示を添えた手動圧縮がある。たとえば/compact 次の操作、未決事項、テスト結果を残すと指定できる。ただし、この依頼を書いたことは、情報が残った証拠にはならない。公式のベストプラクティス

圧縮済みの会話を再開すると、圧縮時の要約と残ったメッセージから続く。直近の圧縮で要約されたメッセージを、元のまま読み直す動作ではない。/clearのあとも保存済みセッションを再開できる。セッション管理の公式資料。編集を続ける前に、会話が説明する状態と現在のファイルを照合したい。

#継続的な指示と今回の作業状態を分ける

公式資料は、セッションをまたぐ文脈としてCLAUDE.mdとauto memoryを説明している。また、これらの指示は強制される設定とは区別されている。繰り返し使う規約はプロジェクトの指示に置き、一件の中断作業は下の引き継ぎ記録に残す、という使い分けを提案する。メモリの公式資料

HANDOFF.jsonは当サイトが選んだ名前で、保存すれば特別に自動読込されるという保証はない。再開したセッションや新しいセッションに、ファイルを読むよう明示する。メモを短くするときも、未決の提案を承認済みへ変えない。会議で出た提案なら、出典と日付も未決事項の文に残す。発言の取得はCircleback MCPの設定記事で扱っている。

#コピーして使う引き継ぎテンプレート

次の構造をコピーし、仮の値を実際の作業に置き換えて保存する。共有する記録に資格情報や非公開の原文を含めない。testEvidenceが空なら、この記録にはテストの証拠がない。

{
  "version": 1,
  "goal": "再試行回数の提案を確認する",
  "file": {
    "path": "retry.js",
    "sha256": "64桁の小文字16進数に置き換える"
  },
  "pendingDecisions": ["再試行回数は担当者の承認待ち"],
  "nextAction": "再試行のテストを読み、回数を担当者へ確認する",
  "testEvidence": []
}

記録を書く時点のファイルのバイト列からハッシュを求める。macOSならshasum -a 256 retry.jsで表示できる。上の仮値のままでは検証に通らない。テストを実行したら、次の形式で実際のコマンド、終了コード、確認日時をtestEvidenceへ追記する。下の値は形式を示す例だ。

{"command":"node --test retry.test.js","exitCode":0,"checkedAt":"2026-10-23T00:00:00Z"}

日時と結果は過去の記録である。ハッシュが一致しても、記載したテストを実行した証明にはならず、依存関係や別ファイルの変更も分からない。現在の合格を報告する前には、関連するテストを再実行する。

#ファイルの版の照合をオフラインで再現する

検証関数、デモ、記入済みの引き継ぎ、合成した対象ファイルの4ファイルを同じフォルダへ保存する。Node.js 22以降、またはBunで、どちらかを実行する。

node context-handoff-demo.mjs
# または
bun context-handoff-demo.mjs

デモは同梱のサンプルだけを読み、メモリ上のコピーを変更して、次の結果を表示する。

{
  "valid": "valid",
  "changed": "changed-file",
  "malformed": "invalid-handoff",
  "missingData": "invalid-handoff",
  "missingFile": "missing-file"
}

検証関数は必須項目、呼出元が渡したファイル名、バイト列のSHA-256を照合する。JSON内のパスを開いたり、記録されたコマンドを実行したりしない。テストでは別のファイル名、項目の型の誤り、空の証拠欄も確認する。デモには通信、Claudeの呼出し、hook、ファイル書込がない。

validは、記録の形式が合い、渡したファイルのハッシュが一致したという結果だ。SHA-256は内容の意味、操作の権限、著者の真正性を検証しない。ファイルと記録の両方を書き換えられる人の改ざんも防がない。一つのファイルを調べる例なので、repository全体の版を証明するものでもない。changed-fileなら差分を読み、記録を見直してから更新する。通すためだけにハッシュを差し替えない。

#次のセッションに読むよう依頼する

再開するか、新しいセッションを開くかを選んだあと、次のように依頼する。

編集前にHANDOFF.jsonと対象ファイルを読んでください。
記録した版と現在のファイルを照合してください。
異なる場合は、作業を続ける前に差分を説明してください。
pendingDecisionsは未決のまま残し、次の操作とテストの証拠を示してください。
不足する判断は確認し、このメモから承認を推測しないでください。

これは運用の提案であり、AIが従った実績ではない。返答と記録を照合し、未決事項は担当者と決め、関連するチェックを再実行する。今回のオフライン実験が示すのは、検証関数が受理・拒否する条件までだ。