【2025年版】PhpStorm×Claude Code実務大全：設定・設計・レビュー・運用まで一気通貫

こんばんは！IT業界で働くアライグマです！
日々の開発で「生成AIの補助をIDEに統合したい」「レビューで再現性のある差分に落とし込みたい」と感じることはありませんか。この記事では、私が現場で実践しているPhpStorm × Claude Codeの連携セットアップから、設計→実装→レビュー→テストの運用までを、安全に小さく回す具体手順としてまとめます。実際に使っているテンプレートやチェックリスト、失敗しやすいポイントと回避策も添えて解説します。

この記事の読み方ガイド（ペルソナ別）

「どこから読めば良いか」を迷わないように、立場別のショートカットを用意しました。

  • 異業種からエンジニア転職を目指す人：下の用語ミニ辞典→はじめてのセットアップ手順→初心者向けプロンプト雛形だけでOKです。
  • 駆け出しエンジニア：はじめてのセットアップ手順→初心者向けプロンプト雛形→失敗テスト先行の型→進め方の全体像を順に。
  • PMに興味がある若手エンジニア：レビュー観点チェックリスト→小さく回すための運用→進め方の全体像の順で、意思決定の基準を押さえましょう。

このガイドを踏まえて、自分に必要な場所だけ拾い読みしても理解できるよう構成しています。

読み方ガイドのイメージ

用語ミニ辞典（30秒で要点）

  • I/F（インターフェース）：関数の「入口（引数）」と「出口（戻り値）」、そして「約束（例外や前提）」のこと。
  • 差分パッチ：大工仕事でいう「削った部分だけ交換」に相当。変えたところだけを小さく提出します。
  • 失敗テスト先行：まず「失敗する自動テスト」を作って、ゴールの形をハッキリさせてから実装します。
  • 観測KPI：システムの健康診断の数値（P95レイテンシ、エラー率、リトライ回数など）。
  • 保存時整形：保存と同時に自動でコードを整える機能。見た目の差分をPRから分離できます。

まずはこの用語だけ押さえれば本文がスラスラ読めるはずです。

用語ミニ辞典のイメージ

この記事の狙い

生成AI（Claude Code）を“書記兼レビュー補助”としてIDE（PhpStorm）に組み込み、I/F設計→失敗テスト→最小実装→差分レビュー→観測の順で小さく素早く回す方法をまとめます。ポイントは「差分で頼む」「IDEに検証を先に置く（リンタ・テスト）」「大きく作らない」。
具体的には、プロジェクト別のプロンプト雛形、エディタ側のショートカット割り当て、AIへの指示の最小単位（関数/モジュール）、レビュー観点のチェックリストを整備し、往復コストを下げます。

実務では「やること」が先に具体化されていないとAIの出力もぶれます。そこで、まずは問題→目的→制約→判断基準→施策→計測KPIを1ページにまとめ、Claude Codeへ最初に提示します。これにより、指示が抽象化しにくくなり、差分パッチとして返すことも期待できます。
例として、既存APIのタイムアウト短縮を扱う場合は、目的（P95=300ms）、制約（互換性維持/ロールバック容易）、判断基準（エラー率悪化なし）、施策（キャッシュ/バッチ化）、KPI（レイテンシ/エラー率/リトライ回数）を先に固定します。
この下準備をしてからプロンプトへ進むと、PRの説明欄も同じ構造で書けるため、レビュワーの合意形成が速くなります。

さらに、プロンプトの雛形を用意することで、AIへの指示が具体的になります。具体的には、入力条件、出力形式、評価基準を明記し、既存の規約や命名規則を守るように指示します。これにより、AIが出力するコードが既存のコードベースに適合しやすくなります。
例として、次のようなプロンプトの雛形を用意します。

目的: XX機能のI/F定義と最小実装を作る
制約: 
- 既存規約に準拠（リンタ/フォーマッタでノーエラー）
- 変更は差分パッチ（関数/モジュール単位）
- 例外・境界・I/Oを明示
出力: 
- I/F表（引数/返り値/例外）
- 失敗テスト（先行）
- 実装の最小差分パッチ
- README追記の差分

