コンテンツにスキップ

コード設計品質の定量化フレームワーク + 指標カタログ — AIコーディング評価とプロジェクトへの導入

作成日: 2026-06-09 きっかけ: AIコーディングの設計品質をどう定量化するかの調査をまとめ、自分の Claude Code 運用に落とすため 関連: context_engineering_ast活用、llm_product_clean_architecture_設計、ai_agent_9社_本番運用アーキテクチャ

TL;DR

AIコーディングの「良し悪し」は単一指標では測れない。McCabe循環的複雑度・Halstead・結合度凝集度（コンセンサス強）を土台に、Cognitive Complexity・Maintainability Index（中）、ネットワーク科学指標（propagation cost、modularity Q、中心性）を加え、最後にDORA/SPACEと経時churn測定（新興）で束ねる三層構成（点→構造→プロセス）が最適解。これらのコア指標はすべて言語非依存で、変わるのは抽出ツールだけ。

実証データは一貫して「AIは速度を上げるが設計品質を下げる」方向を示す。GitClearは2020→2024でコピペ行8.3%→12.3%・リファクタ（moved）行24.1%→9.5%・5行以上の重複ブロック8倍増、CMU（He et al. 2025, MSR'26採択）はCursor導入後に静的解析警告+30%・複雑度+41%が持続的に増加、Google 2024 DORAはAI採用25%増ごとにデリバリ安定性-7.2%。

言語横断で使える土台は lizard（複雑度、20言語以上）/ SonarQube・SonarCloud（認知的複雑度・債務・重複、30言語以上）/ tree-sitter（AST、多言語文法）/ CodeQL（依存・データフロー、主要言語）→ NetworkX・igraph（ネットワーク解析）。これらをCIに組み込み、PR単位で複雑度デルタとコピペ率を、週次でグラフ指標を経時追跡するのが現実解。結合度はOO言語ならCBO/LCOM、手続き型ならfan-in/fan-out を使う。

Key Findings

1. 「測定容易性」と「学会コンセンサス」は別軸であり、両方が高い指標を土台にすべき

  • コンセンサス強・測定容易: McCabe循環的複雑度、Halstead、LOC、結合度/凝集度（fan-in/out、CBO/LCOM）、Martinの不安定度/抽象度。いずれも1976–1994年の査読論文が起点で、無料OSSツールが多数存在。
  • コンセンサス中・測定容易: Cognitive Complexity（2018、SonarSource）、Maintainability Index（1992、ただし式の妥当性に批判あり）。
  • コンセンサス成長中・測定中程度: ネットワーク科学指標（propagation cost、modularity Q、中心性）。学術的裏付けは強いが、ツールが自作前提で測定の手間が大きい。
  • 新興・要注意: AI生成コード固有のchurn/重複指標（GitClear等）。実務的示唆は大きいが、ベンダー研究中心で独立再現が途上。CMU研究が独立検証として最も価値が高い。

2. AI生成コード品質の実証研究は2023–2025で急増し、結論は概ね一致

「機能的正しさ（SWE-bench等）は向上するが、保守性・重複・複雑度・結合は悪化する」。設計品質指標とベンチマークは補完関係にある（前者=「保守できるか」、後者=「動くか」）。

3. コア指標は言語非依存、変わるのは抽出層だけ

McCabe・Halstead・Cognitive Complexity・結合度凝集度・ネットワーク指標・churn は、いずれも「制御フロー」「依存グラフ」「コミット履歴」という言語横断の構造に対して定義される。言語が変わると変わるのは (a) AST/コールグラフをどのツールで抽出するか、(b) 結合度をクラス単位（OO）で測るか関数/モジュール単位（手続き型）で測るか、の2点に集約される。

統合評価フレームワーク（3層 + 時間軸）

設計品質を「点（関数/ファイル）」「構造（グラフ）」「プロセス（時間）」の3層で捉え、AIコーディングの評価ではこれらの経時変化（デルタ）を主指標にする。

層 起点 対象 主な指標 問い
第1層 ローカル複雑度 AST 関数・ファイル単位 McCabe、Halstead、Cognitive Complexity、MI、nesting depth、AST node count AIが書いた個々の関数は読めるか/テスト可能か
第2層 構造的結合 ネットワーク科学 モジュール依存グラフ/コールグラフ 結合度凝集度、Martin指標、propagation cost、modularity Q、中心性、循環依存（SCC） AIの変更がアーキテクチャを侵食していないか
第3層 プロセス/債務 統合フレームワーク チーム・時間 SQALE技術的負債、DORA、SPACE、code churn、co-change結合、重複率 チーム全体の速度と安定性、長期保守コスト

AIコーディング評価の中核原則（実証研究の含意）: AIは第3層の速度指標（commits, lines added）を短期的に押し上げるが、第1層（複雑度）と第2層（結合）を悪化させ、それが回り回って第3層の安定性（change failure rate）を下げる。CMU研究のパネルGMM分析は「蓄積した技術的負債が将来の速度を下げる自己強化的悪循環」を実証した。したがって速度指標だけを見ると必ず誤判断する。速度と品質デルタを常にペアで監視するのがこのフレームワークの設計思想である。

