$ man context-wiki/context-handoffs

Claude Code のセッションはステートレスだ。ターミナルを閉じればコンテキストは消える。新しいセッションは毎回ゼロから始まる。何を構築したか、何が壊れたか、どんな決定をしたか、何が途中なのか、一切記憶がない。コンテキストハンドオフがこれを解決する。各セッションの終わりに、何が起きたか、何が変わったか、何がまだ必要か、どんな決定がなされたかを記録した構造化ドキュメントを書く。次のセッションの最初に、そのドキュメントを読む。これで新しいセッションは直前に何が起きたかの完全なコンテキストを持つ。セッションがリセットされなくなり、複利で成長し始める。ハンドオフはあれば便利というものではない。すべてを忘れる AI と、昨日の上に積み上げる AI の違いだ。

アンチパターン

コンテキストハンドオフの最初のバージョンは常に単一ファイルだ。~/.claude/context-handoff.md のようなもの。一つのファイル。各セッションが開始時に読み、終了時に書く。ターミナルを一つだけ走らせているときは完璧に動く。二つ目を開いた瞬間に壊れる。ターミナル A が終了してハンドオフを書く。ターミナル B が 30 秒後に終了してターミナル A を上書きする。ターミナル A のコンテキストが消える。翌朝、コンテキストが半分欠けた状態でセッションが始まるまで気づかない。これは典型的な最後の書き込みが勝つ競合状態だ。スケールするほど悪化する。私は 4 から 6 個の Claude Code ターミナルを同時に走らせている。単一のハンドオフファイルでは、毎日 3 から 5 セッション分のコンテキストが静かに破壊される。システムは動いているように見える。ハンドオフファイルは常にそこにあるからだ。ただ、何が欠けているかが見えないだけだ。

パターン

修正はシンプルだ。一つのファイルの上書きを止める。代わりにタイムスタンプ付きファイルをディレクトリに書く。各セッションが ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md に書き込む。タイムスタンプがユニーク性を保証する。二つのセッションが衝突することはない。セッション開始時に、ディレクトリ内のすべての未消費ハンドオフを読む。各ファイルのコンテキストをマージする。読んだ後、各ファイルを file.md から file_done.md にリネームして再読み込みされないようにする。クリーンアップジョブが 7 日以上前の消費済みハンドオフを削除する。アーキテクチャ全体は 4 つの操作だ：ユニーク名のファイルを書く、未読ファイルをすべて読む、ファイルを消費済みにマークする、古いファイルをクリーンアップする。データベース不要。ロックファイル不要。セッション間の協調不要。各セッションが独立して動き、ディレクトリがマージを処理する。

コード

並行安全なハンドオフを使ったセッションのライフサイクル： セッション開始： ls ~/.claude/handoffs/*.md（*_done.md をスキップ） --> 未消費のハンドオフをそれぞれ読む --> file.md を file_done.md にリネーム --> すべてのコンテキストを現在のセッションにマージ セッション終了： --> ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md に書き込む --> 他のセッションのファイルを上書きしない クリーンアップ（定期的に）： find ~/.claude/handoffs -name '*_done.md' -mtime +7 -delete 並行安全性は命名規則から生まれる。同じ秒に終了する二つのセッションが衝突するには、同じスラッグが必要だ。実際にはこれは起こらない。スラッグは作業内容を記述し、タイムスタンプは秒単位の精度を持つからだ。

フォーミュラ

すべてのハンドオフドキュメントには 5 つのセクションが必要だ： 1. セッションサマリー。1 段落。目標は何で、何が起きたか。 2. 変更内容。作成、変更、削除されたファイル。具体的なパス。 3. 残作業。未完了のタスク、既知のバグ、次のステップ。 4. 重要な決定。アーキテクチャの選択、トレードオフ、次のセッションが蒸し返すべきでないこと。 5. アクティブコンテキスト。ブランチ名、実行中のプロセス、環境の状態、次のセッションが現在のマシン状態について知るべきこと。 事実だけを書く。コメントなし、意見なし、ナラティブなし。ハンドオフはステータスレポートであり、ブログ記事ではない。朝 6 時にこれを読むセッションが必要なのは、リファクタリングに対するあなたの感想ではない。どのファイルが変わり、何が壊れたかを知ることだ。