動的なシステムプログラミングフルグラフ対応

MaguyvaのPython対応: AIによるコード検索とリファクタリング

MaguyvaはAST解析とシンボル抽出によりPythonに対応しており、AIエージェントが実際のPythonリポジトリにおいてデコレータ、self/clsメソッド、インポート、モジュール横断の依存関係をたどるのを助けます。

Pythonのリポジトリが浅いAIツールを破綻させやすい理由

Pythonは、多くのAIコーディングツールが最初は良さそうに見えて、やがて本番環境で当てずっぽうを始める場所です。難しい部分はおなじみのものです。デコレータの付いたエントリポイント、サービスクラス、型スタブ、至るところにある小さなヘルパーモジュール、そしてselfやclsを所属するクラスに結び直して初めて意味をなすメソッドなどです。

Pythonにとって本当の問いは「.pyファイルを読めるか」ではありません。問いは、エンドポイントからサービスへ、バックグラウンドタスクからヘルパーへ、あるいはクラス名から実際に挙動を実装しているメソッドへと移動する間、エージェントが根拠を保ち続けられるかどうかです。

MaguyvaがPythonで実際に抽出するもの

Maguyvaは、Pythonを完全な構造的言語として扱います。この設定は.py、.pyw、.pyiをカバーし、decorated_definitionを関数シンボルに対応付け、self / clsのメソッド呼び出しを囲むクラスに紐づけます。これが重要なのは、まさにそこがPythonのリポジトリが人間にとっては自明で、LLMにとっては曖昧に感じられ始める場所だからです。

また、標準ライブラリのノイズの多くを関係抽出からフィルタリングします。つまり、pathlib、typing、loggingのようなモジュールからの一般的なランタイム呼び出しが、本当に気にすべきリポジトリ固有の関係性を埋もれさせにくくなります。

Pythonのリポジトリに役立つMCPワークフロー

最もシンプルで役立つワークフローは、次のとおりです。

「請求書同期まわりのリトライロジック」や「課金エンドポイントにおける権限チェック」のような挙動に関する疑問にはintelligent_searchから始める。
気になるクラス名や関数名が分かったらfind_symbolに切り替える。
共有サービス、ヘルパー、基底クラスをリファクタリングする前に、incomingトラバーサルでdependency_searchを使う。

このパターンは、コールドスタートの状態でエージェントに「課金フローを更新して」と頼むよりも優れています。エージェントがまず地図を作り、その後でコードを変更できるようになるからです。

このページが役立つ場面

このページは、サービスコード、ジョブ、スクリプト、生成された型、周辺の設定など、すでにある程度の年月と複雑さを抱えたPythonリポジトリのためのものです。主な比較対象がポリグロットなWebモノレポ全般であれば、TypeScriptガイドも読んでみてください。対応マトリクス全体だけが必要な場合は、互換性をご覧ください。

最適な用途

>アプリケーションコードと運用スクリプトが同居する、FastAPI、Django、データプラットフォーム、社内ツールのリポジトリ。
>すでにデコレータ、バックグラウンドジョブ、そして多くの暗黙的な配線を抱えた、息の長いPythonサービスをリファクタリングするチーム。
>ハンドラー、サービス、モデル、ヘルパーを変更する前に、grep以上のものを必要とするエージェントワークフロー。

エージェントワークフロー

>編集する前に、エンドポイント、タスク、CLIコマンドをヘルパーや共有モジュールを通じてたどる。
>サービス、クラス、ユーティリティ関数がリポジトリ全体のどこでインスタンス化・再利用されているかを見つける。
>エージェントが最も近い文字列一致ではなく正しい抽象化を編集するように、隣接する実装同士を比較する。

エンジンの詳細

>デコレータが付いた定義も関数として扱われるため、デコレートされたビューやタスクもシンボルとして検索可能です。
>`self` や `cls` によるメソッド呼び出しは、それを含むクラスに紐づけて解決されるため、クラス中心のサービスコードでもグラフが実用的な状態を保てます。
>import・呼び出し・シンボルの正規化は有効になっている一方、`pathlib.*`、`typing.*`、`logging.*` など一般的な標準ライブラリのノイズは関係性から除外されます。

役立つMCPエントリーポイント

intelligent_search
「invoice syncまわりのリトライロジック」のような概念的なクエリから始め、リポジトリがポリグロットであれば `language_filter="python"` を設定してください。
find_symbol
クラス名や関数名が分かっていて、編集前に定義と参照の両方が必要なときに使用してください。
dependency_search
共有サービスやヘルパーをリファクタリングする前に、incoming方向を使って何がそれに依存しているかを確認してください。