指標カタログ

カテゴリA: AST（抽象構文木）ベース

A1. McCabe循環的複雑度（Cyclomatic Complexity） — コンセンサス: 強 / 測定容易性: 高

  • 定義: 制御フローグラフ上の線形独立パス数。直感的には「分岐の数+1」。
  • 計算式: M = E − N + 2P（E=辺、N=節点、P=連結成分）。実務的には判定点（if, for, while, case, &&, ||, ?）の数+1。
  • ツール: lizard（20言語以上: C/C++/C#/Java/JS/TS/Python/Go/Rust/Swift/Objective-C/PHP/Ruby/Scala/Lua等、ヘッダ不要、デフォルト閾値CCN=15、--csv/--xml/checkstyle出力）、Radon（Python）、ESLint complexity（JS/TS）、gocyclo（Go）、PMD（Java）、SonarQube/SonarCloud、OCLint（閾値10）。
  • 閾値: McCabe原論文は10を上限の目安。SonarSourceは言語ごとに調整（C/C++/Objective-Cは25をデフォルト）。10超で中リスク、20超で高リスク、50超でテスト困難という経験則。
  • 出典: T.J. McCabe, "A Complexity Measure," IEEE TSE, SE-2(4), pp.308–320, 1976.
  • AI評価への意義/限界: 関数単位のテスト必要数の下限を示す（分岐網羅）。ただし「見た目の複雑さ」であり、ネストの深さや認知負荷は捉えない。switch文を過大評価する弱点。

A2. Halstead複雑度 — コンセンサス: 強 / 測定容易性: 高

  • 定義: 演算子・オペランドの語彙統計から、Volume（規模）、Difficulty（難度）、Effort（労力）を算出。
  • 計算式: n1=異なる演算子数, n2=異なるオペランド数, N1/N2=総出現数。Vocabulary n=n1+n2、Length N=N1+N2、Volume V=N×log₂(n)、Difficulty D=(n1/2)×(N2/n2)、Effort E=D×V。
  • ツール: lizard（token count）、Radon（Python）、Multimetric（多言語）。
  • 出典: M.H. Halstead, "Elements of Software Science," Elsevier, 1977.
  • AI評価への意義/限界: MIの構成要素として有用。単独では古く、現代的な妥当性検証は限定的。

A3. Cognitive Complexity — コンセンサス: 中 / 測定容易性: 高

  • 定義: 「コードの理解しにくさ」を測る。McCabeが等価に扱う構造を、人間の読みやすさ基準で重み付け。
  • 計算方法: 3規則 — (1) 短縮構文（null合体等）は加算しない、(2) 線形フローのbreak（ループ/条件/catch/goto等）ごとに+1、(3) ネストするごとにペナルティを加算（深い入れ子を重く）。
  • ツール: SonarQube/SonarCloud、ESLint（JS、デフォルト閾値20）、lizard拡張。
  • 閾値: SonarSourceは多くの言語で関数あたり15をデフォルト。
  • 出典: G. Ann Campbell, "Cognitive Complexity," SonarSource SA, 2018（TechDebt 2018で発表）。実証検証: Muñoz Barón et al., "An Empirical Validation of Cognitive Complexity..." (arXiv:2007.12520)。
  • AI評価への意義/限界: AI生成コードの「読みにくさ（過度に簡潔、不自然なネスト）」を捉えるのに適する。McCabeほどの歴史的検証はない。

A4. AST編集距離 / tree edit distance とコードクローン検出 — コンセンサス: 強（アルゴリズム）/ 中（品質指標）/ 測定容易性: 中

  • 定義: 2つのASTを変換する最小編集操作数。コードクローン（Type-1〜3）検出に利用。
  • 計算方法: Zhang-Shasha動的計画法。正規化類似度 = 1 − TED/max(|T1|,|T2|)。大規模にはDECKARD（部分木を特徴ベクトル化しLSHでクラスタリング）。
  • ツール: zss（Python）、APTED、DECKARD、tree-sitter+独自実装。汎用クローン検出: PMD-CPD（多言語）、NiCad、CCFinderX、SonarQube duplication、lizard duplicate。
  • 出典: K. Zhang & D. Shasha, SIAM J. Computing 18(6), 1989。DECKARD: Jiang et al., ICSE 2007。
  • AI評価への意義/限界: AIが増やす「コピペクローン」の定量化に直結（D2参照）。計算コストが高く、Type-4（意味的）クローンは捉えにくい。

A5. 構造指標（AST node count, AST depth, nesting depth） — コンセンサス: 中 / 測定容易性: 高

  • 定義: AST節点数（規模）、AST深さ・ネスト深さ（構造的複雑さ）。
  • ツール: tree-sitter（多言語文法、ビルド不要で高速）、各言語ネイティブAST（Python ast、TS compiler API、libclang等）、lizard（nesting）。
  • AI評価への意義/限界: 軽量で言語非依存に近く、CIで安価に経時追跡可能。単独の品質判定力は弱く、補助指標。

