codebase-comprehension-algorithms

コミュニティにおけるコードベース理解とドメインマッピングのアルゴリズムに関するベストプラクティス

コードベースを理解しやすい機能／ビジネスドメインにマッピングするために有効なアルゴリズムを、実務者向けにまとめたリファレンスです。これらの手法の多くは、ソフトウェアアーキテクチャの復元やソフトウェアリポジトリのマイニングに関する文献で扱われていますが、現場のエンジニアにはほとんど知られていません。しかし、コーディングエージェントが日々求められる「このコードベースは何をしていて、その機能はどこにあるのか？」という問いに答えるには、まさに適した手法です。

47 のルールは、実行ライフサイクルへの影響度に基づいて整理されています。パイプラインの早い段階での誤った判断（どのグラフを構築するか、どの識別子を残すか）は、その後のすべてに影響します。CRITICAL の 3 つのカテゴリ（graph-、clust-、valid-）は、誤った判断を後から挽回できないものです。まず、これらをお読みください。

対象範囲：査読済みの文献または定評ある書籍に基づく実証済みのアルゴリズムです。Newman の Networks、Leskovec-Rajaraman-Ullman の Mining of Massive Datasets、Ganter-Wille の Formal Concept Analysis に加え、ICSE／FSE／TSE／PNAS／JMLR の論文を 40 本以上取り上げています。チュートリアルサイト、Stack Overflow、マーケティング記事は含みません。GNN／CodeBERT／code2vec（まだ「数十年にわたって実証済み」とは言えません）と、リファクタリングのレシピに関する内容（react-refactor や typescript-refactor などの関連スキルで扱います）は、意図的に将来のバージョンに先送りしています。

適用する場面

次のような場合に、これらのルールを使用してください。

• 不慣れなコードベースにエージェントを適応させる場合：「このコードベースがドメインごとに何をしているのか説明してください」
• アーキテクチャマップを作成する場合：「主なサブシステムとその接続関係は何ですか？」
• 機能の実装箇所を特定する場合：「決済／認証／検索を実装しているファイルはどれですか？」
• リファクタリングをレビューする場合：「この変更はアーキテクチャ上の境界を守っていますか？」
• アーキテクチャ上の負債を検出する場合：「予想外に結合しているファイルはどれですか？」
• 既存の分解を検証する場合：「README に記載されたアーキテクチャは、コードと一致していますか？」
• 上記のいずれかに使うアルゴリズムを選ぶ場合 — ユーザーが求めているのは、感覚的な判断ではなく、実証済みの手法です

優先度別のルールカテゴリ

#	カテゴリ	プレフィックス	影響度	内容
1	グラフの構築とエッジの重み付け	graph-	CRITICAL	構築するグラフ、広範なフィルタリング、サイクル処理、マルチレイヤー
2	コミュニティ検出とクラスタリング	clust-	CRITICAL	Leiden、Infomap、SBM、MCL、Walktrap、スペクトラル、HDBSCAN
3	検証と品質指標	valid-	CRITICAL	MoJoFM、ARI／NMI、解像度限界、コンセンサス、変更予測、アブレーション
4	識別子と言語的前処理	lex-	HIGH	Samurai による分割、略語の展開、TF-IDF／BM25、語幹処理、V-O 解析
5	ソフトウェア固有のアーキテクチャ復元	arch-	HIGH	Bunch + MQ、ACDC、Limbo、Reflexion、DSM
6	ソースコードのトピックモデリング	topic-	HIGH	LDA、LSI／SVD、NMF、HDP、一貫性に基づく K の選択
7	進化的結合と共変更のマイニング	evol-	HIGH	Lift／confidence／support、大規模コミットのフィルタリング、時間減衰、論理的結合
8	情報理論的手法	info-	MEDIUM-HIGH	正規化圧縮距離、相互情報量、MDL、コードの自然さ
9	中心性、階層、ラベリング	rank-	MEDIUM	PageRank、HITS、媒介中心性、TextRank／YAKE によるラベル生成

クイックリファレンス

1. グラフ構築とエッジの重み付け（重要）

