culprit

culprit

エージェント主導の開発のための根本原因分析。
コーディングエージェントがバグを持ち込んだ変更を見つけ、コミットする前に自分の修正が完全であることを検証します。

クイックスタート · ツール · 精度 · アーキテクチャ · MCP レジストリ

実際の実行例です。修正では parse_config の呼び出し元のうち1つにパッチを適用し、2つを見落としたため、評価は partial となりました。

エージェントにこれが必要な理由

エージェントは git の履歴を調べて何が壊れたのかを見つけることができ、しかも得意です。しかし、毎回そのために十数回もツールを呼び出したり、変更したばかりのヘルパーにコミット前にほかの呼び出し元が3つあるかどうか確認したりするとは限りません。culprit はこの2つを、エージェントが活用できる構造化 JSON を返す決定論的な1回の呼び出しにまとめます。

エージェントの質問	culprit の回答
「何がこのバグを持ち込んだのか？」	容疑者となるコミットを順位付けし、作者の意図と、そのコミットが含まれたリリースを提示します
「修正は完全か？」	verify_fix：見落とした呼び出し箇所、テストが含まれているか、リスクレベル
「この変更で何が壊れる可能性があるか？」	逆方向のインポート依存先、対象となるテスト、高リスクの共有モジュール

• ⚡️ 即時に実行。 テスト実行も二分探索もありません。エージェントのツール呼び出しを41％削減したというベンチマーク結果があります。
• 🔒 読み取り専用でオフライン。 リポジトリや PR に書き込みません。API キーもネットワークも不要です。
• 🔌 MCP ネイティブ。 標準入出力経由で11個のツールを提供し、公式 MCP レジストリにも登録されています。さらに、1つのコマンドで使えるプラグインもあります。
• 🗣️ 言語に依存しません。 git が動作する場所なら、どこでも容疑者を特定できます。影響範囲の解析では12の言語ファミリーを読み取ります。

実際に機能するのか？

既知の導入コミットが各修正の Fixes: トレーラーから分かる、実際のリグレッション50件を対象にベンチマークを実施しました。内訳は git から25件、systemd から25件です（作者が検証した正解データです）。修正コミットだけを与えると、culprit は削除された行を手がかりに、バグを持ち込んだコミットを順位付けします。

指標	結果
導入コミットが1位	50%（25/50）
導入コミットが上位5件の容疑コミットに含まれる	66%（33/50）

エンジンが一度も見たことのない大規模な C コードベースで、決定論的かつオフラインで動作します。python benchmarks/run.py を実行すると、リポジトリをクローンし、すべてのケースを評価して再現できます。

ただし、エージェントは自分で git blame を実行できます

実行できますし、得意でもあります。ですから、率直に問うべきなのは、culprit が正確かどうかではなく、git を使えて culprit を使わないエージェントに勝るのか、あるいはその助けになるのかです。同じ10件のリグレッションを使い、修正コミットから答えを読み取れないように各条件を分けて実施しました。

	culprit のみ	エージェントのみ	エージェント＋culprit
原因コミットが1位	80%	90%	90%
原因コミットが上位5位以内	90%	100%	100%
到達までの平均ツール呼び出し回数	1	14.9	8.8（-41%）
到達までの平均トークン数	約0	55,534	47,616（-14%）

正確性ではエージェントが勝ち、culprit を使っても精度は上がりません。culprit の効果は、調査ごとに約8,000トークンを節約し、ステップ数をおよそ半分にして結果にたどり着けることです。 ツール呼び出し回数は全10件で減少し、トークン数は10件中7件で減少しました。最も難しいケースでは、エージェントのみの場合は42回のツール呼び出しと124kトークンが必要でしたが、culprit を使うと16回の呼び出しと84kトークンで済みました。

これらの削減量には、culprit の出力を読むコストもすでに含まれており、これは3列目に計上されています。culprit 自体の実行は決定論的な呼び出し1回で、モデルを使わず、1秒もかかりません。

つまり、culprit はエージェントの代わりではなく、より賢い blame ツールでもありません。エージェントを高速化するものです。手法、注意事項（n=10であり、この一部のケースは全50件より簡単です）、再現方法については、benchmarks/agent/ をご覧ください。

クイックスタート

Claude Code プラグイン（MCP サーバーと、エージェントにいつ使うかを指示するスキルをインストールします）：

/plugin marketplace add noordeen123/culprit
/plugin install culprit@culprit

任意の MCP クライアント（Cursor、Windsurf、VS Code、Codex CLI、Zed、Continue、Cline、Amazon Q、Goose）：

{
  "mcpServers": {
    "culprit": {
      "command": "uvx",
      "args": ["--from", "culprit[mcp]", "culprit-mcp"]
    }
  }
}

CLI（エージェントは不要です）：

uvx culprit                     # run from PyPI on demand
rca --verify-fix patch.diff     # exit 0 if complete, 1 otherwise

MCP サーバーには Python 3.10 以降と uv が必要です。CLI は3.9以降で実行できます。

ツール