A6. Maintainability Index (MI) — コンセンサス: 中 / 測定容易性: 高

  • 定義: Halstead Volume、循環的複雑度、LOC（、コメント率）を合成した単一保守性スコア。
  • 計算式（Microsoft/VS版、2011年に0–100へ再スケール）: MI = MAX(0, (171 − 5.2×ln(HV) − 0.23×CC − 16.2×ln(LOC)) × 100/171)。元式（Oman-Hagemeister 1992）はコメント率項を含む。
  • ツール: Visual Studio（2007〜）、NDepend（.NET）、Radon（Python）。
  • 閾値: VSでは0–9=低、10–19=中、20–100=高。
  • 出典: Oman & Hagemeister, ICSM 1992。精緻化: Coleman, Ash, Lowther, Oman, IEEE Computer 27(8), 1994。
  • AI評価への意義/限界: 単一スコアで経営層に説明しやすい。一方、式の定数の妥当性に学術的批判が強い（van Deursen、CQSE/Teamscaleが「使わない」と公言）。トレンド監視に留めるのが安全。

A7. code churn と AST diff — コンセンサス: 中（churn全般）/ 新興（AI文脈）/ 測定容易性: 高

  • 定義: churn = 短期間（例: 2週間以内）に書き換え/取り消しされたコード行の割合。AST diff churnは構文木レベルの変更量。
  • ツール: git log解析（言語非依存）、GitClear、CodeScene、git-of-theseus。AST diffにはGumTree（多言語、tree-sitter/srcML連携）。
  • AI評価への意義/限界: 「すぐ直すコード=低品質コード」の代理指標。AIコーディング評価の中核（D2参照）。行ベースchurnはノイズが多く、AST/意味ベースが望ましい。

カテゴリB: ネットワーク科学・グラフ理論ベース

B1. 結合度・凝集度（CBO, LCOM, Ca/Ce, Fan-in/Fan-out） — コンセンサス: 強 / 測定容易性: 中

  • 定義: CBO=あるクラスが結合する他クラス数。LCOM=属性を共有しないメソッドペア数 − 共有するペア数。Ca（求心結合）=自分に依存する外部数、Ce（遠心結合）=自分が依存する外部数。手続き型ではfan-in/fan-out。
  • 計算式: LCOM(1994)= |共有しないペア| − |共有するペア|。Henry-Kafura: IF4 = (fan-in × fan-out)²。Instability I = Ce/(Ca+Ce)。
  • ツール（言語依存が最も強い層）: OO — ckjm/ck（Java）、Understand（商用）、NDepend（.NET）、CCCC（C++/Java）。手続き型/多言語 — fan-in/out はコールグラフから言語非依存に導出。
  • 出典: Chidamber & Kemerer, IEEE TSE 20(6), 1994。実証: Basili, Briand & Melo, IEEE TSE 22(10), 1996（CBOが欠陥傾向の有意な予測因子）。Gyimóthy, Ferenc & Siket, IEEE TSE 31(10), 2005（Mozilla C++、CBOが最良の予測力）。
  • AI評価への意義/限界: 結合の増加はAIによるアーキテクチャ侵食の兆候。CBO/LCOM/DIT/NOCはクラスレベルのOO指標。手続き型では fan-in/fan-out・モジュール間依存数・グローバル状態共有で代替（fan-outがCBOの手続き的対応物）。

B2. Martinのパッケージ指標（不安定度I, 抽象度A, 主系列からの距離D） — コンセンサス: 強 / 測定容易性: 中

  • 定義: I=Ce/(Ca+Ce)（0=安定, 1=不安定）。A=抽象型/全型。D=|A+I−1|。
  • 解釈: 「苦痛ゾーン」（I,A共に低=硬直で変更困難）と「無用ゾーン」（共に高）を回避。Dは0に近いほど良い。
  • ツール: NDepend、JDepend/PHP_Depend系、Sonargraph（多言語）、import-linter（Python）。
  • 出典: Robert C. Martin, "OO Design Quality Metrics," 1994。
  • AI評価への意義/限界: モジュール/パッケージ境界設計の健全性を可視化。抽象度の薄い言語ではIと依存方向（循環の有無）に焦点。

