コードベース記憶ツールの選び方：code-review-graph、codebase-memory-mcp、Claude.md、Codex Skills の比較

AI Agent には「コードベース記憶」が必要だ、とよく言われます。しかしこの言葉は広すぎます。 Agent にプロジェクトルールを覚えてほしい人もいます。関数の呼び出し関係を見つけてほしい人もいます。毎回リポジトリ全体を再スキャンしてほしくない人もいます。固定のレビュー手順を自動で実行してほしい人もいます。

この四つは似て聞こえますが、必要なツールはまったく違います。 Claude.md と AGENTS.md はプロジェクトルールファイルに近いものです。 code-review-graph はコード関係グラフとレビュー補助に近いものです。 codebase-memory-mcp は複数ツールで共有するコード索引サービスに近いものです。 Codex Skills は再利用できるワークフロー手順書に近いものです。

選び方を間違えると、機能が少し足りないだけでは済みません。維持コストが上がります。この記事では単一ツールの使い方ではなく、選定の考え方を整理します。

まず結論

小さなプロジェクトでは AGENTS.md または Claude.md から始めます。中規模プロジェクトでは Codex Skills を追加し、繰り返す手順を固定します。コードレビューではまず code-review-graph を検討します。複数ツールで同じコード索引を共有したい場合に、codebase-memory-mcp を考えます。

最初から四つすべてを入れる必要はありません。良い順番は、ルールファイル、ワークフロー、構造索引、MCP サービスです。 AI Agent コードベース記憶ツール比較を読んでいるなら、この記事はより実践的な選定表として使えます。

四つのツールは四つの問題を解く

ツール	主に解く問題	向いている場面	最大のリスク
`Claude.md` / `AGENTS.md`	プロジェクトルールと長期制約	小チーム、単一リポジトリ、安定した規約	長すぎてコンテキストを汚す
`Codex Skills`	反復タスクのワークフロー	公開、翻訳、デプロイ、SEO、レビュー	未成熟な手順を固定してしまう
`code-review-graph`	呼び出し関係と変更影響	PR レビュー、設計影響分析	グラフが古い、除外設定が甘い
`codebase-memory-mcp`	ツール横断の共有コード索引	複数 Agent、複数 IDE、大規模リポジトリ	権限と索引維持のコスト

重要なのは「主に解く問題」です。これらは同じ種類のツールの別ブランドではありません。四つの層です。ルール層は Agent にどう作業するかを伝えます。ワークフロー層は繰り返し何をするかを伝えます。構造層はコード同士のつながりを伝えます。サービス層は複数 Agent が同じ索引を問い合わせられるようにします。

足りない記憶を先に見極める

ツールを選ぶ前に、四つ質問します。

Agent はプロジェクト規約を忘れているのか。
Agent は関連コードを見つけられないのか。
Agent は毎回同じ手順を繰り返しているのか。
複数ツール間でコンテキストが同期されていないのか。

規約を忘れるだけなら AGENTS.md で十分です。同じ作業手順を繰り返すだけなら Skill のほうが直接的です。呼び出し関係や影響範囲を漏らすならコードグラフを使います。 Codex、Claude Code、Cursor が同じ構造化索引を見たいなら MCP を接続します。

「記憶」という言葉だけで全部を混ぜないほうがよいです。

Claude.md と AGENTS.md：プロジェクトルール層

Claude.md と AGENTS.md の価値は短さにあります。 Agent に安定したルールを伝えるもので、プロジェクト百科事典ではありません。

書くべき内容は次のようなものです。

起動コマンド。
テストコマンド。
コードスタイル。
変更禁止のディレクトリ。
公開前チェック。
よくある落とし穴。
セキュリティ境界。
言語と文面の要件。

向かない内容は次のようなものです。

完全な業務背景。
古い議論ログ。
各モジュールの詳細説明。
長い設計文書。
一度きりの作業ログ。
検証されていない個人の好み。

良いルールファイルは道しるべです。 Agent が違う方向へ行かないように知らせます。厚い手引きにする必要はありません。詳しくは Claude.md は長ければよいわけではないを参照してください。

Codex Skills：ワークフロー記憶層

Skill はコード索引ではありません。覚えるのは「作業の進め方」です。

たとえばこのサイトの新規記事フローでは、次の手順があります。

新規記事かどうかを判断する。
次の番号を見つける。
index.zh-cn.md だけを作成する。
front matter を設定する。
公開日を制御する。
行数を確認する。
他言語を生成しない。

これらを毎回プロンプトに書くのは向いていません。 Skill として残すほうが自然です。

Skills に向くタスク

コンテンツ公開フロー。
多言語翻訳フロー。
デプロイフロー。
SEO クールダウン確認。
ローカルリライトフロー。
セキュリティチェックリスト。
固定形式のレポート。
コードレビュー手順。

Skills に向かないタスク

一度きりの不具合調査。
まだ探索中の手順。
その場の判断が多いタスク。
安定した受け入れ基準がないタスク。
回答を長くするためだけのプロンプト集。