ツール	わかること
analyze	1回の呼び出しで完全なRCAを実行します：分類、疑わしい箇所または影響範囲、リスク、テストへの影響
verify_fix	この差分は安全にコミットできますか？ complete / partial / risky と、見落とした呼び出し箇所を提示します
find_suspects	バグを引き起こしたコミットを順位付けします
check_completeness	変更されたシンボルのうち、修正で手が加えられていない呼び出し箇所を示します
get_intent	原因コミットのメッセージ、関連するPR、参照されているissueを示します
get_evolution	git log -L を使って、不具合のある行のコミットごとの履歴を示します
get_risk_score	要因を含むQAゲートスコア（0～100、low/medium/high）を示します
get_blast_radius	機能への影響を示します：依存先、対象をカバーするテスト、リスクの高いファイル
get_test_impact	この変更に対して実行する最小限のテストセットを示します
classify_change	根拠とともに、バグ修正か機能追加かを判定します
from_trace	差分やPRなしで、スタックトレースから直接RCAを行います

verify_fix：コミット前のゲート

エージェントはコミット前に、自分の差分に対してこれを実行します。

• verdict：未変更の呼び出し箇所が残っていない場合は complete、見落としがあった場合は partial、リスクが高い場合は risky です。verdict は完全性の軸であり、テストカバレッジは risk_level に反映される別の信頼度の軸です。
• untouched_references：変更されたシンボルを引き続き使っているファイルを正確に示します。エージェントはこのリストを確認して修正します。
• skipped_symbols、adds_test、notes：広く使われすぎて確認対象から除外されたもの、テストが追加されたかどうか、次に行うことを示します。

complete になるまでループしてからコミットします。それがすべてです。

CLI と CI

rca                            # current branch vs the configured base
rca --last                     # the latest commit only
rca --pr 16786                 # a specific PR (uses the PR's own base)
rca --trace crash.txt          # RCA from a stack trace, no fix or PR needed
rca --verify-fix patch.diff    # check a diff before committing
rca --select-tests             # print the tests to run for this change
rca --html report.html --open  # a single self-contained HTML report
rca --pr 16889 --fail-on high  # exit non-zero when QA risk is high
rca serve --repo /path         # local web UI with a base picker

CIゲート：終了コードのみでリスクを判定し、PRコメントも書き込みも行いません。 examples/github-actions/culprit-pr.yml を .github/workflows/ にコピーしてください：

- run: pip install "culprit>=0.3.0"
- env: { GH_TOKEN: "${{ github.token }}" }
  run: rca --pr ${{ github.event.pull_request.number }} --fail-on high

HTML レポート

--html を指定すると、単独で完結するファイルが1つ生成されます。CDNは不要で、オフラインで開けるため、CIにも添付できます。判定から始まり、要因を示すスコア付きのQAリスクと、バグがどれほどの期間潜んでいたかを含む最有力の原因候補が表示されます。

次に、バグがどのように入り込んだかを再構成します。問題のある行に変更を加えたすべてのコミットを、作成から、バグを引き起こしたコミット（赤色で、正確な差分付き）、修正（緑色）まで表示します。

各ノードを展開すると、その差分が表示されます。レポート全体を見る。

git bisect との比較

	git bisect	culprit
入力	信頼できる失敗テスト	修正の差分（またはスタックトレース）
方法	コミットをチェックアウトしてテストを実行	修正の行と git log -L を使って原因を特定
速度	数分（テスト実行回数は約 log2(N) 回）	即時
出力	最初に問題が発生したコミット	原因候補のセット、意図、ライフサイクル、完全性、リスク
確度	証明	強力なヒューリスティック

--bisect "<cmd>" を指定すると、確認用の任意のレイヤーとして実際の bisect を実行します。使い捨ての git worktree 内で実行するため、チェックアウトには一切変更を加えません。最初に失敗したコミットが 原因候補として特定されたコミットと一致すると、レポートに git bisect で確認済み と記されます。

アーキテクチャ

正規化されたコンテキストを入力し、構造化されたJSON結果を出力します。非決定的な処理は、任意のLLMによる説明生成だけです。これはアダプターの背後に隔離されているため、エンジンはAPIキーなしで動作します。

2つのレーンで1つのエンジンを構成します。各モジュールは結果の一部分を出力するため、対象が gh、REST API、ローカルのgit、貼り付けたスタックトレースのいずれから取得されたかを意識する必要はありません。モジュールの全体図： docs/ARCHITECTURE.md。

設定

ベースブランチは、--base フラグ、CULPRIT_BASE、.culprit.toml （base = "origin/main"）、HEAD~1 の順に解決されます。--last を指定すると、最新のコミットを表示します。

PRのタイトルとラベルの取得には、GitHub CLIが利用可能な場合はそれを使用し、そうでない場合は公開リポジトリ向けに認証不要のREST APIを使用します（制限を緩和するには GITHUB_TOKEN または GITLAB_TOKEN を設定してください）。GitHub、GitLab、Bitbucket、Giteaへの詳細リンクに対応しています。影響範囲の解析では、JS/TS、Python、Go、Java/Kotlin、Ruby、C/C++、C#、PHP、Rust、Scala、Swiftのインポートを読み取ります。

コントリビューション

pip install -e ".[dev]" && pytest

モジュールの全体図とデータ構造： docs/ARCHITECTURE.md。MCP サーバーをレジストリに公開する方法： docs/PUBLISHING.md。MITライセンスです。