B3. グラフ中心性（betweenness, PageRank, degree） — コンセンサス: 強（NW科学）/ 成長中（SE応用）/ 測定容易性: 中

  • 定義: betweenness=最短経路がその節点を通る割合（ボトルネック/ブリッジ性）。PageRank=重要な節点から参照される節点ほど重要。degree=直接の被参照/参照数。
  • 計算方法: コールグラフ/依存グラフを抽出し、NetworkX/igraph/graph-tool/NetworKitで計算。PageRank減衰d=0.85、betweennessはBrandes（O(VE)）。
  • 出典: Newman, SIAM Review 45(2), 2003。SE応用: Hibernateコールグラフ研究（arXiv:1706.09859）、Breakpoint（arXiv:2506.00172、複雑度×中心性とAI修正成功率の相関）。
  • AI評価への意義/限界: 高中心性の関数はAIに触らせる際の影響範囲が大きい → harnessでの保護対象・人間レビュー必須対象の特定に有用。単独では「良し悪し」を語れない。

B4. ソフトウェアネットワークのスケールフリー性・べき則 — コンセンサス: 中 / 測定容易性: 中

  • 定義: 依存グラフの次数分布がべき則 P(k)∼k^(−γ)（γ≈2–3）に従う傾向。少数のハブ（スケールフリー、スモールワールド）。
  • 出典: Myers, Phys. Rev. E 68, 046116, 2003。Valverde, Ferrer-Cancho & Solé, EPL 60(4), 2002。Potanin et al., CACM 48(5), 2005。
  • 注意: 後続研究（Springer Computing 2017等）は「高結合クラスはべき則で正確にはモデル化できない」と部分的反証。現象の記述であって品質指標ではない。AI評価では「ハブの異常な肥大化」の検知に補助的に使える程度。

B5. モジュラリティ（Newman modularity Q）とコミュニティ検出 — コンセンサス: 強（NW科学）/ 成長中（SE応用）/ 測定容易性: 中

  • 定義: Q = グラフのコミュニティ内辺密度がランダム期待値をどれだけ上回るか。Q∈[−0.5, 1)、0.3–0.7で良好なクラスタ構造。
  • 計算式: Q = (1/2m)Σ_ij(A_ij − d_i·d_j/2m)δ(c_i,c_j)。Louvain/Girvan-Newman/greedy modularityを適用し実モジュール構造と比較。
  • 出典: Newman & Girvan, Phys. Rev. E 69, 026113, 2004。Newman, PNAS 103, 2006。
  • AI評価への意義/限界: 「アーキテクチャ上のモジュール境界」と「実依存の自然なクラスタ」の乖離を定量化。AIによる無秩序な依存追加でQが低下すれば設計侵食の兆候。
  • 批判: 解像度限界（resolution limit）等の既知の批判あり。複数解像度で交差検証。

B6. 循環依存（circular dependency, Tarjan SCC, Feedback Arc Set） — コンセンサス: 強 / 測定容易性: 中（最も自動化しやすいグラフ指標の一つ）

  • 定義: 有向依存グラフ中の強連結成分（SCC）でサイズ>1のもの=循環依存。FASは循環を断つ最小辺集合。
  • 計算方法: Tarjanの強連結成分アルゴリズム（O(V+E)）。サイズ>1のSCCを列挙。
  • ツール: Sonargraph（多言語）、SonarQube（Architecture→Dependency Cycles）、madge（JS/TS）、import-linter（Python）、Classycle（Java）、NDepend（.NET）。汎用には依存グラフ抽出→NetworkX strongly_connected_components。
  • 出典: Tarjan, SIAM J. Computing 1(2), 1972。
  • AI評価への意義/限界: 循環依存数・最大SCCサイズはアーキテクチャ健全性の明快な指標。CIで「新規循環の混入」をブロックするゲートに最適。

B7. Propagation Cost / Architectural Complexity (DSM) — コンセンサス: 強（SE研究）/ 測定容易性: 中

  • 定義: Propagation Cost = 依存行列の推移閉包（Visibility Matrix）の密度。ある変更が平均してシステムの何%に波及しうるか。MacCormack/Baldwin/Rusnakのcore-periphery分析。
  • 計算方法: Design Structure Matrix（DSM）を構築→推移閉包（行列累乗 D^(N-1)）→密度。
  • ツール: 専用研究ツール（dsmsuite等）、Understandの依存DSM、Lattix、NetworkXで推移閉包を自作。
  • 出典: MacCormack, Rusnak & Baldwin, Management Science 2006。実証: Sturtevant博士論文（MIT 2013）— アーキテクチャ複雑度が生産性50%減・欠陥密度3倍・離職率桁違い増と相関。Lagerström, Baldwin, MacCormack & Aier, 2014。
  • AI評価への意義/限界: システム全体の結合度を1スカラーで表す強力な指標。AIによる結合増を経時で捉えられる。依存抽出が前提。

B8. Temporal/Evolutionary Coupling（co-change, logical coupling） — コンセンサス: 強 / 測定容易性: 中

  • 定義: 構文的依存がなくても「一緒に変更される」ファイル/関数の組。隠れた結合を履歴から検出。言語非依存（git履歴のみ）。
  • 計算方法: コミット履歴からco-change頻度→association rule mining（support, confidence）。
  • ツール: CodeScene（商用、最も実用的）、Evolution Radar、git履歴+自作（ROSE/TARMAQ系）。
  • 出典: Gall, Hajek & Jazayeri, ICSM 1998。Zimmermann, Zeller, Weissgerber & Diehl, IEEE TSE 31(6), 2005。Kirbas et al., JSEP 2017。
  • AI評価への意義/限界: AIが作る「コピペで散在し一緒に直す羽目になるコード」を捉える。Mo et al. の co-changeクローンの57.1%がバグに関与 という報告と整合。言語非依存に使えるのが強み。