このプロンプトの雛形を用意することで、AIへの指示が具体的になり、出力されるコードが既存のコードベースに適合しやすくなります。

AIとエディタ運用のイメージ

前提ツール

  • PhpStorm：プロジェクト規模のリファクタと差分把握が容易。キーマップ最適化が効きます。
  • Claude Code（JetBrains連携）：スニペット生成/コードレビュー/説明の要約。モデル切り替えも想定。
  • リンタ/フォーマッタ：Black/ruff、Prettier、ESLint 等。PhpStormの「保存時整形」をON。
  • テストランナー：pytest/Jest 等。最初に失敗テストを置いて自動化。
  • CI：リンタとテストを同条件で再現。PR毎に実行。

PhpStormのプラグイン/設定はプロジェクトと相性があります。まずは「IDEの保存時整形」「インスペクションの強度」「コードスタイル」をチーム標準に揃え、Claude Codeへの指示は関数単位の差分で渡すと精度が安定します。内部運用品質の基礎固めは「ログモニタリングの完全ガイド」の設計観点も参考になります。
具体設定の例：

  • 保存時整形：ESLint/Prettierやruffを保存時に走らせ、フォーマット差分をPRから分離。
  • インスペクション：誤検知が多い規則はスコープを限定。警告ゼロの状態を基準に。
  • キー割り当て：テスト実行/再実行、差分表示、選択範囲送信（Claude Code）を利き手側へ集約。
  • プライバシー：社外送信を避けるコード/秘密情報をスニペットから除外。ファイル無視設定を活用。

Claude Codeのモデル切替（高速/精度）もショートカット化しておくと、検証→再生成の往復が速くなります。

前提ツールのイメージ

はじめてのセットアップ手順（初心者向け）

はじめてでも迷わないように、手順を短くそろえました。

  1. PhpStormをインストール：公式サイトから導入。テーマやフォントは見やすさ重視でOK。
  2. Claude Code（JetBrains）を有効化：プラグインを追加し、サインイン。プロジェクトを開いた状態で有効化すると設定が反映しやすいです。
  3. 保存時整形をON：ESLint/Prettierやruffの実行を保存時に設定。見た目の差分をPRから分離できます。
  4. テスト実行のショートカット：再実行キーを利き手側に割り当て、失敗→修正→成功の往復を1キーに。
  5. ファイル無視設定：社外送信しないべきコードや秘密情報をスニペット対象から外します。

できたら、小さな練習課題（メールアドレスの全角→半角など）で往復を試しましょう。

はじめてのセットアップのイメージ

進め方の全体像

  • 要件→I/F：入出力とエラー条件を先に固定。
  • 失敗テスト先行：再現手順を自動化し、ゴールを可視化。
  • 最小実装：関数/モジュール単位で通す。巨大PRを避ける。
  • 差分レビュー：理由が読める粒度でPR化。整形だけは別PR。
  • 観測性：ログの粒度/構造を事前に決める。
  • ドキュメント：README・docstringを同時に差分で更新。

PhpStormではスコープ選択→アクション実行の往復を最小化すると生産性が上がります。例えば「対象ファイルを開く→関数選択→Claude Codeへ『I/Fを守ってこの分岐のみ最小変更』と指示→即差分確認→ローカルテスト実行」という短いループを回します。
さらに、コミットを機能ごとに分割してPRを小さく保つと、レビューの合意形成が速くなります。レビュー観点の整備は「AIコーディングアシスタント比較」で示した補助軸も役立ち、監視設計は「ログモニタリングの完全ガイド」の指針が有効です。プロンプトの基礎固めには 大規模言語モデルを使いこなすためのプロンプトエンジニアリングの教科書 も併せてどうぞ。
ケーススタディ：問い合わせフォームのバリデーション改善

  1. 失敗テスト追加（全角メール/過長氏名）。
  2. Claude Codeへ関数の分岐だけを選択送信し「I/F不変・差分パッチで」と指示。
  3. 差分確認→整形→ローカルテスト実行。
  4. ログ粒度を見直し、入力値はマスク。観測KPI（P95/エラー率）をダッシュボード登録。
  5. 小さなPRで提出し、ロールバック手順もPR本文へ記載。

