Claude CodeとBobで検証！3層の記憶設計で引き継ぎ一致率を9割に高める方法

• 事実と背景：Claude CodeとIBM Bobを用い、エージェントの記憶をSkills、AGENTS.md、引き継ぎノートの3層に分けて検証。
• 技術的変革：引き継ぎノートのテンプレートに「完了させる範囲」を明記することで、ツール間の解釈一致率が0%から90%へ劇的に向上。
• 現場への影響：開発者は特定のAIツールにロックインされることなく、リポジトリ内のMarkdownだけでシームレスな作業引き継ぎが可能に。

「昨日あれほど丁寧に教え込んだコーディング規約を、今日の新しいセッションでエージェントが綺麗さっぱり忘れて、また同じスパゲッティコードを吐き出している」――。コーディングエージェントを実務に導入したエンジニアなら、誰もが一度は深夜の障害対応のような徒労感とともに、この「記憶のデッドロック」に直面したことがあるはずだ。モデルのパラメータ数がどれだけ増えようとも、セッションが切れれば彼らは「記憶喪失の新人」に戻ってしまう。この問題を解決するために、我々開発者は自動メモリや独自のプロンプト注入など、様々なアプローチを試みてきた。しかし、本質的な解決策は高度なメモリ基盤の導入ではなく、リポジトリ内における「記憶の置き場所」の設計にあると私は考える。

認知科学における記憶の分類をソフトウェア開発に当てはめると、エージェントに必要な記憶は以下の3つのレイヤーに美しく整理できる。この3層モデルの肝は、情報の「変化の速さ（ライフサイクル）」に応じて置き場所を厳密に分ける点にある。

多くの開発現場で起きている悲劇は、このライフサイクルの混同から生じている。例えば、頻繁に変わる「現在の作業状態」を、毎回読み込まれるAGENTS.mdに書き込んでしまうと、情報がすぐに陳腐化し、エージェントは古い指示と新しいコードの間で無限ループに陥る。逆に、変化しないはずの「エンドポイント追加手順」を毎回のプロンプトで長々と説明するのは、トークンコストの無駄遣い以外の何物でもない。この3層を物理的・論理的に分離することこそが、エージェントのポテンシャルを100%引き出すための大前提なのだ。

特定のAIツールに依存し、そのエコシステムにロックインされることは、我々シニアエンジニアにとって最大の技術的リスクである。APIの障害、プランの利用制限、あるいはより優れた新ツールの登場に備え、私は普段からClaude CodeとIBM Bobを併用している。しかし、ここで課題となるのが「ツール間での記憶の引き継ぎ」だ。ツール固有の自動メモリ機能に依存していては、エージェントを切り替えた瞬間に作業コンテキストは完全に失われてしまう。

この課題に対し、リポジトリ直下にMarkdown形式の「引き継ぎノート（docs/handoff.md）」を配置し、両ツールに共有させるアプローチは極めてエレガントな解決策となる。今回の検証では、Claude Codeが実装したセッション1の状態から、プロンプトには「前回の続きをお願いします。」とだけ入力し、セッション2をClaude CodeまたはIBM Bobで実行した。その結果、ノートが存在する限り、ツールを跨いだとしても「どの地点から再開し、どの方針（コードには現れないエラーコードPRODUCT_NOT_FOUNDの適用など）に従うべきか」を完璧に踏襲できることが実証された。リポジトリ内のMarkdownこそが、ツールに依存しない「共通の脳」として機能するのだ。

しかし、ここで極めて興味深い「解釈のズレ」が発生した。初期のテンプレート（v1）を使用した場合、同じ引き継ぎノートを読ませているにもかかわらず、Claude Codeは「(2) GET /products/:id」の実装だけで作業を止めたのに対し、IBM Bobは「(3) POST /products」まで一気に実装を進めてしまったのだ。ツール間での解釈の一致率は「0/10（10回中0回）」という惨憺たる結果であった。原因は、テンプレートの「次にやること（最初の1手を具体的に）」という見出しの曖昧さにあった。エージェントによって、これを「今回のセッションの作業範囲」と捉えるか、「将来的なタスクリスト」と捉えるかの解釈が分かれたのである。

そこで、テンプレートの見出しを「次のセッションで完了させる範囲」と「その後の予定」に明確に分けた「v2」へとアップデートしたところ、驚くべき変化が起きた。IBM Bobも5回中4回で作業を(2)で止めるようになり、両ツールの振る舞いの一致率は「9/10（90%）」へと劇的に向上したのだ。この結果が示唆するのは、引き継ぎノートのテンプレート設計とは、単なるドキュメンテーションのルールではなく、「次のセッションを起動するエージェントに対する、厳密な制御プロンプトの設計」そのものであるという事実だ。見出しを1つ変えるだけで、エージェントの自律的な行動範囲を完全にコントロールできるのである。

エージェントがどれだけ賢くなろうとも、コードベースから読み取れない「暗黙知」の扱いには致命的な脆弱性が残る。今回の検証において、コードを見れば推測できる情報（既存のルーティング構成など）については、AGENTS.mdの記述が古くなっていてもエージェントは実際のコードを優先して正しく判断した。しかし、本当に危険なのは「コードに現れない方針・制約・経緯」が古くなったとき、あるいはそれらが引き継ぎの過程で風化していくときだ。

検証の過程で、Claude Codeは「負数も拒否にするのは自分の判断。方針上は明示されていないので、変える場合は要確認」と、ユーザーからの絶対的な指示と、エージェント自身の仮説的な判断を明確に区別してノートに記録していた。これは人間のシニアエンジニア顔負けの素晴らしい振る舞いである。しかし、このノートを引き継いだIBM Bobが作業を終えてノートを更新した際、その繊細な区別は失われ、「小数・負数は400で拒否」というフラットなルールへとマージされてしまった。さらに、更新者の署名も「by claude-code」のまま残されるという、メタデータの不整合まで発生した。引き継ぎという「伝言ゲーム」を1回経ただけで、意思決定の背景にある文脈（コンテキスト）は完全に削ぎ落とされてしまったのだ。

我々エンジニアが直面するのは、「AIにコードを書かせるのが楽になった」という目先の果実の裏にある、「意思決定のブラックボックス化」という新たな技術的負債である。コードの変更履歴はGitで追えるが、「なぜその設計にしたのか」「誰の指示でその制約が入ったのか」という経緯は、エージェントが自律的にノートを書き換える過程で容易に消滅する。この暗黙知の風化を防ぐために、我々は明日からどのような処方箋を適用すべきか。

実践的なアプローチとして、私は「引き継ぎノートの『範囲』と『判断理由』のセクションだけは、人間がコミット前に必ずレビューする」という運用ルールを提案したい。エージェントにノートの更新を自動で行わせることは作業効率上不可欠だが、それをノーチェックでマージし続ければ、リポジトリのコンテキストは数世代のセッションを経て確実に「スパゲッティ化」する。AIエージェントとの協働において、我々人間に残された最も重要な役割は、コードのレビューではなく、「コンテキスト（文脈）の番人」として意思決定の履歴を監視し続けることではないだろうか。あなたは、自らのリポジトリの記憶を、完全にAIの伝言ゲームに委ねる覚悟があるだろうか。