カテゴリC: 統合的・実務的フレームワーク

C1. DORA metrics（4 keys） — コンセンサス: 強 / 測定容易性: 高

  • 定義: Deployment Frequency、Lead Time for Changes、Change Failure Rate、MTTR。2024年版はrework rateを安定性指標に追加。
  • 出典: Forsgren, Humble & Kim, "Accelerate," 2018。DORA/Google年次State of DevOps Report。
  • AI関連の実証: Google 2024 DORA（約39,000人）— AI採用25%増ごとに「スループット約1.5%減、安定性約7.2%減」、コード品質+3.4%・ドキュメント品質+7.5%。39.2%がAI生成コードを「ほとんど/全く信頼しない」。原因は「AIがバッチサイズを増やすこと」と分析。
  • AI評価への意義/限界: チームレベルの成果指標。設計品質の直接測定ではないが、設計劣化の下流影響（安定性低下）を捉える。個人/コード単位には使えない。

C2. SPACE framework — コンセンサス: 中〜強 / 測定容易性: 中（主観指標含む）

  • 定義: 5次元 — Satisfaction & well-being、Performance、Activity、Communication & collaboration、Efficiency & flow。「生産性は単一指標に還元できない」が中心命題。
  • 出典: Forsgren, Storey, Maddila, Zimmermann, Houck, Butler, ACM Queue 19(1), 2021。
  • AI評価への意義/限界: AIの生産性影響を多面的に評価。設計品質指標（第1・2層）をPerformance次元のアウトカムとして組み込むのが筋。

C3. Technical Debt定量化（SQALE / SonarQube） — コンセンサス: 中〜強 / 測定容易性: 高

  • 定義: SQALE法。Technical Debt（SQALE Index）= 全保守性問題の修正所要時間の和。TDR = 修正コスト /(1行あたり開発コスト × LOC)。
  • 閾値: SonarQube既定のRating: A=0–0.05、B=0.06–0.10、C=0.11–0.20、D=0.21–0.50、E=0.51–1。1行開発コスト既定=30分。
  • 出典: Letouzey, "The SQALE method," 2012（ISO 25000準拠）。原概念: Cunningham 1992。
  • AI評価への意義/限界: 静的解析で見える「コード債務」を時間/金額換算。再現性が高い反面、静的解析が見える範囲しか捉えない（アーキテクチャ債務は第2層で別途測定）。

C4. ISO/IEC 25010 品質モデル — コンセンサス: 強（国際標準）/ 測定容易性: 低

  • 定義: 製品品質を8特性（2023年版）に分類: 機能適合性、性能効率性、互換性、相互作用性、信頼性、セキュリティ、保守性、移植性。保守性の下位=モジュール性、再利用性、解析性、修正性、試験性。
  • 出典: ISO/IEC 25010:2011（2023改訂）、SQuaREシリーズ。
  • AI評価への意義/限界: 上位の概念枠組み。具体指標（McCabe→試験性、CBO/fan-out→モジュール性）を各特性にマッピングする「屋根」。

C5. defect density / code review との相関 — コンセンサス: 強 / 測定容易性: 高

  • 定義: defect density = 欠陥数/KLOC。複雑度・結合との相関が古典的に研究。
  • AI評価への意義/限界: 複雑度・結合指標の「予測的妥当性」の根拠。Basili 1996、Gyimóthy 2005（B1参照）。

カテゴリD: AIコーディング特有の評価観点（2023–2025）

D1. AI生成コードを古典指標で測った実証研究

  • Idrisov & Schlippe (2024): AI vs 人間コードを正しさ・効率・保守性（CC、Halstead、MI、LOC）で比較。
  • Z. Liu et al., "No need to lift a finger anymore?...", IEEE TSE 50(6), 2024。
  • Y. Liu et al., "Refining ChatGPT-generated code...", ACM TOSEM 33(5), 2024。
  • Asare, Nagappan & Asokan, "Is GitHub's Copilot as bad as humans...?", EMSE 28(6), 2023。
  • 総じて「機能的には妥当でも、可読性・保守性・セキュリティに難」が共通見解。