• graph-filter-omnipresent-utilities-before-clustering — クラスタリング前にロガーと基底クラスを除外します（MoJoFM が 20～40 ポイント向上）
• graph-pick-edge-type-by-question-asked — 呼び出し、インポート、共変更、二部グラフ。問いに応じてグラフを選びます
• graph-collapse-sccs-before-clustering — Tarjan の SCC 凝縮により、循環が明示され、すべてのアルゴリズムが安定します
• graph-weight-edges-by-information-content — エッジに IDF／PMI／Jaccard を適用してノイズを抑制します（MoJoFM が 2～5 倍向上）
• graph-bipartite-file-term-for-joint-structure — DI／動的ディスパッチによって呼び出しグラフが隠れている場合に使用します
• graph-combine-signals-in-multilayer-graphs — 正規化された α 重み付きレイヤーに対する、Mucha 2010 のマルチレイヤーモジュラリティ

2. コミュニティ検出とクラスタリング（重要）

• clust-leiden-not-louvain — Louvain はノードの 5～25% で、互いにつながっていないコミュニティを生成します（Traag 2019）
• clust-infomap-mdl-on-random-walks — ランダムウォークに対する MDL。フローに意味のあるグラフに適した手法です
• clust-stochastic-block-model — ベイズ手法で階層的にクラスタリングし、データから K を学習します。非同類選好構造にも対応します
• clust-mcl-markov-clustering — フローシミュレーションを使用します。バイオインフォマティクスで広く使われ、ノイズに強い手法です
• clust-walktrap-short-random-walks — ランダムウォーク距離と階層的凝集型クラスタリング
• clust-spectral-laplacian-fiedler — ラプラシアンの固有ベクトルを使って、最適な k 分割の正規化カットを実現します
• clust-hdbscan-density-based — グラフではなく、ファイルの埋め込み表現を使ってクラスタリングする場合に使用します

3. 検証と品質指標（重要）

• valid-mojofm-as-software-clustering-distance — SAR におけるゴールドスタンダードの距離指標です（Wen-Tzerpos 2004）
• valid-adjusted-rand-index-and-nmi — 偶然一致を補正した、アルゴリズム間の比較指標です
• valid-be-aware-of-resolution-limit — モジュラリティでは √(2m) より小さいクラスターを検出できません（Fortunato-Barthélemy PNAS 2007）
• valid-consensus-clustering-for-stability — 1 回の実行結果は信頼できません。複数回の実行結果を統合するのが適切です
• valid-cochange-prediction-as-ground-truth-proxy — 時系列データの一部を保留した共変更予測を、存在しない正解データの代わりに使用します
• valid-ablate-each-input-signal — 1 つずつ除外するアブレーションを行い、どの入力が実際に結果を左右しているかを明らかにします

4. 識別子と字句の前処理（高）

• lex-split-identifiers-with-samurai — 素朴なキャメルケース分割の精度60％に対し、87％の精度を達成（Enslen MSR 2009）
• lex-build-programming-language-stop-words — 3層構造：キーワード＋汎用語＋IDF主導
• lex-expand-abbreviations-with-context — usr → user、ctx → context（Lawrie GenTest 2011）
• lex-tf-idf-and-bm25-on-identifiers — 生のカウントは一般的な語に左右されます。TF-IDF／BM25で解決します
• lex-stem-versus-subword-tokenization — クラスタリングにはPorterステマー、埋め込みにはBPE
• lex-extract-verb-object-pattern-from-method-names — getUserById → (verb=get, object=user)。複合概念のシグナル

5. ソフトウェア固有のアーキテクチャ復元（高）

• arch-bunch-with-mq-fitness — MQ適合度関数と探索。コードではQ最大化より優れています
• arch-acdc-subgraph-patterns — サブシステムと骨格のパターン。アーキテクトの直感に合致します
• arch-limbo-information-bottleneck — TishbyのIBをソフトウェアに適用（Andritsos-Tzerpos 2005）
• arch-reflexion-model — 仮説と実際を比較します。Murphy-Notkin 1995による、あまり活用されていない優れた手法です
• arch-dsm-partitioning — 設計構造マトリックス。60年前から使われているエンジニアリング手法

6. ソースコードのトピックモデリング（高）

• topic-lda-on-source-code — 識別子とコメントのテキストから、ファイルごとの確率的なトピック分布を推定します
• topic-lsi-svd-on-term-document — SVDベースの決定論的な意味埋め込み（Maletic-Marcus 2001）
• topic-nmf-non-negative-factorization — 要素ベースの加算型トピック。完全に再現可能です
• topic-hdp-for-nonparametric-topic-count — 階層的ディリクレ過程。データからKを学習します
• topic-pick-topic-count-by-coherence-not-perplexity — パープレキシティは、人間によるトピック品質評価と負の相関があります

