Claude CodeにSonarQubeプラグインを入れ品質ゲートを回す手順

SonarQubeのエージェントプラグイン(sonarqube-agent-plugins)は、SonarSourceがGitHubで配布している統合パッケージです。Claude Codeには/plugin install sonarqube@claude-plugins-officialで入ります。入れると/sonarqube:で始まるスラッシュコマンド群と、PRやdiffをまとめて見るレビュー用エージェントが使えるようになります。

MCPサーバーを自分でclaude mcp addする方法はSonarQubeのMCPサーバー接続手順にあります。プラグイン版はその上に、スキル・フック・エージェントを同梱し、セットアップまで案内させる位置にあります。

プラグイン版は、MCP単体と何が違うのか

プラグインが束ねているのは、SonarQube CLI(sonarコマンド)とSonarQube MCP Serverを呼び出すスキルです。リポジトリの説明では、Issue検出に加えて、テストカバレッジや重複といったプロジェクトのメトリクス確認、依存関係のリスク取得までを対象にしています。

MCPサーバー単体との差は、次の表のとおりです。

認証の行は見落としやすい点です。プラグイン版のMCPサーバーはsonar auth loginで作ったログインを使うため、トークンを--envに書く場面がありません。

前提条件 — 入れる前に3つそろえる

リポジトリが挙げる前提は3つです。

• SonarQubeのアカウント(SonarQube Cloud、Server、Community Buildのいずれか)
• マシン上のSonarQube CLI(sonar)
• MCPサーバーのイメージを動かすコンテナランタイム(Docker、Podman、Nerdctl)

加えて、Claude Codeでは起動時のSessionStartフック(scripts/setup.js)がNode.jsを使います。Vortex解析のように、SonarQube Cloudの組織設定に依存する機能もあります。使えるかどうかは自分の組織の設定次第です。

インストールからセットアップまで

シェルから入れる場合は、同じ意味のclaude plugin installが使えます。

claude plugin install sonarqube@claude-plugins-official
sonar auth login -o <org-key>
sonar integrate claude

sonar auth loginの引数は接続先で変わります。

sonar integrateは、エージェントごとに配線する中身が違います。Claude Code向けのsonar integrate claudeはMCP、フック、シークレット検査をまとめて設定し、Cursor向けのsonar integrate cursorはMCPとシークレット検査のフックに加えてVortex解析の指示を入れます。リポジトリの説明では、どちらもsonar auth loginの後に実行する順序になっています。

CLIやログインの手順を手で踏みたくない場合は、Claude Code上で/sonarqube:sonar-integrateを実行します。CLIのインストール・更新、ログイン、連携の配線を順に案内するスキルです。プロジェクトルートにsonar-project.propertiesを置いてsonar.projectKeyなどを書いておくこともできます。

インストールスコープは何を選ぶか

手順1で選ぶスコープは3種類で、プラグインを有効にする設定ファイルが変わります。

チームで品質ゲートの運用をそろえたいなら、projectスコープが候補です。ただしコミットで他のメンバーに伝わるのは「有効にする」設定だけで、プラグイン本体は各自のマシンに入りません。メンバーはそれぞれclaude plugin install sonarqube@claude-plugins-official --scope projectを一度実行します。

もう一点、sonar auth loginのログインは各自のマシンのキーチェーンに残るため、スコープを共有にしても認証は共有されません。まず自分だけで試すなら、localスコープなら他のメンバーの設定に触れません。同じプラグインを複数のスコープで設定したときは、local、project、userの順で優先されます。

スラッシュコマンドの一覧と使い方

プラグインのスキルは、/プラグイン名:スキル名の形で呼びます。Claude Code側のプラグインの仕組みとして、my-pluginのreviewスキルが/my-plugin:reviewで動く、という規則があります。このプラグインの名前はsonarqubeなので、すべて/sonarqube:から始まります。

数えると10個ありますが、sonar-integrateは導入用なので、日常で使うのは残りの9個です。リポジトリの使用例を、引数付きで並べます。

/sonarqube:sonar-list-issues my-project --severities CRITICAL
/sonarqube:sonar-fix-issue java:S1481 src/main/java/MyClass.java
/sonarqube:sonar-fix-issue python:S2077 src/auth/login.py:34
/sonarqube:sonar-quality-gate my-project --branch main
/sonarqube:sonar-coverage my-project --max 50
/sonarqube:sonar-coverage my-project --file src/auth/login.py
/sonarqube:sonar-duplication my-project --pr 42
/sonarqube:sonar-dependency-risks my-project --pr 42
/sonarqube:sonar-triage-dependency-risks my-project --branch main --fix

引数の読み方は例から取れます。

• プロジェクトキーを先頭に置き、--branchでブランチ、--prでプルリクエスト番号を指す
• sonar-fix-issueはルールキー(java:S1481)と対象ファイルを渡し、ファイル:行番号の形で位置も指せる
• sonar-coverageは--maxで件数を絞り、--fileで1ファイルに寄せられる
• sonar-triage-dependency-risksの--fixは、仕分けに加えて修正まで進めるときの引数として例に載っている