D2. AI固有の問題: 重複増加・churn増加（GitClear） — 新興 / ベンダー研究

  • GitClear 2025 "AI Copilot Code Quality"（Harding/Kloster）: 2020–2024の2.11億変更行を分析。
  • コピペ行: 8.3%(2020)→12.3%(2024)、相対48%増。
  • moved（リファクタ）行: 24.1%→9.5%、相対39.9%減。2024年に初めてコピペ行がmoved行を上回った。
  • short-term churn（2週間以内改訂）: 5.5%→7.9%、「pre-AIベースライン比で2024年に2倍化見込み」。
  • 5行以上の重複ブロックは2024年に8倍増。
  • Mo et al.: co-changeクローンの57.1%がバグに関与。
  • 注意: 自社ツール顧客データ中心のベンダー研究。方向性は整合するが独立再現は途上。

D3. CMU Cursor研究（最重要の独立実証） — 査読前 / MSR'26採択

  • He, Miller, Agarwal, Kästner & Vasilescu (CMU, 2025), "Speed at the Cost of Quality..."（arXiv:2511.04427、MSR '26採択）。
  • 手法: .cursorrules で採用を検知し807リポジトリを特定、傾向スコアマッチングで1,380の対照群。Borusyak et al. DiD + パネルGMM。
  • 主要結果: 開発速度に有意で大きいが一過性の上昇、静的解析警告とコード複雑度に持続的増加。採用初月にlines added 3–5倍（2か月後に消失）、静的解析警告+30%・コード複雑度+41%が持続。GMMは「蓄積した技術的負債が将来の速度を下げる自己強化的悪循環」を示す。
  • 注意: 査読前、OSS限定。対照群もCopilot等を使う可能性があり効果は過小推定の可能性。

D4. SWE-bench等のベンチマークと設計品質指標の違い

  • SWE-bench はテスト通過=成功で機能的正しさのみ測定。保守性・効率・設計は捉えない。
  • OpenAIはSWE-bench Verifiedで「27.6%サブセットの59.4%でテストが正解を誤って棄却」と報告しフロンティア評価から除外（2026/2）。COMPASS（arXiv:2508.13757）は効率・品質を多軸評価する補完ベンチマークを提案。
  • 補完関係: ベンチマーク=「動くか」、設計品質指標=「保守できるか」。両輪が必要。

D5. deterministic checker / static analysis をエージェントharnessに組み込む（実務関心に直結）

  • 観点: 上記指標の多くは決定論的に計算可能（McCabe、複雑度デルタ、循環依存、重複率、結合デルタ）。これらをsandbox内のpost-edit checkとしてエージェントループに組み込み、閾値超過で自動リジェクト/再生成。
  • 実例的アプローチ: コールグラフをLLMプロンプトに注入（CelloAI、arXiv:2508.16713 がDoxygenコールグラフの2ホップlineageを付加）。Breakpoint（arXiv:2506.00172）は中心性×複雑度とAI修正成功率の相関を分析。
  • 含意: 「機能テスト（非決定的にパスしうる）」+「設計品質チェッカー（決定論的）」の二段ゲートが、AIエージェントの設計劣化を抑える現実的harness設計。

プロジェクトへの導入プラン（言語横断）

推奨ツールチェーン（言語非依存の土台 → 言語別の抽出層）

言語非依存に使える土台（まずこれ）: - 複雑度（McCabe/Halstead/CC）: lizard（20言語以上を単一CLIで）、SonarQube/SonarCloud（30言語以上、cognitive complexity・TDR・duplication・550+ルール）。 - クローン/重複: PMD-CPD（多言語）、SonarQube duplication、lizard duplicate。 - AST（構造指標・diff）: tree-sitter（多言語文法、ビルド不要）、GumTree（AST diff）。 - 依存・コールグラフ + データフロー: CodeQL（主要言語、OSS無料）、Understand（商用）、Sourcetrail系。 - ネットワーク解析: 抽出グラフを NetworkX（手軽）/igraph（高速）/graph-tool（最速）/NetworKit（大規模）で中心性・modularity Q・SCC・propagation cost計算。 - 履歴系（churn / co-change / DORA）: git解析、CodeScene、GitClear。完全に言語非依存。

言語別の抽出層（CBO/LCOM とコールグラフ抽出だけが言語依存）: - OO（Java/C#/C++/Python/TS等）: ckjm/ck（Java）、NDepend（.NET）、Understand（汎用）。コールグラフはCodeQL/言語サーバから。 - 手続き型・関数型（C/Go/Rust等）: CBO/LCOMは適用せず fan-in/fan-out・モジュール依存・グローバル状態共有で代替。コールグラフは各言語ツール（C: cflow/clang、Go: go callvis/callgraph、Rust: rust-analyzer等）。 - スクリプト（JS/TS/Python）: madge/dependency-cruiser（JS/TS）、pydeps/import-linter（Python）。

言語横断で押さえる落とし穴

  • 動的ディスパッチ/関数ポインタ/リフレクション: 静的コールグラフは取りこぼす。CodeQL等のデータフローで補完するが完全ではない。「取りこぼし前提」でトレンドを見る。
  • OO指標 vs 手続き型: CBO/LCOMはクラスを持つ言語専用。fan-in/fan-out + モジュール依存 + 共有状態が普遍的な代替。
  • マルチ言語リポジトリ: lizard/SonarQube/tree-sitterで指標定義を統一し、言語ごとの閾値差を設定で吸収。
  • 生成コード/ベンダーコードの除外: 自動生成ファイル・vendored依存を計測対象から除外しないと指標が汚れる。

