code-review-graph チュートリアル：Codex／Claude Code の PR 影響分析と CI 増分グラフ

code-review-graph は、ローカルファーストのコード構造図ツールです。 Tree-sitter を使用してコードを解析し、呼び出し、インポート、継承、テスト、その他の関係をウェアハウス内の SQLite グラフデータベースに書き込みます。その後、CLI と MCP を使用して、Codex や Claude Code などのツールに構造化コンテキストを提供します。

「AI に PR を自動的に承認させる」のではなく、レビューごとに AI がリポジトリ全体を再検索するコストを削減し、レビュー担当者がファイル間の呼び出し、影響を受ける可能性のある領域、テストのギャップを見つけられるようにするという問題を解決します。最終的な結論は依然として Git diff、テスト結果、そして人間の判断に帰されます。

プロジェクトアドレス: tirth8205/code-review-graph

どのような場合に使う価値があるか

より適したもの:

数百から数千のファイルを含むリポジトリ。
モノリポジトリまたは多言語プロジェクト。
ファイル間およびモジュール間の変更を頻繁にレビューします。
呼び出し元、依存関係、テスト、実行フローを追跡する必要がある。
コアグラフデータをローカルに維持したい。

必ずしも次のような場合に適しているわけではありません。

少数のファイルのみを含む小規模なプロジェクト。
変更は単一の独立したファイルに集中します。
主にドキュメント、構成、または写真をレビューします。
チームにはインデックスの鮮度を維持する準備ができていません。
1 回限りのタスクで、差分を直接読み取る方が速くなります。

差分が小さい場合、グラフクエリの結果は元の差分よりも大きくなる可能性があります。影響範囲を拡大するかどうかを決定する前に、最小限のコンテキストと変更の検出を最初に使用する必要があります。

動作原理とデータ境界

主なプロセスは次のとおりです。

1
2
3
4
5
6


Git 跟踪文件
  -> Tree-sitter 解析
  -> 节点与关系
  -> .code-review-graph/ SQLite
  -> CLI / MCP 查询
  -> Codex、Claude Code 或人工审查

コアの構成とクエリはローカルで実行でき、コードをクラウドにアップロードする必要はありません。オプションの埋め込みでは、オンプレミスモデルまたはクラウドプロバイダーを使用できます。クラウド埋め込みを有効にする前に、コード配布の境界とチームのポリシーを確認する必要があります。

Git リポジトリでは、git ls-files によって返された追跡ファイルのみがデフォルトでインデックス付けされます。 Git によって追跡されている生成ファイルまたはサードパーティコードを除外するには、リポジトリルートに次のファイルを作成します。

1
2
3
4
5


