Claude Codeのための並列安全なコンテキストハンドオフ

2026年2月27日·1分で読める

1ファイルの問題

Claude Codeのセッションはすべてゼロから始まる。ターミナルを閉じれば、コンテキストは消える。何を作ったか、何が壊れたか、どんな判断をしたか、何が途中のままか、一切の記憶がない。

コンテキストハンドオフはこれを解決する。セッションの終わりに構造化されたドキュメントを書く。次のセッションの開始時にそれを読む。これで新しいセッションが前回の完全なコンテキストを持てる。

最初のバージョンは常に単一ファイルだ。~/.claude/context-handoff.md。すべてのセッションが開始時に読み、終了時に書く。シンプル。効果的。

2つ目のターミナルを開くまでは。

ターミナルAが終了してハンドオフを書く。ターミナルBが30秒後に終了して上書きする。ターミナルAのコンテキストは消える。ファイル自体はまだ存在するので気づかない。中身が間違っているだけだ。

これはlast-write-winsの競合状態だ。スケールすればするほど悪化する。私はClaude Codeのターミナルを同時に4〜6個動かしている。単一ファイルでは、毎日3〜5セッション分のコンテキストが静かに破壊される。ハンドオフファイルは常に存在するのでシステムは健全に見える。何が欠けているかが見えないだけだ。

ここに至るまで

進化はこうだった：

ハンドオフなし。 すべてのセッションがコールドスタート。毎回すべてを再説明する。最初の10分をモデルの方向付けに浪費する。ほとんどの人がここにいる。

単一ファイル。 ~/.claude/context-handoff.md。CLAUDE.mdがモデルに開始時に読んで終了時に書くよう指示する。セッションがリセットではなく蓄積されるようになる。大きなアップグレード。数ヶ月間うまくいった。

破綻。 並列ターミナルを使い始めた。コンテンツ用に1つ。インフラ用にもう1つ。デバッグ用に3つ目。Wiki構築用に4つ目。すべてが同じファイルに書き込む。コンテキストが消え始めた。ハンドオフファイルは常に中身があったので、数週間気づかなかった。80%のセッションが抜けていただけだ。

修正。 ディレクトリベースの並列書き込み。タイムスタンプ付きファイル。起動時に全読み込み。消費済みマーク方式。実装に30分。

振り返ると修正策がいかに明白だったかがもどかしい。アーキテクチャが問題だったのであってモデルが問題ではなかったと気づくまで、数週間コンテキストを失い続けた。

アーキテクチャ

並列安全なハンドオフシステムには4つの操作がある。

書き込み。 各セッションは~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.mdに書き込む。タイムスタンプが一意性を保証する。2つのセッションが衝突することはない。slugはそのセッションが何をしていたかを説明する。

読み込み。 セッション開始時に、_done.mdで終わらないすべてのファイルを一覧表示する。すべてを読む。すべてのコンテキストを現在のセッションにマージする。

消費。 読み取り後、各ファイルをfile.mdからfile_done.mdにリネームする。将来のセッションは消費済みファイルをスキップする。元のコンテンツは参照用にディスクに残る。

クリーンアップ。 定期的に7日以上経過した消費済みハンドオフを削除する。未消費のハンドオフは決して削除しない。

以下がライフサイクルの全体像：

