レビューの消耗戦から抜け出せ：PhpStorm「Custom Inspection」でチームの暗黙知を自動執行するアーキテクチャ
テックリードとして最も生産性が削られる瞬間はどこか。CIでの構文エラーでもなければ、複雑なアルゴリズムの設計ミスでもない。それは、「プルリクエストでのコーディング規約の指摘」という、完全に自動化できるはずの泥臭い消耗戦だ。
「このクラスで直接 `new DateTime()` を使わないでください。日付のモック化ができなくなるのでインフラ層経由で……」
「またドメインモデルにリポジトリを直接インジェクションしていますよ。サービスクラスを経由させてください」
このようなチーム特有の設計制約（暗黙知）を、人間の目視によるコードレビューだけに頼るのは、組織のスケールにおいて致命的なボトルネックとなる。ドキュメントに規約を書き残しても、誰も読まない。Linterの標準ルール（PHP_CodeSnifferやPHPStan）だけでは、プロジェクト固有のビジネスロジックに踏み込んだアーキテクチャ違反までは検知できない。
ここで登場するのが、JetBrains PhpStormの奥義「Custom Inspection（カスタムインスペクション）」だ。
今回は、IDEの静的解析エンジンをハックし、プロジェクト固有の禁忌（アンチパターン）をリアルタイムで警告・ハイライトさせ、チーム全体のコード品質を「自動担保」する極限の仕組みを構築する。
—
1. 開発スピードを異次元に引き上げる：PhpStorm 隠しコマンド & 神プラグイン
Custom Inspectionの解説に入る前に、まずあなたの手元のPhpStormを「超戦闘モード」に引き上げる。これを知らずしてPhpStormを語るなかれ。
開発速度を3倍にする隠れキーボードショートカット（macOS / Windows）
- 「どこでも検索」二刀流 (`Shift` × 2 または `Double Shift`)
ファイル、クラス、シンボル、設定、果てはアクションまで全てを統べる。メニューバーを探すという無駄なコンテキストスイッチを脳から排除する。
- 最近の変更されたファイル (`Cmd + E` / `Ctrl + E`)
タブバーを見るな。直近触ったファイル群のメンタルマップがポップアップし、瞬時に往復できる。
- コンテキスト・アクション (`Option + Enter` / `Alt + Enter`)
PhpStormの心臓部。エラーや警告だけでなく、通常のコード行でも「何らかのリファクタリングや修正のヒント」が常にここに隠されている。Custom Inspectionと連携することで真価を発揮する。
- 行の複製 (`Cmd + D` / `Ctrl + D`)
選択していなければその行全体がコピー＆ペーストされる。地味だが指の移動量を劇的に減らす。
絶対に入れるべき神プラグイン 3選
1. Key Promoter X
マウスでメニューをクリックするたびに「今の操作、このショートカットキーでやれよ」と画面右下に右翼的なまでに優しく通知してくれる鬼コーチプラグイン。これを導入して1週間で、あなたのマウス操作は絶滅する。
2. String Manipulation
キャメルケース、スネークケース、JSONエスケープ、URLエンコードなど、文字列変形の全宇宙が `Alt + M`（または右クリックメニュー）に凝縮される。リファクタリング時の命名変更のストレスがゼロになる。
3. SonarLint
PHPStanやPsalmを補完し、セキュリティ脆弱性やバグの臭いをリアルタイムで嗅ぎ分ける。PhpStorm標準のインスペクションと併用することで、ローカル環境が最強のCIサーバーに変貌する。
—
2. なぜ「Custom Inspection」なのか？ Linterとの決定的な違い
「PHPStanやPsalmがあるから、IDEのインスペクションは不要ではないか？」という疑問を持つアーキテクトも多いだろう。しかし、ここには明確な役割の違いがある。
- PHPStan / Psalm（CI / CLI層）:
型の整合性、網羅性、静的解析の厳密性を担保する。重厚長大であり、実行に数秒〜数十秒を要する。
- PhpStorm Custom Inspection（IDE リアルタイム層）:
コードを打っているその瞬間（リアルタイム）に、開発者の脳裏に直接警告を突き刺す。
人間は、エラーを指摘されてから修正するまでの時間が短ければ短いほど、コンテキストを維持できるため学習コストが低い。CIが落ちるのを待つのではなく、コードを書いた指の下で「その書き方はウチのプロジェクトでは禁止です」と赤く波線が出ることの心理的効果は計り知れない。
—
3. 実践：プロジェクト固有の「Custom Inspection」を定義する
今回は、実務でよくある以下の要件をCustom Inspectionとして実装する。
> 【チームの独自ルール】
> 「ドメイン層（`Domain\` 名前空間）のクラス内において、直接 `\PDO` や外部データベース接続クラスをインスタンス化、あるいは静的呼び出しすることを一切禁止する。必ずリポジトリインターフェースを介すこと。」
これをPhpStormに認識させ、違反コードに対して即座に警告とクイックフィックス（自動修正の提示）を行う仕組みを作る。
Step 1: 構造検索（Structural Search and Replace: SSR）の召喚
PhpStormのインスペクションは、正規表現よりも強力な「構造検索（Structural Search）」をベースに作成できる。
1. メニューバーの `Preferences` (または `Settings`)を開く。
2. `Editor` > `Inspections` に移動する。
3. 右上の `+` ボタン（Add Inspection）をクリックし、「Structural Search」を選択する。
4. インスペクション名（例: `Domain layer should not directly instantiate database connection`）をつける。
Step 2: 検索テンプレート（Search Template）の構築
Structural Searchでは、コードの「構造」を抽象化して定義できる。以下のように設定する。
言語 (Language): `PHP`
テンプレート (Search template):
// $variable$ には任意のクラス名やインスタンスが入る
$variable$ = new \PDO($url$, $username$, $password$);
ここで、変数 `$variable$` の制約（Constraints）を設定する。
- `$variable$` を右クリック（またはEdit Variables）、あるいは下部の「Edit Variables」から、このパターンが適用されるスコープや条件を絞り込む。
- 今回は、クラス内のコンテキストを絞り込むために、インスペクションのスコープ（Scope）機能を利用して、対象ディレクトリを `app/Domain` に限定する。
Step 3: 警告メッセージの設定
インスペクションの設定画面で、検出された際に表示するメッセージを定義する。
> Warning message:
> ドメイン層（Domain\）での直接的なPDOのインスタンス化は禁止されています。インフラストラクチャ層のリポジトリを経由させてください。
これで、開発者が `app/Domain` 配下で `new \PDO(…)` と書いた瞬間、IDEがそれを検知し、鮮やかな赤の波線で警告を発するようになる。
—
4. チーム開発で役立つ設定の共有化ルール（インスペクションプロファイルのGit管理）
どれほど素晴らしいCustom Inspectionを作っても、それがテックライクな個人のローカル環境に眠っているだけでは組織の資産にならない。PhpStormの設定をチーム全員で完全同期させる仕組みが不可欠だ。
`.idea` ディレクトリの正しいバージョン管理戦略
PhpStormはプロジェクト設定を `.idea` ディレクトリ内のXMLファイル群として保存する。通常、`.idea` はすべてGitから除外（`.gitignore`）されがちだが、チームの生産性を底上げするアーキテクトは `.idea` の一部をバージョン管理に含める。
特に、インスペクションプロファイルの実体である以下のファイルは、チーム共有の「法典」としてGitで管理すべきだ。
- `.idea/inspectionProfiles/Project_Default.xml` (またはカスタム名)
- `.idea/php.xml` (PHPのバージョンやインテプリター設定)
- `.idea/codeStyles/CodeStyleConfig.xml` (コードスタイル設定)
チーム全員に強制適用するための設定手順
1. 作成したCustom Inspectionを含むインスペクションプロファイルをプロジェクト用にエクスポートする。
- `Preferences` > `Editor` > `Inspections`
- スキーム名の横にある歯車アイコンをクリック > `Share` を選択。
- これにより、設定が `.idea/inspectionProfiles/` 内のXMLとして保存される。
2. `.gitignore` の調整
# 通常の除外設定
.idea/
# ただし、インスペクションとコードスタイルは共有する
!.idea/inspectionProfiles/
!.idea/codeStyles/
!.idea/php.xml
3. チームメンバーがリポジトリをクローンした際、PhpStormは自動的にプロジェクト固有のインスペクションプロファイル（Project_Default）をロードし、全員のIDEで同じカスタムルールが稼働し始める。
—
5. 実用的な設定ファイル（XML）のベストプラクティス構成例
PhpStormが内部でどのようにインスペクションルールを保持しているか、その実態をXMLのコードとして覗いてみよう。以下のファイルは、前述の「ドメイン層でのPDO直接インスタンス化禁止」ルールをコード化した `.idea/inspectionProfiles/Project_Default.xml` の断片である。
このXMLファイルをチームで共有・同期することで、誰がどのマシーンでPhpStormを開こうとも、プロジェクトのアーキテクチャ境界が物理的（論理的）に守られる環境が完成する。
—
6. アーキテクトからの提言：ツールによる強制が組織の心理的安全性を生む
「厳しいルールをIDEで強制すると、開発者の自由を奪うのではないか」という反論を受けることがある。しかし、それは誤りだ。
人間同士のコードレビューで「この書き方はうちの規約違反です」「いや、これくらい良いでしょう」といった主観的な議論や感情的衝突が発生することほど、チームのエネルギーを無駄に消耗するものはない。
ツールが機械的に、感情を挟まずに「ここはダメだ」と指摘してくれる。これにより、コードレビューの場は「細かいタイポや規約の指摘」から解放され、「より良いアルゴリズムの設計」「ビジネス価値を最大化するドメインモデリングの議論」という本来のクリエイティブなフェーズへと昇華される。
PhpStormのCustom Inspectionをプロジェクトのインフラストラクチャとして組み込み、チーム全体の開発生産性を次の次元へと引き上げてほしい。