スキルは自然文でも起動します。「analyze my code for issues」「show open SonarQube findings」「check my coverage」と頼む使い方が、リポジトリの説明に挙がっています。

品質ゲートを開発のループに組み込む

/sonarqube:sonar-quality-gateは、プロジェクトの品質ゲートが通っているかを返すスキルです。ブランチやPRを引数で絞れるため、実装後の確認でそのまま使えます。

次のようなルールをCLAUDE.mdに書いておくと、実装の終わり方をそろえやすくなります。以下は筆者が考えた書き方の例で、プラグインが要求する記述ではありません。

## 完了条件
- 実装後は `/sonarqube:sonar-quality-gate <プロジェクトキー> --branch <作業ブランチ>` を実行する
- 失敗した条件は `/sonarqube:sonar-list-issues` で該当Issueを出し、直してから再度ゲートを見る
- ゲートが通るまでPR作成に進まない

特定のファイルを解析したいときは、/sonarqube:sonar-analyze src/auth/login.pyのようにパスを渡す例がリポジトリに載っています。

レビュー用エージェントと自動実行のフック

Claude Code、GitHub Copilot CLI、Cursorでは、プラグインがsonarqube-reviewerエージェントも同梱します。スキルを組み合わせて、PRやdiffを品質ゲート・Issue・依存関係リスク・重複・カバレッジの観点でレビューするもので、コードの編集はしないと説明されています。

読み取り専用のレビュー役が欲しいチームには、この性質が合います。直す作業は別に/sonarqube:sonar-fix-issueで指示し、観察と修正の担当を分けられます。

フックは別の層です。sonar integrate claudeは、Claude Codeにシークレット検査のフックを入れます。リポジトリの説明では、これは漏れた認証情報を、エージェントが作業するループの中で見つけるための仕組みです。CIまで待たずに検知できます。

Vortex解析は、組織で有効になっている場合に使える追加の検証です。有効なら編集のたびに自動で検証が走り、手動の呼び出しは要らなくなります。有効でない組織では、シークレット検査のフックは入りますが、編集ごとの自動検証は走りません。その場合は/sonarqube:sonar-analyzeなどを自分で呼びます。有効かどうかはSonarQube Cloudの組織設定の側で決まるので、プラグイン側のスイッチでは変えられません。

フックはイベントごとに同時に走る数にも上限があります。他のフックと併用するときは、hooksの同時実行は1イベント12件までも合わせて見てください。

他のエージェントとの違いと、つまずきやすい点

同じリポジトリが、Claude Code以外のエージェント向けにも入れ方を示しています。違いの要点だけ挙げます。

• GitHub Copilot CLIは/plugin install sonarqube@awesome-copilotで入れ、sonar integrate copilotを実行する
• Cursorは/add-plugin sonarqubeで入れ、sonar integrate cursorを実行する
• Codex CLIはcodex plugin add sonarqube@sonarで入れ、sonar integrate codexを実行する
• Factory Droidにはフックがなく、シークレット検査とVortex解析のフックは使えない

Claude Code側でつまずきやすいのは、次の2点です。

• 導入直後にコマンドが出ない: /reload-pluginsで読み込み直します。
• MCPのツールが見えない: sonar auth loginを済ませたか、コンテナランタイムが動いているかを見ます。MCPのイメージはDockerなどで起動する前提です。

自作のプラグインを別の面から読み込む場面はAgent SDKプラグインのロードにまとまっています。スキルを外部サービスの検査に使う別の例としては、StackHawkのスキルでHawkScanを回す手順があります。

更新・無効化・アンインストール

外すときも、入れたときと同じ/pluginの画面を使います。セッション内で/pluginを開き、TabキーでInstalledタブに移ると、インストール済みのプラグインごとに有効化・無効化・更新・アンインストールの操作があります。/plugin disableや/plugin uninstallでも同じパネルが開きます。

• 一時的に止めたい: 無効化にとどめれば、インストールしたまま戻せます
• 最新にしたい: 詳細メニューのUpdate nowを使います
• 反映したい: 変更後にPlugins changed. Run /reload-plugins to activate.と出たら、/reload-pluginsを実行します

projectスコープで有効にしたプラグインをアンインストールすると、Claude Codeは「自分だけ無効にする(y)」か「全員分を外す(u)」かを尋ねます。yなら.claude/settings.local.jsonにfalseが書かれ、リポジトリの共有設定は変わりません。uは共有の.claude/settings.jsonから外します。

プラグインを外しても、sonar integrate claudeが設定したMCPやフックがどこまで消えるかは、リポジトリの説明に書かれていません。外した後にsonar側の設定が残っていないかは、自分の環境で確かめるのが安全です。

まとめ

プラグイン版は、SonarQubeをClaude Codeの作業ループに入れるための一式です。導入は/plugin installとsonar integrate claudeの2段で済みます。日々の確認は/sonarqube:sonar-quality-gateで行い、直す作業はsonar-fix-issueに任せる使い分けが見えてきます。

認証とフックまで一度にそろえたいなら、プラグイン版が短い道です。ツールの絞り込みなど接続の細部を自分で決めたい場合は、MCPを手で追加する記事の手順が出発点になります。