Session Start:
  ls ~/.claude/handoffs/*.md (skip *_done.md)
  --> read each unconsumed handoff
  --> rename file.md to file_done.md
  --> merge all context into current session

Session End:
  --> write ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md
  --> never overwrite another session's file

Cleanup (periodic):
  find ~/.claude/handoffs -name '*_done.md' -mtime +7 -delete

これがシステムの全体だ。データベースなし。ロックファイルなし。セッション間の調整なし。各セッションが独立して動作し、ディレクトリがマージを処理する。

メモリのアップグレード

ハンドオフを修正している最中に、メモリファイルでも同じ問題に当たった。

MEMORY.mdはすべてのセッションが読み込む単一ファイルだった。最初は30行だった。数週間すべてのセッションが追記した結果、400行以上になった。Claudeは自動メモリファイルの最初の200行を読み込む。200行目以降はすべて見えなくなっていた。判断、設定、アーキテクチャメモ、すべてが静かに切り捨てられていた。

修正は同じパターンに従う。すべてを1ファイルに入れるのをやめる。

MEMORY.mdは軽量なインデックスになる。200行未満。セクションヘッダー、1行の要約、トピックファイルへのリンク。

トピックファイルが詳細を保持する。identity.mdでアイデンティティとプロフィールデータ。voice-rules.mdでボイスシステムのクイックリファレンス。infrastructure.mdでモデル、cron、主要パス。completed-work.mdで完了したイニシアチブ。

MEMORY.mdは常に読み込まれる。トピックファイルはタスクに関連する場合にオンデマンドで読み込まれる。インデックスは切り捨て制限内に収まる。詳細は必要な時に利用できる。

ハンドオフディレクトリと同じ原則だ。構造が、過負荷の単一ファイルに取って代わる。

ビフォー・アフター

ビフォー：

~/.claude/context-handoff.mdに1つのハンドオフファイル
最後に書いたターミナルが勝ち、他のコンテキストはすべて消失
制限なく肥大するMEMORY.mdファイル1つ
200行目以降のコンテンツは静かに見えなくなる
セッションがランダムにコンテキストを欠落、可視エラーなし

アフター：

~/.claude/handoffs/にハンドオフディレクトリ
すべてのセッションが一意の名前のファイルに書き込む
セッション開始時にすべての未消費ハンドオフをマージ
MEMORY.mdはトピックファイルにリンクする200行のインデックス
トピックファイルはオンデマンドで読み込み、切り捨てなし
並列ターミナル間でコンテキスト消失ゼロ

並列ハンドオフシステムは1週間稼働している。6ターミナル、同時セッション、コンテキスト消失ゼロ。朝のセッションが前日の3〜5つのハンドオフを読み、前日に起きたすべてを完全に把握した状態で始まる。

このアーキテクチャを使え

これがあなたに必要なCLAUDE.mdブロックだ。プロジェクトにコピーしてほしい。

## Context Handoff System

Handoffs are parallel-safe. Multiple terminals can write handoffs
without overwriting each other.

### On Session Start
1. Read all unconsumed handoffs:
   ls ~/.claude/handoffs/*.md 2>/dev/null | grep -v '_done.md$'
2. Also check legacy location: ~/.claude/context-handoff.md
3. After reading, mark each consumed:
   rename file.md to file_done.md
4. Clean up old consumed handoffs:
   find ~/.claude/handoffs -name '*_done.md' -mtime +7 -delete

### On Session End
Write handoff to ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md
Never overwrite another session's handoff.

ディレクトリ構造：

~/.claude/
  handoffs/
    2026-02-27_091522_blog-pipeline.md        (unconsumed)
    2026-02-27_093401_wiki-entries.md          (unconsumed)
    2026-02-26_201145_deploy-fix_done.md       (consumed)
    2026-02-26_184230_content-batch_done.md    (consumed)

すべてのハンドオフドキュメントには5つのセクションがある：

セッション要約。 1段落。目標は何で、何が起きたか。
変更内容。 作成、変更、削除されたファイル。具体的なパス。
まだ必要な作業。 未完了のタスク、既知のバグ、次のステップ。
主要な判断。 アーキテクチャの選択、トレードオフ、次のセッションが再検討すべきでないこと。
アクティブなコンテキスト。 ブランチ名、実行中のプロセス、環境の状態。

ハンドオフは事実に基づくものにする。コメンタリーは不要。朝6時にそれを読むセッションに必要なのは、ファイルパスとステータスであって、リファクタリングについての意見ではない。

名前をつける価値のある再帰的な洞察がある。セッションコンテキストを管理するコンテキストエンジニアリングのインフラ自体が、コンテキストの問題で壊れていた。アーキテクチャが並列性を考慮していなかったために、セッション同士が上書きし合っていた。修正は、私が他のすべてに使うのと同じ原則を適用することだった：構造、命名規則、そしてすべての状態を1つのファイルに入れないこと。