これを繰り返すだけで、往復コストが大きく低下し、品質変動も抑えられます。

進め方の全体像のイメージ

はじめてのプロンプト雛形（初心者向け）

専門用語を避けた、最初の一歩用の雛形です。

やってほしいこと: 会員登録フォームで、全角メールを正しい形に直す関数を作る
守ること:
- 既存の関数名や引数は変えない
- エラーの種類とメッセージをはっきりさせる
出力してほしいもの:
- 関数の入力と出力の説明
- 先に失敗するテスト（例1つ）
- 最小限の変更だけ（差分）

迷ったら、「何を入れて何が出るか」→「ダメな例を先にテスト」→「直した所だけ提出」の順に考えると安定します。

初心者向けプロンプトのイメージ

プロンプト雛形（設計→実装）

Claude Codeに渡す雛形は、入力制約・出力形式・評価基準の3点を外さないのがコツです。特に「既存規約を守る」「差分パッチで返す」「例外と境界を明示」させると、PRに載せやすいアウトプットになります。PhpStormではエディタで選択範囲を絞り、関数単位での指示に固定すると安定します。

目的: XX機能のI/F定義と最小実装を作る
制約: 
- 既存規約に準拠（リンタ/フォーマッタでノーエラー）
- 変更は差分パッチ（関数/モジュール単位）
- 例外・境界・I/Oを明示
出力: 
- I/F表（引数/返り値/例外）
- 失敗テスト（先行）
- 実装の最小差分パッチ
- README追記の差分

補助雛形（レビュー依頼用）：

目的: 差分パッチのレビュー
前提: 既存テストは成功、失敗テストが1つ成功するようになった
観点:
- 命名/責務は単一か
- 例外/境界の説明は十分か
- ログはPIIを含まず粒度は適切か
- 性能劣化はないか（予算内か）
出力: 指摘事項の箇条書き、修正差分パッチ

生成後は必ず自分の言葉で要約し、意図と一致しているかをチェックします。レビュー観点に直結させると往復が減ります。設計の考え方を深めるなら 達人プログラマー ―熟達に向けたあなたの旅 が参考になります。なお、PhpStormのインスペクション結果と齟齬があれば、まずIDEの警告をゼロにしてからAIに再依頼すると、以降のやりとりが安定します。

プロンプト設計のイメージ

レビュー観点チェックリスト

  • 命名と責務：単一責務か。副作用は明示されているか。
  • エラー設計：再試行可否、メッセージ方針、呼び出し契約。
  • 境界値：空/最大/異常入力の扱い。
  • N+1/ロック順序：データアクセスの回数と順序の安全性。
  • 性能予算：根拠とトレードオフが説明できるか。

チェックの具体例：

  • ダメ例/命名：utilやhelperなど用途不明な命名 → 良い例：EmailNormalizer（責務を明確化）。
  • ダメ例/例外：Exceptionのみ捕捉して握りつぶす → 良い例：ValidationErrorとIOErrorを分離。
  • ダメ例/境界：最大長のテストがない → 良い例：空、最大、異常（マルチバイト）を網羅。
  • ダメ例/性能：ループ内でDB呼び出し → 良い例：一括取得とインデックス設計。
  • ダメ例/ログ：個人情報を平文で出力 → 良い例：トークナイズ/ハッシュ化、ID参照のみ。
  • 契約：呼び出し前後条件（pre/post）をdocstringに明記し、変更時はPRで契約変更を宣言。
  • 観測：エラー率/P95/リトライ回数をダッシュボード化し、PRでKPIの期待値を明示。

PhpStormではインスペクションの誤検知抑制（スコープや強度の調整）や、コードスタイルの自動整形を先に通してからAIレビューを依頼すると、ノイズが減ります。
レビューの運用例は「チケット運用効率化」や「ログモニタリングの完全ガイド」と相性が良いです。アクセス権限や秘密情報の取り扱いは早めに方針を決め、端末側の保護には YubiKey 5C NFC を検討してください。