良い Skill は説明を少なくし、制約を多くします。 Agent が同じミスを繰り返す確率を下げるためのものです。ゼロから書くなら Codex Skills で自分のワークフローを書く方法を参照してください。

code-review-graph：変更影響層

code-review-graph の目的はチャット履歴を覚えることではありません。焦点はコード構造です。グラフの考え方で、次の質問に答えやすくします。

この関数は誰に呼ばれているか。
このルートはどのモジュールに影響するか。
この PR はどの呼び出し連鎖を変えたか。
どのテストを追加すべきか。
どのファイルを一緒にレビューすべきか。

普通のプロンプトだけでは、こうした質問に安定して答えるのは難しいです。 Agent が diff だけ読むと間接影響を漏らします。リポジトリ全体を検索させるとコンテキストを浪費します。

グラフツールの価値はここにあります。コード構造を事前に計算しておき、Agent が必要なときに問い合わせます。

code-review-graph が向く人

PR レビューをよく行う人。
モジュール間の呼び出しが複雑なリポジトリを扱う人。
Codex や Claude Code に変更影響をレビューさせたい人。
毎回 Agent に全倉庫をスキャンさせたくない人。
レビュー手順を GitHub Actions に組み込みたいチーム。

code-review-graph が向かない人

数ファイルだけの小さなスクリプト。
PR や diff の流れがないプロジェクト。
チャット記憶だけを保存したい人。
索引生成結果を維持したくない人。
生成ファイルとソースディレクトリを分けられないリポジトリ。

使い始めるなら code-review-graph の使い方を参照してください。 CI に接続するなら code-review-graph を GitHub Actions に組み込むを参照してください。

codebase-memory-mcp：共有索引層

codebase-memory-mcp は複数ツール環境に向いています。一つの Agent だけを使うなら、必須ではありません。

しかし Codex、Claude Code、Cursor、Gemini CLI を同時に使うと問題が出ます。各ツールは自分のコンテキストを持ちます。各ツールはコードを再スキャンするかもしれません。各ツールのプロジェクト構造理解がずれるかもしれません。

このとき MCP 形式のコード索引に価値があります。コードベース構造をサービスとして複数 Agent に公開できます。 Agent は毎回理解を作り直さなくて済みます。

codebase-memory-mcp が向く場面

大規模リポジトリ。
多言語リポジトリ。
複数 Agent が同じプロジェクトを共有する。
ローカル優先のコード索引が必要。
MCP 経由で統一接続したい。
重複スキャンのコストを減らしたい。

使う前に考えること

これはサービスです。サービスには実行状態があります。ポート、権限、索引対象ディレクトリ、アップグレード問題もあります。

チームに維持する人がいなければ、「一度入れたが誰も触れないもの」になりがちです。すでに Agent 利用が安定しているチーム向けです。まだ試用段階の人には向きません。セットアップは codebase-memory-mcp チュートリアルを参照してください。

リポジトリ規模で選ぶ

リポジトリ規模は選定に強く影響します。スクリプトリポジトリと大規模モノリポジトリで同じ記憶構成にするべきではありません。

10 ファイル以下

複雑な記憶は不要です。残すものは次の程度で十分です。

README.md。
AGENTS.md。
基本テストコマンド。
Git diff レビュー。

それでも Agent がファイルを見つけられないなら、多くの場合タスク説明が広すぎます。

10 から 200 ファイル

軽量な構造説明が必要になり始めます。追加候補は次の通りです。

モジュールディレクトリ説明。
よく使うコマンド一覧。
開発または公開用 Skill を一つ。
必要なら code-review-graph。

この段階でもルールファイルは短く保ちます。すべてのモジュールを AGENTS.md に書かないほうがよいです。

200 から 2000 ファイル

変更影響の問題が出てきます。追加候補は次の通りです。

呼び出し関係グラフ。
変更影響レビュー。
CI 上の最小テスト戦略。
チーム共有ルール。
生成ディレクトリを除外する索引設定。

この層では code-review-graph の価値が高くなります。 Agent が推測に頼る量を減らせます。

多言語の大規模リポジトリ

共有索引とサービス化が必要です。追加候補は次の通りです。

codebase-memory-mcp。
統一 MCP 設定。
索引更新戦略。
権限の許可リスト。
サービス監視。
バージョンアップ記録。

ここではツール自体がインフラです。個人の習慣だけで維持してはいけません。

タスク種類で選ぶ

タスクによって必要な記憶は違います。

Bug 修正

Bug 修正では再現手順と関連ファイルが重要です。優先順位は次の通りです。

エラーログ。
再現コマンド。
直近の変更。
関連テスト。
呼び出し関係。

局所的な Bug なら MCP は不要です。モジュールをまたぐ Bug ならグラフを使います。

新機能実装

新機能では境界が重要です。優先順位は次の通りです。