7. 進化的結合と変更の共起マイニング（高）

• evol-mine-cochange-with-lift-and-confidence — リフトが2を超えることが基準です。生の共変更カウントはノイズです
• evol-filter-large-commits — 200ファイルのコミットでは、誤ったペアカウントが2万件発生します。積極的にフィルタリングしてください
• evol-temporal-decay-on-edge-weights — 半減期を6か月とする指数減衰
• evol-logical-coupling-as-architectural-signal — 最も強い結合の30～50％は静的解析では検出できません（Gall 1998）

8. 情報理論的手法（中～高）

• info-normalized-compression-distance — 特徴量エンジニアリングなしでクラスタリング。gzipベースの汎用類似度
• info-mutual-information-as-coupling — リフトでは検出できない非線形／条件付き結合を検出します
• info-mdl-for-model-selection — 原理に基づくKの選択。コード長としてのオッカムの剃刀
• info-naturalness-of-code-as-quality-signal — Hindle 2012 — コードは英語より30～50％予測しやすく、バグがあるとエントロピーが急増します

9. 中心性、階層、ラベリング（中級）

• rank-pagerank-for-module-importance — 依存関係グラフを反転させて PageRank を適用し、アーキテクチャの中核を特定します
• rank-hits-hubs-and-authorities — オーケストレーターと実装を区別します（Kleinberg 1999）
• rank-betweenness-centrality-for-bottlenecks — ドメイン間の橋渡しを特定し、ゴッドクラスを検出します
• rank-textrank-for-cluster-labels — 複数語のキーフレーズをクラスタラベルとして使います（Mihalcea-Tarau 2004、YAKE 2020）

使用方法

まず、エージェントが答えようとしている問いから始めます。

• 「このコードベースの主なドメインは何ですか？」 → graph-（グラフを選択）→ clust-（Leiden / Infomap / SBM）→ topic-（ラベルを付与）→ valid-（安定性を確認し、アブレーションを実施）
• 「機能 X を実装しているファイルはどれですか？」 → テーマの位置を特定するには topic-lda-on-source-code、X のファイルをシードとしてパーソナライズド PageRank を実行するには rank-pagerank-for-module-importance
• 「アーキテクチャの中核はどこですか？」 → 依存関係グラフに対して rank-pagerank-for-module-importance と rank-hits-hubs-and-authorities を使用します
• 「README に記載されたアーキテクチャはコードと一致していますか？」 → この用途に特化して設計されているのが arch-reflexion-model です
• 「（静的な依存関係だけでなく）実際の結合度はどの程度ですか？」 → evol-logical-coupling-as-architectural-signal と evol-mine-cochange-with-lift-and-confidence
• 「特徴量を設計せずにクラスタリングするにはどうすればよいですか？」 → info-normalized-compression-distance
• 「クラスタはどの程度の大きさが適切ですか？」 → valid-be-aware-of-resolution-limit と topic-hdp-for-nonparametric-topic-count
• 「分解が適切かどうかを判断するにはどうすればよいですか？」 → valid- カテゴリー全体を使用します。複数の代理指標による評価は必須です

このスキルの基本的な考え方は、まず適切なグラフを構築すること（どこにでも現れるファイルは除外します）、グラフと問いに合ったアルゴリズムを選ぶこと、語彙的なシグナルが重要な場合はコードに特化した前処理パイプライン（Samurai + ストップワード + ステミング + TF-IDF）を使用すること、そして必ず検証することです。専門家による正解データがある場合は MoJoFM を、ない場合はコンセンサス + 変更共起予測 + アブレーションを使用します。

コード例が Python で書かれているのは、参照実装（networkx、igraph、leidenalg、scikit-learn、gensim、graph-tool、hdbscan）がすべて Python で利用できるためです。ここでの考え方は、どの言語にも応用できます。

参照ファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンと参照情報
AGENTS.md	自動生成された目次ナビゲーション

関連スキル

• computer-science-algorithms — アルゴリズムとデータ構造のリファレンス（このスキルでは MinHash/LSH、Aho-Corasick などについて相互参照しています）
• complexity-optimizer — ここで特定するホットパスの静的解析
• design-to-react-algorithms — デザインからコードへの構造復元を支援するスキル