CI組み込みステップ（段階導入）

  • 第0段階（ベースライン）: 全関数のMcCabe/Halstead/MI/LOC、モジュール依存グラフ、循環依存数・modularity Q・重複率を計測しスナップショット保存。「AI導入前後」比較の基準線。最優先。
  • 第1段階（PRゲート、決定論的）: lizardをCIに追加。新規/変更関数のCCN>15、関数長、引数数で警告→閾値超過でPR fail。言語別linter併走。コピペ率増加分（PRデルタ）を閾値化。
  • 第2段階（週次グラフ解析）: 依存/コールグラフ抽出→NetworkXパイプラインをスケジュール実行。循環依存数・最大SCCサイズ・propagation cost・modularity Q・中心性上位を時系列ダッシュボードに記録。新規循環依存の混入をブロック。
  • 第3段階（プロセス指標）: SonarQubeでTDR/Maintainability Rating継続計測。git履歴からchurn・co-change結合。DORA 4キーをCI/CDから収集。
  • 第4段階（AIコーディング経時評価）: コミットを「AI支援/非支援」でタグ付け（commit trailer、ブランチ規約、.cursorrules等の有無）。AI支援/非支援で「複雑度デルタ・結合デルタ・churn・重複率」を比較。速度指標と品質デルタを必ずペアで提示。

harness/エージェント設計への接続（実務関心）

  • 二段ゲート: ①非決定的な機能テスト（sandbox実行）+②決定論的な設計品質チェッカー（複雑度デルタ、新規循環依存、重複増、結合増）。②で閾値超過なら自動リジェクト→再生成プロンプトに違反内容をフィードバック。言語非依存ツールで組めば多言語でも同一ハーネス。
  • コンテキスト注入: 変更対象関数のコールグラフ2ホップ（callers/callees）と中心性をプロンプトに付加（CelloAI型）。高中心性関数は人間レビュー必須にエスカレーション。
  • 経時回帰検知: グラフ指標を回帰テスト的に扱い、modularity Q低下/propagation cost上昇/最大SCC拡大をCIアラート化。

Claude Code コーディングで取り入れるべきこと

このフレームワークを、自分の Claude Code 運用（~/.claude の hooks / settings / agents / skills）に落とすと何をすべきか。「速度はAIが出す。品質デルタは決定論ゲートで守る」が方針。詳細は llm_product_clean_architecture_設計 の「認可・チェックは決定論コア側に置く」思想、コールグラフ注入は context_engineering_ast活用 と地続き。

1. PostToolUse hook で「編集直後に lizard」を回す（最優先・低コスト）