要件範囲。
変更しない範囲。
データ構造。
API 契約。
テスト入口。

ルールファイルは Agent の無秩序な設計変更を防ぎます。 Skill は固定の実装フローを保存できます。

コードレビュー

コードレビューでは変更影響が最重要です。優先順位は次の通りです。

diff。
呼び出し元。
呼び出し先。
ルート入口。
テストカバレッジ。
セキュリティ境界。

ここでは長いプロンプトより code-review-graph が向いています。

ドキュメントと公開

ドキュメントと公開ではワークフロー記憶が重要です。優先順位は次の通りです。

front matter。
ファイル命名。
ビルドルール。
多言語同期。
リンクチェック。
公開前チェック。

この種類のタスクは Skills に向いています。

データ更新戦略

コードベース記憶は更新しないとすぐ Agent を誤導します。ツールごとに更新方法は違います。

ルールファイルは人が維持します。 Skills は手順の変化に合わせて更新します。 code-review-graph はコード変更後に再構築または増分更新します。 codebase-memory-mcp は索引サービスとデータディレクトリを維持します。

更新が必要なタイミング

モジュール追加。
ディレクトリ削除。
ルート構造変更。
テストコマンド変更。
ビルドツール変更。
生成ディレクトリ変更。
チーム権限ルール変更。
CI フロー変更。
Agent ツール更新。
MCP サービス更新。

更新後の確認

Agent が入口ファイルを説明できる。
Agent が関連テストを見つけられる。
Agent が生成ディレクトリをスキャンしない。
Agent が実際の diff を説明できる。
Agent が変更禁止範囲を守る。
Agent が正しい Skill を呼び出せる。
MCP クエリが最新ファイルを返す。
グラフ結果が実際のコードと一致する。

失敗例と修正

ルールファイルが長すぎる

症状は、Agent の読み込みが遅く、無関係なルールを引用することです。修正方法は削ることです。安定した制約だけを残します。手順は Skill に移します。背景は文書に移します。

Skill が広すぎる

症状は、あらゆるタスクが同じ手順に押し込まれることです。修正方法は分割です。一つの Skill は一種類の仕事だけを扱います。公開、翻訳、デプロイ、レビューを分けて書きます。

グラフが生成ディレクトリを除外していない

症状は、Agent がソースコードではなくビルド成果物に注目することです。修正方法は ignore 設定の更新です。 dist/、public/、node_modules/、キャッシュディレクトリを除外します。

MCP の権限が広すぎる

症状は、Agent が無関係なリソースにアクセスできることです。修正方法は権限分離です。読み取り専用ツールを先に使います。書き込みツールは別承認にします。本番系ツールはデフォルトで閉じます。

四つのツールをどう組み合わせるか

個人の小規模プロジェクトでは、AGENTS.md、少量のプロジェクト文書、Git diff、最小テストコマンドで十分です。中規模 Web プロジェクトでは、AGENTS.md、公開またはテスト用 Skill、code-review-graph、PR レビューテンプレートを組み合わせます。複数 Agent のチームプロジェクトでは、AGENTS.md、チーム Skills、code-review-graph、codebase-memory-mcp、CI レビュー、権限境界文書を用意します。コンテンツサイトと自動化ワークフローでは、公開 Skill、翻訳 Skill、SEO クールダウンルール、デプロイ Skill、少量のサイト構造メモが合います。

重要なのはツールの数ではありません。各層が解く問題を重ねないことです。

選定ツリー

まず、Agent はプロジェクトルールに頻繁に違反するかを聞きます。はいなら、AGENTS.md または Claude.md を書きます。

Agent は同じ手順を頻繁に繰り返すか。はいなら、Skill を書きます。

Agent は呼び出し関係や影響範囲を頻繁に漏らすか。はいなら、code-review-graph を使います。

複数 Agent が同じコード索引を共有する必要があるか。はいなら、codebase-memory-mcp を考えます。

いいえなら、まだツールを増やしません。この順番なら、単純な問題を複雑にしにくくなります。

既存記事とのつなげ方

この記事は選定入口として使えます。単一ツールのインストールは既存記事に任せます。

code-review-graph の具体的なコマンドは 7/99。 GitHub Actions 連携は 7/137。 codebase-memory-mcp のインストールは 6/113。ルールファイルの考え方は 4/118。汎用的な記憶ロードマップは 7/42。

こうすると読者は一つの記事で大量のコマンドに沈みません。先に方向を選び、その後で具体的なチュートリアルへ進めます。

最終的な選び方

Agent に固定ミスをさせたくないだけなら、AGENTS.md または Claude.md を選びます。 Agent に固定手順で作業してほしいなら、Codex Skills を選びます。 Agent に変更影響分析をさせたいなら、code-review-graph を選びます。複数 Agent にコード構造を共有させたいなら、codebase-memory-mcp を選びます。

成熟したコードベース記憶とは、すべてを覚えることではありません。ルール、ワークフロー、構造、サービスを適切な場所に置くことです。