SonarQube に アーキテクチャ分析 という新しい機能が追加されました。これまで SonarQube が見てきた信頼性・保守性・セキュリティに、もう一段上の観点として「コードの依存関係や構造そのものを継続的に管理する」機能が加わったかたちです。
背景として、Coding Agent を使った開発で、実装は速くなる一方で、コード全体の整合性が崩れやすくなっているという問題意識があります。
Sonar公式でもアーキテクチャの劣化が一気に進んでしまう状況に触れ、それを防ぐための機能をリリースしたという流れになります。
本記事では、この アーキテクチャ分析 機能が何をするものなのか、どう使うのかというところと、実際に小さいプロジェクトで使ってみてどうだったかを紹介したいと思います。
アーキテクチャ分析機能とは
SonarQube のアーキテクチャ分析機能は、ざっくり 3 つの機能で構成されています。
-
現状アーキテクチャ（Current Architecture）の可視化
コードを静的解析した結果から、いまの依存関係や構造を地図のような UI で可視化します。コードからのリバースエンジニアリングなので、図を別途用意する必要はないです -
目標アーキテクチャ（Intended Architecture）の定義
SonarQube の Web アプリ上の専用エディタで、あるべき目標となる構造と、依存関係を定義します -
目標からの逸脱や循環参照の検出
定義した目標アーキテクチャと現状アーキテクチャを比較し、の逸脱や循環参照などの欠陥の発見します。通常の Issue と同列に扱えるため、Quality Gate にもそのまま組み込めます
この3つの機能を活用し、先に述べたアーキテクチャの劣化を SonarQube の品質チェックプロセスの中で防ごうというものになります。
利用条件と最新ステータス
2026 年 5 月時点の利用条件をまとめると次のとおりです。
| 項目 | 状況 |
|---|---|
| プロダクト | SonarQube Cloud（SonarQube Server 向けは後日公開予定） |
| ステータス | GA |
| 利用可能プラン | 全プラン |
| 対応言語 | Java / C# / Python / JavaScript / TypeScript |
Beta 版のリリース当初は Automatic Analysis では解析が走らない状況でしたが、現在は Automatic Analysis でも利用できるようになっているようです。
実際に使って
ここからは、実際に小さなプロジェクトでアーキテクチャ分析を利用してみたので、それを共有します。
対象は以下の通り。
-
構成: Frontend（React + WebWorker）+ API（Node.js + Express + MongoDB）+ 共通モジュール
-
monorepo 構成、全体を TypeScript で実装
-
規模: 約 6,300 LOC
個人プロジェクトですが、Frontend / API / 共通 という構成で、程よい題材かなと利用してみました。
現状アーキテクチャを見てみる
現状アーキテクチャの分析は、通常の SonarQube による分析を行うと自動で行われます。
プロジェクトメニューの Analysis → Architecture → Current architecture を開くと、現状アーキテクチャがマップとして表示されます。地図アプリのようにパンとズームができ、また要素クリックすると依存関係を探れる UI になっています。
マップには以下のようなルールがあります（凡例（Legend）ボタンを押すと表示されます）。
- ファイルをディレクトリで再帰的にグループ化される
- 各要素のサイズと配置は、プロジェクト構造を表している
- 要素は依存に基づき左から右へ並ぶ
- 縦に並ぶ同じ列の要素は、依存がない
このルールが分かっていると、マップを見るだけでざっくりとプロジェクトがどのような構成になっているかを把握することができます。
実際に自分のプロジェクトで試してみての気づきは以下のとおりです。
- API と Frontend が縦並びになっており、想定通り直接的な依存はない
- API は比較的シンプル、Frontend は縦横に伸び、複雑化していきている
- 共通モジュールは横に長く、依存関係の連鎖が深い
- 共通モジュールのテストコードが、なぜか 不自然に下流に置かれている。これは独立させるか、共通モジュールのルート直下に移動すると見通しが良くなりそう
- 循環参照ではないが、逆流する依存関係 がいくつか見つかった。配置階層を整理するなどすれば違和感なく解消できそう
ドキュメントを読み込むのとはまったく違って、「読まないと見えなかった関係」が、探索していくことで視覚的に入ってくるので、レビューや改善の入り口として便利と感じました。
目標アーキテクチャを定義してみる
プロジェクトメニューの Policies → Intended architecture から、専用エディタが開けます。定義する要素は 2 種類です。
- Structure（構造）: モジュール、またはそれをグループ化したもの
- Relationships（関連）: モジュールやグループ間で許可する依存関係
構造は、現状アーキテクチャの情報が Component structure として表示されるのでそこから選択、追加でき、ゼロから組み立てる必要はありません。また Add placeholder component という入力欄では、現在まだ現状アーキテクチャに存在しない構造の追加もできます。
関連については、先に追加した構造間の依存関係をドラッグアンドドロップで直感的につなげていくことができます。
今回のプロジェクト向けに試しに作ってみた際には、約 30 分 で目標アーキテクチャの初版を作成できました。
共通モジュールの src 配下は定義に時間がかかりそうだったので、今回は作成を見送っています。このように定義する範囲を絞って、できるところから始められるというのもうれしかったりしますね。
検出された問題を見てみる
目標アーキテクチャを定義したあとに改めて解析を走らせると、構造上の問題、関係上の問題が検出されるようになります。（循環参照は目標アーキテクチャを定義しなくても検出できます。）それぞれ通常の Issue として扱われ、Open Issues をたどれば普段の Issue 画面に直接遷移できます。
検出例をいくつか紹介します。
-
構造上の問題: 目標アーキテクチャでは
testの位置を移動し、srcと横並びに定義しました。これが現状アーキテクチャの逸脱となりました。結果、ファイル移動を促す Issue が「保守性・アーキテクチャ」の問題として上がっていました -
関係上の問題: 目標アーキテクチャでは
pages → partsの一方向のみ許可する関連と定義したが、現状アーキテクチャでは逆向きの依存のため逸脱となりました。結果、未許可の関係性を削除すべしという Issue がこれも「保守性・アーキテクチャ」の問題として上がっていました -
循環参照の問題:
Tanglesの一覧から、検出された循環参照を確認できる。どの参照を問題として扱うかはユーザー側で選ぶ仕様となっており、問題として扱う判断をしたものが次回以降の解析で Issue 化されます
上記は、共通モジュールですが、「相互作用するオブジェクト群」と「サンドボックス実装」が絡まり合って、かなり複雑な Tangle になっていました。改善したい気持ちはあるものの、アルゴリズム自体の都合もあるので、対処タイミングは別途検討としました。
Quality Gate と組み合わせる
ここまで触れてきたとおり、アーキテクチャ分析が上げる問題は 通常の Issue と同列 に扱われます。Quality Gate の条件にそのまま組み込めるため、CI/CD でアーキテクチャ違反をブロックすることができます。
逆にアーキテクチャを定義すると Quality Gate がくぐれなくなるかもという懸念もありそうですが、いきなり完璧な目標アーキテクチャを定義する必要はなく、その定義範囲も絞れるため、大規模／既存プロジェクトでも少しずつ改善していくということが可能な作りになっているなと感じました。
試して感じたこと
使ってみてよかった点
- 依存・非依存の関係が一目で分かる: ドキュメントや README に加えて、構造を俯瞰できるというのは理解の助けになったし、再確認にもなりました
- 目標アーキテクチャの初版が短時間で書ける: 現状アーキテクチャの内容を使って選択式で作成できるので、一旦現状を書き起こすだけであればスムーズに開始できます
- 無理のないペースで進められる: 今回のように「共通モジュール内部は見送り」など、現実的な落とし所をつけられます。大枠の整理 → 特定パッケージの整理 → 共通モジュール というように、詳細化の対象を選べる
改善に期待したいところ
執筆時点の率直な感想として、以下が改善されるとさらに使い勝手が上がりそうと感じたので期待も込めて共有しておきます。
- インポート／エクスポート: 定義をテキストとして取り出せると、戻したい場面や、AI に相談する場面でも便利そう
- 正規表現／Glob パターンのサポート: 機能ごとに実装をまとめる Feature-based の構成とかでは、定義が煩雑になりそうなので
- 外部 API・依存ライブラリへの参照制約: DB アクセスが許される層、外部 API を呼んでいい層など、目標アーキテクチャで制限したい
- AI 連携によるリコメンド／テンプレート提供: 典型的なレイヤー構成のひな型があるとうれしい
- 責務や Architectural Decision Records(ADR) 情報の付与: 目標アーキテクチャの各構造に責務や意図を残せると、アーキテクチャが生きてくるし、AI にも使ってもらえるかも？
機能改善のサイクルは速く、GA 後も活発にアップデートが入っているようなので、このあたりも近いうちに入るのではと期待。
まとめ
今回は SonarQube に新しくリリースされたアーキテクチャ分析機能を紹介しました。
コードの依存関係と構造を継続的に確認するための基盤として、SonarQube の既存機能とシームレスにつながり、このAI開発時代に、レビュアーの負荷を下げるガードレールの1つとして、強力な機能かなと感じました。
興味を持った方は、自分のプロジェクトで利用してみると、想像していなかった気づきがあるかもしれません。ぜひぜひお試しください。
参考
クレスコでは、SonarQube Server の日本語化プラグインを作ったりしています。ぜひそちらもご参照ください。