# .code-review-graphignore
generated/**
*.generated.ts
vendor/**
node_modules/**

グラフデータベースは通常、次の場所にあります。

1

.code-review-graph/

これは再構築可能なアーティファクトであるため、無条件に Git に送信しないでください。

インストール前に Python 環境を準備します

プロジェクト要件 Python 3.10 以降:

1
2


python --version
git --version

グローバル CLI を分離するには、pipx を使用することをお勧めします。

1
2
3


python -m pip install --user pipx
python -m pipx ensurepath
pipx install code-review-graph

直接インストールすることもできます。

1

python -m pip install code-review-graph

インストール後の検証:

1
2


code-review-graph --help
code-review-graph status

シェルがコマンドを見つけられない場合は、まず Python スクリプトまたは pipx の bin ディレクトリが PATH に入っているかどうかを確認します。複数のコピーを繰り返しインストールしないでください。

Codex または Claude Code 用に MCP を構成します

統合インストールコマンドは、インストールされているプラットフォームを検出します。

1

code-review-graph install

Codexのみを構成します:

1

code-review-graph install --platform codex

Claude Code のみを構成します:

1

code-review-graph install --platform claude-code

インストーラーは、対応する MCP 構成を書き込み、サポートされているプラットフォームにフック、スキル、またはルールの説明を追加します。チームのカスタマイズを誤って上書きしないように、実行前に既存の構成をバックアップし、実行後に差分を確認してください。

終了したらAIツールを再起動します。 Claude Code は /mcp 経由で接続を確認できます。他のクライアントは、code-review-graph サーバーが接続されており、ツールがリストされていることを確認する必要があります。

コードグラフを初めて構築する

分析するウェアハウスのルートディレクトリを入力します。

1
2
3
4


git rev-parse --show-toplevel
git status --short
code-review-graph build
code-review-graph status

status は、少なくともゼロ以外のファイル、ノード、エッジの数を表示し、ビルドブランチとコミットを記録する必要があります。ノードがゼロの場合、一般的な理由は次のとおりです。

現在のディレクトリはターゲットウェアハウスではありません。
ファイルは Git によって追跡されません。
拡張子がパーサーによって認識されません。
.code-review-graphignore はすべてのコンテンツを除外します。
ビルドが途中で失敗しました。

正式に使用する前に、既知の関数を選択して構造クエリをテストし、呼び出し関係が実際のファイルに戻ることができることを確認します。

毎日の更新と変更の検出

コード変更後に増分更新を実行します。

1
2


code-review-graph update
code-review-graph status

簡潔な出力とコンテキストを保存する情報が必要な場合:

1
2


code-review-graph update --brief
code-review-graph detect-changes --brief

update 変更ファイルを更新します。 detect-changes は現在の Git の変更と影響を分析します。 2 つは異なる意味を持っており、detect-changes が機能するからといってグラフが最新であると想定すべきではありません。

長期的な開発の場合は、以下を使用できます。

1

code-review-graph watch

ただし、大規模なリポジトリでは、CPU、ファイルリスニングの上限、および生成されたディレクトリノイズを観察する必要があります。 CI 環境は通常、build または update の明示的な実行に適しています。

Codex または Claude Code に PR をレビューしてもらいましょう

MCP をインストールして構成を完了したら、次のことを提案できます。

1
2
3


使用 code-review-graph 审查当前分支相对 main 的变化。
先检测变更，再给出跨文件影响、调用者、相关测试和测试缺口。
只读取必要上下文；所有结论附上文件路径，并与 git diff 对照。

プロジェクトでは、次のようなワークフローテンプレートも提供します。

review_changes: 現在の変更を確認します。
architecture_map: アーキテクチャを理解します。
debug_issue: 関係に沿ったトラブルシューティングを行います。
onboard_developer: 開始コンテキストを生成します。
pre_merge_check: マージ前のチェック。

テンプレートを使用する場合でも、無料のプロンプトを使用する場合でも、順序を維持する必要があります。

グラフデータベースが新しいことを確認します。
実際の Git diff を読みます。
変更されたノードをクエリします。
呼び出し元、依存関係、およびテストを展開します。
実際のテストを実行します。
手動レビューの結論。

Token の節約を解釈する方法

現在、CLI は detect-changes --brief と update --brief でコンテキスト保存パネルを表示できます。デフォルトの数値はプロジェクト定義の見積もりであり、請求書の正確な Token とは異なります。

トークナイザー相互検証を使用するには、追加の依存関係をインストールし、--verify を追加する必要があります。

1
2


python -m pip install tiktoken
code-review-graph detect-changes --brief --verify

評価中の記録:

生の差分とリポジトリのサイズ;
グラフによって返されるコンテキストの長さ。
AI が実際に読み取りを続けるファイル。
偽陰性と偽陽性。
レビューには時間がかかります。・写真に写っていない問題がないかテストしてください。

公式ベンチマークの最高倍率をチームの予算に直接適用しないでください。小さなリポジトリ、単一ファイルの変更、言語解析範囲、および質問方法はすべて結果を変えます。

GitHub Actions サンプルの位置づけ

以下はこのサイトがまとめたセルフメンテナンスの例であり、プロジェクトが正式にリリースした GitHub アクションではありません。 CLI のインストール、ローカルマップキャッシュの復元、増分更新の実行、レポートの出力のみを行います。 PR を自動的に承認したり、結果をコメント領域に書き戻したりすることはありません。

最初に作成します:

1

.github/workflows/code-review-graph.yml

例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


name: code-review-graph

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  impact:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install
        run: python -m pip install code-review-graph

      - name: Restore graph cache
        id: graph-cache
        uses: actions/cache@v4
        with:
          path: .code-review-graph
          key: crg-${{ runner.os }}-${{ github.event.pull_request.base.sha }}
          restore-keys: |
            crg-${{ runner.os }}-

      - name: Build or update graph
        shell: bash
        run: |
          if [ -d .code-review-graph ]; then
            code-review-graph update --brief
          else
            code-review-graph build
          fi
          code-review-graph status

      - name: Analyze changes
        run: code-review-graph detect-changes --brief | tee crg-review.txt

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: code-review-graph-report
          path: crg-review.txt
          if-no-files-found: warn

初めて有効にする場合は、キャッシュ手順を削除し、クリーンビルドが成功したことを確認してからキャッシュを追加することをお勧めします。キャッシュは正確性の源ではありません。パーサー、スキーマ、またはプロジェクト構造を変更した後は、完全な再構築を許可する必要があります。

キャッシュキーとグラフの鮮度

この例では、異なるベースライン間で古いイメージが直接再利用される可能性を減らすために、PR ベースラインをキャッシュキーに送信します。依存関係ロックファイルの概要を追加することもできます。

1

key: crg-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'package-lock.json') }}-${{ github.event.pull_request.base.sha }}

次の場合、キャッシュを削除して再起動する必要があります build:

code-review-graph または Tree-sitter パーサーをアップグレードします。
除外ルールを変更します。
大規模なディレクトリ名の変更。
グラフ統計の異常な低下。
ローカルおよび CI の結果は再現できません。
スキーマまたはデータベースの互換性の変更。

受け入れキャッシュヒットでは、アクション表示 cache-hit をチェックするだけでなく、status のブランチ、コミット、ファイル数、ノード数、エッジ数もチェックする必要があります。

Fork PR の権限境界

コア分析では、チェックアウトされたソースコードを読み取るだけでよく、ウェアハウスへの書き込み権限は必要ありません。また、デプロイメント Secret を使用しないでください。保管することをお勧めします:

1
2


permissions:
  contents: read

PR ヘッドをチェックアウトした後にコマンドを実行するために、未レビューの Fork コードで pull_request_target を使用しないでください。この組み合わせにより、基礎となるリポジトリ権限または Secret が公開される可能性があります。

今後、コメントが自動的に投稿される場合は、コメントを独立した管理されたステップに分割し、レポートの内容、権限、およびソースを確認する必要があります。最も安全な最初のバージョンは、メンテナーによるレビューのためにアーティファクトのみをアップロードします。

モノレポと大規模な変更

.code-review-graphignore をモノリポジトリで使用すると、明示的にレビューの対象外となるビルドディレクトリとベンダーを除外できます。速度を上げるために共有ライブラリを除外しないでください。除外しないと、分析でパッケージ間の関係が失われます。

非常に大きな diff の場合は、最初にファイルのリストを取得する必要があります。

1

git diff --name-only origin/main...HEAD

MCP の自動検出が長時間応答しない場合は、変更されたファイルの明確なリストを影響分析ツールに渡して、バックエンドで過剰な範囲で Git 検出が繰り返し実行されるのを避けることができます。

このプロジェクトは、CRG_MAX_CHANGED_FUNCS、CRG_MAX_TRANSITIVE_FRONTIER、CRG_TOOL_TIMEOUT など、非常に大きなフロントを制限するための境界環境変数も提供します。調整する前にデフォルトの動作を記録します。制限が低すぎるとリコールが減少します。

Windows MCP 接続と遅延のトラブルシューティング

CLI は正常ですが、MCP は Invalid JSON: EOF while parsing または Connection closed を報告します:

code-review-graphをアップグレードします。
install を再度実行して構成を更新します。
バージョン FastMCP がプロジェクトの現在の要件を満たしていることを確認します。
MCP が仮想環境で .exe を直接実行できるようにします。
PYTHONUTF8=1を設定します。
クライアントを再起動し、MCP ログを表示します。

概略構成:

1
2
3
4
5
6
7


{
  "code-review-graph": {
    "command": "C:\\path\\to\\venv\\Scripts\\code-review-graph.exe",
    "args": ["serve", "--repo", "C:\\path\\to\\project"],
    "env": {"PYTHONUTF8": "1"}
  }
}

CLI の status と detect-changes は非常に高速ですが、MCP 呼び出しがタイムアウトすると、Git の遅い変更の検出と遅いグラフクエリを区別するために、git diff --name-only の結果が最初に明示的にツールに渡されます。

グラフデータが間違っている場合の復旧方法

まずシーンを録画します。

1
2
3


code-review-graph status
git rev-parse HEAD
git status --short

次に、増分更新を実行します。

1
2


code-review-graph update
code-review-graph status

それでも結果が異常である場合は、再構築可能な .code-review-graph ディレクトリをバックアップまたは削除して、再度構築してください。他のデータを誤って削除しないように、削除する前に、ディレクトリがターゲットウェアハウスに実際に存在することを確認してください。

これもアップグレード後に再実行する必要があります。

1
2
3


python -m pip install -U code-review-graph
code-review-graph install
code-review-graph build

install はプラットフォーム構成を更新するために使用され、build はグラフデータを更新するために使用されます。 2 つのステップを混同しないでください。

アンインストールとロールバック

最初にプレビューします:

1

code-review-graph uninstall --dry-run

確認後にアンインストールします。

1

code-review-graph uninstall

統合のみを削除し、グラフデータを保持します。

1

code-review-graph uninstall --keep-data

次に、Codex、Claude Code およびその他の構成に MCP 項目が残っているかどうかを確認し、元の構成のバックアップを復元できることを確認します。

最終承認チェックリスト

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[ ] Python 版本至少为 3.10
[ ] CLI --help 和 status 可运行
[ ] build 后文件、节点和边数量非零
[ ] .code-review-graph 已加入忽略策略
[ ] Codex 或 Claude Code 能列出 MCP 工具
[ ] update 后图对应当前分支与提交
[ ] detect-changes 结果能回到真实 Git diff
[ ] 影响范围和测试缺口经过人工核对
[ ] Token 节省区分估算与 --verify 结果
[ ] CI 仅有 contents: read 权限
[ ] Fork PR 不接触 Secret
[ ] 缓存失效时可以完整重建
[ ] 卸载和恢复步骤已验证

概要

code-review-graph は、自動承認者ではなく AI コードレビューの構造インデックスとして適しています。安定したプロセスは、正しいウェアハウスマップを作成し、増分更新を維持し、MCP を通じて必要最小限のコンテキストを取得し、その後、Git diff を使用して、テストと手動レビューを行って結論を確認することです。

GitHub Actions にアクセスするときは、まずクリーンビルドが再現可能であることを確認してから、徐々にキャッシュとアーティファクトを追加する必要があります。権限は読み取り専用のままで、Fork PR は Secret を使用しません。また、グラフが失敗したときに通常の差分と完全な再構築にフォールバックできることは、単一のベンチマークで最も高い Token の節約を追求するよりも重要です。