コードレビューのイメージ

失敗テスト先行の型

Claude Codeで雛形を作る前に、必ず失敗する自動テストを用意します。PhpStormのテストランナー構成を保存し、1キーで失敗→実装→成功の往復ができるようにします。副作用を持つ処理はテストの前後状態を検証し、ログメッセージの粒度も先に決めておくと後の運用が安定します。Pythonの自動化例は 作業が一瞬で片付く Python自動化仕事術 が導入に向いています。

ケース: バリデーション失敗
Given: 不正入力X
When: validate(X)
Then: InvalidError を送出し、メッセージは '...' を含む

補助テンプレ（pytest例/擬似コード）:

def test_email_normalize_multibyte():
    with pytest.raises(ValidationError) as e:
        normalize_email('ＡＢＣ＠ｅｘａｍｐｌｅ.ｃｏｍ')
    assert 'multibyte' in str(e.value)

def test_form_slow_path_p95():
    t = measure_p95(lambda: submit_form(sample_payload()))
    assert t < 0.3

CIではテストの並列実行で順序依存が露呈することがあります。順序依存が出たらバグと捉え、フィクスチャのスコープや一時ディレクトリの扱いを見直します。外部APIはフェイク/スタブでコントロールし、ネットワーク不要で再現できることを基準にします。

テスト駆動のイメージ

小さく回すための運用

  • フラグ：新旧切替を用意し、ロールバック容易に。
  • 棚卸し：再発指摘を規約に昇華、プロンプトへ反映。
  • メトリクス：レイテンシ/エラー率/リトライ回数を定点観測。

具体策として、フィーチャーフラグでリリースを段階化し、ロールバック手順を文書化します。PRテンプレートには「目的」「制約」「テスト項目」「観測項目（ログ/メトリクス）」を入れて、レビュー観点を先に合意しておきます。
ロールアウト手順（例）：

  1. ステージングでP95/エラー率の基準を満たすことを確認。
  2. 本番で1%→10%→50%→100%の順にフラグを切り替え。
  3. 各段階でログ/メトリクスを確認し、閾値超過で即時ロールバック。
  4. 事後に原因を棚卸し、プロンプトとガイドラインへ反映。

在宅とオフィスの両立では作業環境の整備も効きます。モニターを増設して差分とテスト結果を並べるとレビュー効率が上がります。たとえば Dell U2424HE 23.8インチ USB-Cハブモニター の導入で手戻りが減りました（私見）。

運用最適化のイメージ

よくあるつまずきQ&A

  • Q. モデルが話を広げすぎて、欲しい差分が返ってきません。A. 指示の対象を関数1つに絞り、「I/Fは変えない」「出力は差分のみ」と明記します。長文で状況を説明するより、ダメな入力→期待する出力を短く示すと安定します。
  • Q. フォーマッタの差分でPRが見づらいです。A. 保存時整形をONにして、整形だけのPRを先に出す運用へ。以降のPRは実質差分だけに。
  • Q. ローカルでテストが通るのにCIで落ちます。A. 並列実行で順序依存が露呈した可能性。フィクスチャのスコープ、一時ディレクトリ、外部APIのスタブ化を見直します。
  • Q. 秘密情報の扱いが不安です。A. スニペット対象から除外する設定を見直し、個人情報はトークナイズします。端末保護には YubiKey 5C NFC も。

まずは小さく安全に回す仕組みを整えることが成功の近道です。

よくあるつまずきのイメージ

まとめ

大きく作らず、検証を先に置き、差分で説明する。これだけで“安全に速く”は達成できます。まずはPhpStormに保存時整形+テストショートカットを整え、Claude Codeには関数単位の差分で指示するところから始めてみてください。小さなPRを継続できれば、レビュー効率と品質は確実に上がります。

まとめのイメージ

IDE / 開発ツールPHP,SES,健康,転職,駆け出しエンジニア