命名からドメイン用語集を生成する(JIG Glossary の言語非依存化)

調査時点: 2026-06。公開ツール code-glossary の背景にある整理。

JIG は、Java のコードを解析して設計を可視化する OSS ツール。その Glossary 機能は、コードの識別子とコメントから業務用語を一覧化する。詳細は JIG。

JIG の 3 層分解#

層	JIG での担当	TypeScript / Python / Go の既存ツール
形式品質(メトリクス閾値)	IDE インスペクションと併用	ESLint の max-* 系、ruff、各種 linter
依存可視化・アーキテクチャ適合	PackageRelation(相互参照の赤線)	dependency-cruiser、eslint-plugin-boundaries、ArchUnitTS、tach(Python)、go-arch-lint
ドメイン知識の可視化(命名 → 用語集)	Glossary	空白

JIG の要素をさらに細かく分けると、TypeScript では識別子抽出(ts-morph)、ドキュメントコメント(TSDoc)、依存図(dependency-cruiser)、境界ルール、未使用検出(Knip)は成熟しており、UML 生成や API 一覧は部分的に存在する。「ドメイン用語集のキュレーション」「ユースケース一覧」「実用品質の call graph」が空白として残る(要素ごとの対応表は JIG の「要素分解と TypeScript での対応ツール」)。

JIG Glossary がやっていないこと#

JIG の Glossary は識別子と Javadoc の 1 文目をソートして列挙するだけで、概念を束ねない。delete / remove / trash が同じ操作を指していても、3 つの用語として並ぶ。揺れの検出と補正は、規律ある命名と Javadoc に委ねられている。

したがって「命名の揺れを概念で束ねる」機能は JIG を超える部分で、ここを LLM の概念判定で埋めると言語に依存しない形になる。

先行研究から分かる設計上の制約#

前処理(識別子の分割・略語展開)は枯れた既存手法(Spiral / Ronin、TRIS)に乗せられる。自作で価値が出るのは「概念の束ね」「文脈付きの LLM 判断」「根拠(evidence)付きの出力」に絞られる
概念クラスタリングを直接評価する標準ベンチマークは存在しない。精度検証は自前の oracle が要る
文脈なしの LLM 単体は特化ツールに負ける(略語展開で ChatGPT は tfExpander 比で Precision / Recall とも約 28 ポイント低い)。ソースの文脈を注入することが前提
embedding は「同義」と「関連」を混同する(IdBench)。「顧客 ↔ acct」(同義)だけが欲しいのに「顧客 ↔ 注文」(関連)まで拾う
実コードの命名はほとんど一貫している(ReName4J)。揺れは少数なので、KPI は recall より precision を優先する

同義と関連の区別(典型例)#

筋トレ記録アプリの TypeScript コードを対象にした素振りで、次の両方が実在した。

正例(揺れ): 「削除」概念が handleDelete / handleRemoveDraft / handleTrashClick の 3 語に割れている
負例(別概念): 手入力の体組成値 BodyMetric と機器から取り込む InbodyMeasurement。似た語だが別概念で、束ねてはいけない

この負例が embedding やゆるい LLM 判定で誤って束ねられるのが最大のリスクになる。

holistic より pairwise#

小さな LLM(temperature 0)で 2 セット × 3 回のコールド実行を比べた結果。

「全識別子を一度にグループ分けさせる」holistic 方式は粒度が実行ごとに揺れる(グループ総数 5 / 9 / 6、特定の識別子が所属を行き来する)
「この 2 語は同じ概念か」を問う pairwise 方式に変えると、負例の分離 3/3、正例の検出 3/3、不安定なペアは低 confidence 帯に限局した
same かつ confidence >= 0.8 を揺れ(drift)の条件にすると、不安定なペアは閾値で落ち、安定した正例だけが残る。confidence 閾値がそのまま再現性の安定化装置になる

設計の骨格#

識別子と型・ドキュメントコメントを抽出する(TypeScript なら ts-morph)
camel / snake で識別子を分割する
blocking: 安価な語彙前フィルタで候補ペアを生成し、O(n²) の LLM 呼び出しを避ける
pairwise の LLM 判定で {same, confidence} を得て、ペア単位でキャッシュする
same かつ confidence >= 0.8 のペアを union-find で連結し、複数の表層名を持つ概念に drift_flag=true を付ける
出力は用語集(JSON)と drift だけを載せたレポート。主役はフル用語集ではなく、違和感リストの方

束ねは保守的に行い、暫定的な束ねと drift 判定を非対称に扱う(束ね損ねより誤って束ねる方が害が大きい)。LLM の概念判定は Claude Code のようなコーディングエージェントが元から持つ能力なので、まずスキルとして実装し、決定的な部分(用語集の列挙・依存図)は後から CLI に切り出すという分担が成り立つ。

更新履歴#

2026-06-19: 初版（ローカル調査ノート）
2026-10-17: Wiki へ移植、概念ページとして再構成。冒頭に定義を追加