PhpStorm「Search Structurally」で作る自動レビューツール：独自のコーディング規約をチームに強制するガードレールの構築法
テックリードとして最も頭を悩ませる問題は何だろうか。それは「コードレビューのコスト」と「品質の属人化」だ。
「PSRに準拠しているか」「セキュリティ的に危ういメソッドが使われていないか」「レガシーなファクトリーのインスタンス化が残っていないか」。これらを人間がプルリクエスト（PR）の段階でチェックし、指摘し、修正を促すプロセスは、シニアエンジニアの貴重な時間を大量に消耗させる。そして何より、指摘された側も、指摘する側も精神的に疲弊する。
この不毛な消耗戦に終止符を打つのが、PhpStormの奥義「Structural Search and Replace (SSR)」と、それをインスペクション（静的解析）に組み込む「ガードレール化」の手法だ。
今回は、単なるテキスト置換を超え、抽象構文木（AST）レベルでコードを解析し、チームの独自規約を自動チェック・自動修正するインフラをPhpStorm上に構築する方法を、実務の現場で即使える設定コードと共に徹底解説する。
—
1. なぜテキスト検索（Regex）ではダメなのか？ ASTとSSRの圧倒的な差
多くの開発者は、特定のNGワードを見つけるために正規表現（Regex）を使う。しかし、コードはテキストではなく構造（構文木）である。
例えば、「古いロガーの直接呼び出しを禁止し、依存性注入されたロガーを使うべき」という規約があったとする。
// 禁止したい記述
Logger::getInstance()->error($message);
これをRegexで検出しようとすると、スペースの有無、改行、静的メソッドのエイリアス、変数への代入など、あらゆる揺れに対応できず、偽陰性（見逃し）か偽陽性（誤検知）の山が築かれる。
PhpStormの Search Structurally は、コードを構文木（AST）に分解してマッチングを行う。ここでは、開発者が書いたコードの「意味」や「構造」をキャプチャ変数（ `$Var$` など）で抽象化し、パターンとして定義できる。つまり、「書き方（フォーマット）が違っても、構造が同じなら確実に検知する」ことが可能なのだ。
—
2. 実践：独自の危険な記述をキャッチするSSRパターンの作成
ここでは実務で即座に役立つ、2つの具体的なSSRパターンを構築してみよう。
ケースA: レガシーな `mysql_`系 や 非推奨の独自ヘルパー関数の排除
プロジェクト固有のヘルパー関数や、フレームワークの非推奨メソッド（例：Laravelで言うなら古いクエリビルダーの記述など）を検知する。
ケースB: 生のPDOやDBファラードの直接呼び出しの禁止（Repository層の強制）
サービスクラスから直接データベースを叩くのを禁止し、必ずRepository層を経由させるルールを強制する。
SSRパターンの定義手順
1. `Edit` > `Find` > `Search Structurally…` を開く。
2. 以下の検索テンプレート（Search template）を入力する。
// 検索テンプレート（Search Template）の例：
// サービス層でのダイレクトなDBクエリ実行を検知するパターン
\DB::table($tableName)->$method$($Args$);
ここで `$tableName$`, `$method$`, `$Args$` はすべてPhpStormが自動認識する変数（Variables）である。変数の設定（Edit Variables）で、以下のように制約（Constraints）を加えられる。
- `$method$` の制約: 正規表現で `insert|update|delete` に限定する。
これにより、`\DB::table(‘users’)->delete($id);` のような不正なコードだけをピンポイントで射抜くことができる。
—
3. 単なる検索で終わらせない。「インスペクション（Inspection）」への昇格
SSRで作ったパターンは、その場限りの検索（Find）で使ってはもったいない。これをプロジェクトのインスペクションルール（静的解析のルール）として常時稼働させることで、真の「ガードレール」が完成する。
テンプレートの保存とインスペクション化の手順
1. 作成したSSRダイアログで 「Save as Template」 をクリックし、わかりやすい名前（例: `TeamGuard: Direct DB manipulation in Service`）を付ける。
2. `Settings` (または `Preferences`) > `Editor` > `Inspections` を開く。
3. 「Structural Search」 の項目を探し、チェックを入げる。
4. リストの中から先ほど保存したテンプレートを探し、インスペクションの重大度（Severity）を `Error` または `Warning` に設定する。
これで、エディタ上でコードを書いているリアルタイムに、該当のコードに赤や黄色の波線が走り、警告が表示されるようになる。コミット前のプレチェックとしても機能するため、CI/CDに回す前の「ファーストディフェンスライン」として絶大な効果を発揮する。
—
4. チーム開発で絶対共有すべき設定ファイルのベストプラクティス
属人化を防ぐためには、このインスペクション設定をチーム全員の環境で同期しなければならない。PhpStormは、プロジェクトルートの `.idea` ディレクトリ配下に設定をXMLとして保存する。
以下は、今回作成した独自の構造的検索インスペクションをチームで共有するための `.idea/inspectionProfiles/Project_Default.xml` の設定例および管理のベストプラクティスだ。
`.idea/inspectionProfiles/Project_Default.xml` の設定例
チーム共有のための運用ルール
1. `.idea/` 配下のバージョン管理方針:
通常、`.idea/` は `.gitignore` に入れることが推奨されるが、インスペクション設定（`inspectionProfiles/`）とコードスタイル設定（`codeStyles/`）だけは Git の管理下に置くのがプロのチームの鉄則だ。
2. 強制力:
PhpStormのGit統合機能や、HuskyなどのGit Hooks（PHPであれば GrumPHP や PHP_CodeSniffer との連携）を組み合わせ、コミット時にPhpStormのインスペクションをCLI（`phpstorm.sh inspect` 等、またはQodana）で走らせ、エラーがある場合はコミットを拒否するフローを組むと完璧である。
—
5. 開発スピードを極限まで高める：PhpStormの神ショートカット＆プラグイン
ガードレールを導入しつつ、日々のコーディング速度自体を爆発的に高めるための実践知見を共有する。
現場で手放せない隠れキーボードショートカット
- `Cmd + Shift + A` ( macOS ) / `Ctrl + Shift + A` ( Windows/Linux ) : Find Action
- あらゆる設定や機能を呼び出すコマンドパレット。メニュー迷子になる時間をゼロにする。
- `Option + Enter` ( macOS ) / `Alt + Enter` ( Windows/Linux ) : Show Intention Actions
- SSRで検知されたエラー箇所にカーソルを合わせ、このショートカットを押すだけで、自動修正（Quick Fix）のメニューがポップアップする。SSRの「置換（Replace）」テンプレートを定義しておけば、ワンタッチでレガシーコードをモダンなコードに一括・個別置換できる。
- `Ctrl + W` ( macOS/Windows/Linux ) : Extend Selection
- AST（構文木）の階層に沿って選択範囲を拡大する。テキスト選択でマウスを触る必要が一切なくなる。
絶対入れるべき神プラグイン
1. Key Promoter X
- マウス操作をした際に、「今の操作は、このショートカットキーで実行できますよ」と右下にポップアップで教えてくれる鬼コーチプラグイン。チームメンバーのショートカット習熟度を自然と引き上げる。
2. String Manipulation
- キャメルケースからスネークケースへの変換、配列のソート、JSONのエスケープなど、コーディング中に発生する泥臭いテキスト加工を秒速で処理する。
3. Laravel Idea (※Laravel環境の場合)
- 公式プラグインの域を超えた神ツール。Eloquentの補完、ルーティング、バリデーションの補完精度が劇的に向上し、コードの記述ミスを未然に防ぐ最強の相棒。
—
6. おわりに：機械に任せられるものは機械に任せよ
シニアエンジニアがコードレビューで「ここ、直接DB叩いてますよ」「このメソッド非推奨ですよ」と指摘する時間は、ビジネス的な価値を何一つ生み出していない。
PhpStormの Search Structurally を駆使したガードレール構築は、チームのコード品質を担保する「自動化された防壁」である。人間は、より本質的なアーキテクチャの設計や、ビジネスロジックのブラッシュアップに集中すべきだ。
今日からあなたのプロジェクトでも、チーム特有の「アンチパターン」をSSRで定義し、インスペクションとして常時稼働させてみてほしい。レビューの指摘数が激減し、チーム全体の開発スピードが跳ね上がるのを実感できるはずだ。