Claude Code は Edit/Write の後に PostToolUse hook を実行できる。編集されたファイルに lizard をかけ、CCN>15 / 関数長 / 引数数の超過を即フィードバックする。drawio 自動エクスポート hook（~/.claude/scripts/drawio-auto-export.sh）と同じ仕組みで、*.py/*.ts/*.go 等に対して走らせる。

# 例: ~/.claude/scripts/lizard-check.sh （PostToolUse で編集ファイルパスを受ける）
file="$1"
case "$file" in
  *.py|*.js|*.ts|*.go|*.java|*.rs|*.c|*.cpp)
    lizard -C 15 -L 80 -a 5 "$file" || echo "⚠️ 複雑度/関数長/引数数が閾値超過: $file" ;;
esac
→ Claude が自分の生成物の複雑度超過をその場で認識し、続けて分割リファクタに向かえる。「書いた直後に決定論チェック」がCMU研究の悪循環を断つ起点。

2. 二段ゲートを Stop hook / subagent で実装

  • ①機能テスト（非決定的）: 既存の test 実行（bg-notify.sh でラップして完了通知）。
  • ②設計品質チェック（決定論的）: 複雑度デルタ・新規循環依存ゼロ・重複増・結合増。code-reviewer / refactor-cleaner agent に「lizard と循環依存検知を実行し、閾値超過を指摘」を担わせる。 → ②で超過なら Claude に違反内容を返して再生成させる。これが harness レベルの設計劣化抑制。

3. tree-sitter ベースのコンテキスト注入（CelloAI型）

変更対象関数のコールグラフ2ホップ（callers/callees）をプロンプトに添えて、波及範囲を意識させる。context_engineering_ast活用 の tree-sitter / ast-grep がそのまま使える。高 betweenness/PageRank の関数は「人間レビュー必須」フラグを立てて、Claude に勝手に大改修させない。

4. lizard を settings.json の allow に入れ、PRゲート化

  • ~/.claude/settings.json の permissions.allow に Bash(lizard:*) を追加（汎用・全プロジェクト共通なのでグローバル昇格対象）。
  • 各プロジェクトの CI（GitHub Actions）に lizard を追加し、新規関数 CCN≤15 / 新規循環依存=0 / コピペ率増を閾値化。Claude が出した PR もこのゲートを通す。

5. ベースライン → AI前後の比較（第0段階を必ず先に）

新しめのリポジトリでは、AI本格導入前に複雑度分布・依存グラフ・churn・TDR のスナップショットを取る。これが無いと「Claude を入れて劣化した/改善した」を統計的に言えない。tech-note で各リポジトリのベースラインノートを残すのも手。

6. 速度と品質デルタをペアで見る運用

日報・週次レビューで、lines added / commits（速度）だけでなく 複雑度デルタ・循環依存数・重複率（品質）を並べて記録する。CMU の教訓どおり、速度指標だけ見ると必ず誤判断する。

7. 既存ルールとの整合

  • ~/.claude/rules/common/coding-style.md の「関数<50行・ファイル<800行・ネスト>4禁止」は、McCabe/Cognitive Complexity/nesting depth の定性版。lizard の数値ゲートで定量裏付けできる。
  • code-reviewer agent のレビュー基準に「複雑度・結合・循環依存の数値」を明示的に足すと、レビューが主観から定量へ寄る。

まとめ（Claude Code への落とし込み早見表）

フレームの層 Claude Code での実装
第1層（複雑度） PostToolUse hook で lizard、settings.json allow、CIのPRゲート
第2層（結合/グラフ） 週次の循環依存・modularity Q チェック、コールグラフをプロンプト注入、高中心性は人間レビュー必須
第3層（プロセス） 速度×品質デルタを日報/週次で並置、ベースライン比較
harness 機能テスト + 決定論チェッカーの二段ゲート → 超過は再生成フィードバック

Recommendations

  1. まず決定論的に測れる土台3指標をCIに入れる（今すぐ）: lizard（McCabe + コピペ率）、言語別linter、循環依存検知（依存グラフ→NetworkX SCC）。閾値: 新規関数CCN≤15、新規循環依存=0、PRごとのコピペ率増を監視。
  2. ベースラインを取ってからAIを評価する: AI導入前のスナップショットが無いと「AIが悪化させた」と統計的に言えない。第0段階を最優先。
  3. 速度と品質を常にペアで見る: DORA/SPACEの速度指標だけ、品質指標だけでは誤判断。CMU研究の通りAIは速度3–5倍×複雑度+41%・警告+30%。ダッシュボードで並置。
  4. ネットワーク科学指標は「週次のアーキテクチャ健康診断」に位置づける: PR単位には重すぎる。modularity Q・propagation cost・中心性は週次バッチ。新規循環依存だけPRゲートに昇格。
  5. 結合度は言語パラダイムに合わせて選ぶ: OOならCBO/LCOM、手続き型/関数型なら fan-in/fan-out + モジュール依存 + 共有状態。多言語は多言語ツールで定義統一。
  6. AIコーディングharnessには二段ゲートを実装: 機能テスト + 決定論的設計チェッカー。閾値超過を再生成フィードバックに回す。

判断を変える閾値（ベンチマーク）

  • コピペ率がAI導入後に継続上昇（四半期で相対+20%超、GitClearの48%増ペースに接近）→ DRY違反深刻化、リファクタプロンプト/ルール強化。
  • 静的解析警告デルタがCMU水準（+30%）に近づく→ レビュー基準を強化（小バッチ+堅牢なテスト）。
  • 最大SCCサイズ/propagation costの単調増加→ アーキテクチャ債務の蓄積、モジュール分割の投資判断（Sturtevant: 複雑度が生産性50%減・欠陥3倍）。
  • TDRがB(0.10)を超えてC帯へ→ 債務返済スプリント検討。

Caveats

  • ベンダー研究の偏り: GitClearは自社顧客データ中心。方向性は独立研究（CMU）と整合するが絶対値は割り引く。
  • プレプリント: CMU Cursor研究は査読前（arXiv 2511.04427、MSR'26採択）。OSS限定、対照群もAI使用の可能性で効果は過小推定の恐れ。
  • 相関≠因果: DORAのAI–安定性低下は「AIがバッチサイズを増やす」媒介が主因。AIコード自体が直接悪いとは限らない。
  • 指標のゲーミング: 単一指標の目標化は最適化の歪み（Goodhartの法則）。SPACEの多次元原則を守る。
  • MI/スケールフリー性への学術的留保: MIは式の定数に批判（Teamscale/CQSE不使用、van Deursenが警告）。スケールフリー性は現象記述で品質指標ではなく反証もある。両者ともトレンド監視に留める。
  • 静的解析の言語横断的限界: 動的ディスパッチ・関数ポインタ・リフレクション・動的importで不完全。データフロー解析でも完全ではない。
  • modularityの解像度限界: Newman Qには既知の解像度限界。複数解像度/手法で交差検証。

作成: 2026-06-10 ／ 最終更新: 2026-06-16