2026/10/29
AI活用
Claude CodeでWebアプリの不具合を回帰テストに変える実務手順
対象読者：上級者向け
不具合修正の翌週に、同じ問題を戻さないための仕事
顧客向けWebアプリを保守する小規模な開発チームを想定します。問い合わせ管理画面で、特定の条件を満たすデータだけ保存できない不具合が報告されました。担当者の目的は、目の前のエラーを直すことだけではありません。同じ条件で再発したときに、リリース前のテストで検知できる状態まで整える必要があります。AIを使わない場合でも、担当者は課題管理ツール、ブラウザの開発者ツール、コードエディター、Git、既存のテストランナーなどを組み合わせて対応します。報告文とログから再現条件を整理し、手元で不具合を再現した後、画面、API、入力検証、データ保存処理のどこに原因があるかをコード検索で絞ります。修正対象が分かったら、既存テストの配置や命名、テストデータの作り方、モックの方針を調べ、不具合を再現するテストを追加します。最後に対象テストと関連テストを実行し、差分をレビューへ回す流れです。
この工程は、もともと必要な確認を積み重ねた妥当な保守作業です。問題は、調査対象が複数の層にまたがると、関連ファイルを開いては戻る作業や、既存テストから適切な雛形を探す作業が増えることにあります。急いでテストを書けば、実装の内部構造だけを固定するテストや、不具合とは無関係な変更を含む差分になりかねません。
そこで本稿では、Claude Codeに調査、既存テストの把握、テスト案の作成を補助させる方法に絞ります。扱うのは新機能の紹介ではなく、2026年10月29日に取得した公式ドキュメントで確認できる日常的なワークフローです。資料中で公開日を確認できないため、最新機能とは位置づけません。修正の採否や品質判断までAIに渡すのではなく、人が承認しやすい小さな差分を作ることが中心です。
時間を使うのはコード入力より調査の往復
不具合対応の負担は、テストコードを数十行書く部分だけでは測れません。最初に必要なのは、報告内容をテスト可能な条件へ置き換える作業です。「保存できない」という一文から、利用者の権限、入力値、操作順、対象ブラウザ、期待される表示、実際の応答などを切り分けます。情報が欠けていれば、報告者への確認も必要でしょう。ここが曖昧なままでは、別の現象を直してしまうおそれがあります。再現後は、画面イベント、状態管理、API、サーバー側の検証、永続化処理をたどります。検索結果が多いプロジェクトでは、同じ名前の関数や似た画面を読み比べなければなりません。原因候補が見つかっても、テストをどの階層に置くべきかは別の判断です。単体テストで十分なのか、APIテストやブラウザテストが必要なのかを、再発時に壊れる境界から考えます。
既存テストの調査にも手間がかかります。利用中のフレームワークを知るだけでなく、ファイル名、セットアップ処理、テストデータ、非同期処理、アサーション、後片付けの慣例を確認するためです。公式のClaude Code Docsでは、検証したい振る舞いを具体的に伝えると、Claudeが既存テストを調べ、プロジェクトのスタイル、フレームワーク、アサーションのパターンに合わせたテストを生成できると説明されています。また、エラー条件、境界値、予期しない入力などの見落としやすいケースを提案させる使い方も示されています（出典: Claude Code Docs）。
ただし、候補を多く出せることと、必要な回帰テストを正しく選べることは同じではありません。担当者は、報告された現象を最小条件で再現できるか、テストが将来の実装変更を不必要に妨げないかを判断します。Claude Codeが減らしやすいのは資料探しと横断調査の往復であり、仕様の確定や合否判定は残る、という分担が現実的です。
従来工程とClaude Codeを使う工程の対応
比較条件をそろえるため、入力は同じ不具合報告、再現手順、期待結果、対象リポジトリとします。成果物も同じで、不具合を再現する回帰テスト、必要最小限の修正差分、検証結果の記録です。品質条件は、修正前の問題を捉えること、修正後に通ること、既存テストを不必要に壊さないこと、プロジェクトの慣例に従うこととします。AIの有無によって、要求水準を下げない比較が必要です。| 工程 | AIを使わない場合 | Claude Codeで補助する場合 | 人が残す判断 |
|---|---|---|---|
| 条件整理 | 報告とログを読み、観点をメモします | 不足情報と再現条件の候補を列挙させます | 事実と推測を分け、条件を確定します |
| 原因調査 | 検索とファイル閲覧を繰り返します | 関連箇所と処理経路を調査させます | 原因候補が現象を説明するか確認します |
| 既存テスト調査 | 似たテストを手作業で探します | 類似テストと慣例をまとめさせます | 採用するテスト階層を選びます |
| テスト作成 | 雛形を転記して書き換えます | 既存形式に沿う差分案を作らせます | アサーションとテスト範囲を承認します |
| 検証 | コマンドを実行し結果を読みます | 実行結果の整理を補助させます | 失敗理由と回帰の有無を判定します |
変化の中心は、複数ファイルから情報を集めて一つのテスト案へまとめる工程です。担当者が毎回ファイルを開いて慣例を転記する代わりに、Claude Codeへ「変更前に、関連実装と類似テストを読み、候補と根拠を示してください」と依頼できます。公式ドキュメントでは、編集前に計画を確認したい場合、プランモードでClaudeにファイルを読ませ、承認まで編集させない流れが案内されています（出典: Claude Code Docs）。原因が確定していない段階では、この読み取り中心の進め方が適しています。
省略できない工程も明確です。不具合報告の正しさ、期待結果が製品仕様に合うか、個人情報や秘密情報を入力してよいか、どのテスト層が保守方針に合うかは、組織と担当者が決めます。生成された差分のレビュー、修正前にテストが失敗することの確認、修正後の成功、関連テストへの影響確認も必要です。Claude Codeは判断材料を集約できますが、承認責任を引き受けるものではありません。
調査を始める前にそろえる入力と境界
準備では、AIへ渡す情報を増やすことより、事実と未確認事項を分けることが重要です。不具合票から、対象画面または機能、再現前提、操作手順、期待結果、実際の結果、エラー表示、発生が確認された環境を抜き出します。顧客名、認証情報、本番データなど、調査に不要な機密情報は含めません。ログを使う場合も、組織の取り扱い規程に沿って必要部分だけを渡します。リポジトリ側では、READMEや開発者向け文書、テスト設定、対象機能に近い既存テストを確認できる状態にします。テストの実行方法は、記事中の架空のコマンドではなく、そのプロジェクトのREADME、パッケージ設定、CI設定に記載されたものを正とします。作業開始時の差分も確認し、既存の未コミット変更と今回の変更を混ぜないようにします。ブランチ作成や退避方法はチームの運用規則に従ってください。
Claude Codeへの境界条件として、最初は読み取り調査だけを依頼し、アプリケーションコードやテストを変更しないよう明記する方法が考えられます。これは本稿で提案する運用例です。調査結果には、関連ファイル、処理経路、類似テスト、原因候補、追加で必要な情報を含めてもらいます。断定できない点には「仮説」と付けさせると、観測事実との混同を避けやすくなります。
受け入れ条件も先に短く書きます。たとえば、「報告された条件を一つのテストで再現する」「外部サービスへの通信は既存方針に従って代替する」「不具合と無関係なリファクタリングは行わない」「テスト名から利用者に見える振る舞いが分かる」といった条件です。ここまで準備しておけば、Claude Codeの出力が詳しくても、採用範囲を見失いにくくなります。
読み取り調査からテスト案へ進める操作手順
Claude Codeを対象リポジトリで利用できる状態にしたら、編集を始める前にプランモードを使い、調査と提案を依頼します。公式ドキュメントでは、プランモード中はClaudeがファイルを読み、承認されるまで編集しない流れが説明されています。また、セッション中はShift+Tabでステータス表示がプランモードになるまで切り替える方法が案内されています（出典: Claude Code Docs）。利用環境の表示を確認し、意図したモードであることを確かめてください。最初の依頼には、再現手順と期待結果だけでなく、変更禁止の範囲と欲しい報告形式も入れます。次の文面は公式の固定プロンプトではなく、コピーして調整できる実務上の例です。
```text
既存Webアプリの不具合に対する回帰テストを追加したいです。まだファイルは変更せず、読み取り調査だけを行ってください。
不具合:
- 対象機能: 問い合わせ編集画面の保存
- 前提: 閲覧権限と編集権限を持つ利用者です
- 再現手順: 必須項目を入力し、任意項目を空欄にして保存します
- 期待結果: 保存が成功し、一覧に更新内容が表示されます
- 実際の結果: 保存処理が失敗します
調査してほしいこと:
1. この処理に関係する画面、API、検証、保存処理のファイル
2. 現象を説明できる原因候補と、その根拠
3. 最も近い既存テストと、命名・準備・アサーションの慣例
4. 回帰テストを置く適切な階層と理由
5. 最小のテスト案、必要なテストデータ、想定する失敗内容
6. 不足情報と、追加で確認すべき境界条件
事実と仮説を分けて報告してください。不具合と無関係な変更は提案しないでください。
```
報告を受けたら、担当者が原因候補と類似テストを開き、説明がコードと一致するか確認します。疑問が残る場合は、すぐに編集を許可せず、「候補Aと候補Bのどちらが実際の分岐を通るか、呼び出し元から追ってください」のように範囲を絞って追加調査を依頼します。計画に納得できた段階で、テストファイルだけを対象にし、既存形式へ合わせた最小差分を作るよう依頼します。
テスト作成後は、プロジェクトで定められた対象テストの実行方法を使います。修正前の状態または不具合条件を安全に再現できる状態で、追加テストが意図した理由により失敗することを確認します。その後に別途承認された不具合修正を適用し、対象テストが通ることを確かめます。テスト追加と本体修正を同時に大きく進めるより、赤と緑の根拠を段階ごとに残すほうがレビューしやすいでしょう。
生成された回帰テストを人が承認する基準
成果物の形はプロジェクトのテスト基盤によって異なりますが、確認すべき構造は共通しています。テスト名には利用者から見た条件と結果が表れ、準備では再現に必要なデータだけを用意し、操作では実際に問題が起きた経路を通し、検証では期待される外部的な振る舞いを確認します。次の例はテストコードそのものではなく、レビュー時に使える振る舞いの骨子です。```text
前提: 編集可能な問い合わせと権限を持つ利用者を用意します
操作: 任意項目を空欄にしたまま保存処理を実行します
期待: 保存が成功し、更新内容を再取得できます
確認: 不要な外部通信や別機能への依存を追加していません
```
最初に見るのは、テストが修正前の不具合を本当に捉えるかです。失敗したという事実だけでは足りません。設定漏れ、テストデータの誤り、環境依存などではなく、報告された欠陥によって失敗していることを、メッセージや実行経路から確認します。修正後に通った場合も、アサーションを弱めたために通っていないかを見ます。常に真になる条件や、例外を握りつぶす処理が追加されていれば回帰テストとして機能しません。
差分レビューでは、既存テストの命名、セットアップ、モック、後片付けに沿っているかを確認します。内部関数の呼び出し回数だけを固定すると、利用者に見える挙動が同じでもリファクタリングで壊れる場合があります。今回守りたいのが保存結果なら、可能な範囲でその結果を検証し、偶然の実装詳細への依存を避けます。類似テストと重複しすぎていないか、逆に条件をまとめすぎて失敗原因が分からなくなっていないかも判断材料です。
過剰修正の有無も人が確認します。回帰テストの追加依頼なのに、無関係なファイルの整形、依存関係の更新、広範な名称変更が含まれていれば、いったん分離を求めます。対象テストに加えて関連する既存テストを実行し、必要に応じてチーム標準の広い検証も行います。最終承認では、実行したコマンド、成功・失敗の結果、未確認範囲を記録し、AIの説明ではなく観測した証拠を根拠にします。
小さな不具合一件で効果を測る方法
導入効果は「AIを使ったから速かった」という印象ではなく、工程ごとの記録で確かめます。最初の試行では、範囲が明確で、手動の再現手順が既にある不具合を一件選ぶと比較しやすくなります。重大障害や仕様が未確定の案件を初回に選ぶと、AIの効果よりも調整や意思決定の負担が大きくなり、評価が難しくなります。記録する項目は、再現条件の整理、関連コードの特定、既存テスト調査、テスト下書き、レビュー、修正、テスト実行です。各工程について、開始から終了までの時間だけでなく、開いたファイル数、Claude Codeへの追加質問回数、生成案の修正理由、レビューで見つかった問題を残します。実測していない削減率を置く必要はありません。従来の類似案件と入力、成果物、品質条件が近い場合に限り、どの往復が減ったかを比較します。
期待できる変化は条件付きです。既存テストが整理され、再現条件が具体的であれば、類似例の探索と下書きの反復をまとめやすくなります。反対に、仕様が曖昧でテスト基盤にも一貫性がない場合は、Claude Codeへの説明や生成結果の修正が増えるでしょう。それでも、不明点や既存慣例を一覧にする調査結果が残れば、次の保守作業に使える材料になります。
最初の一歩は、本体コードの修正まで一度に任せることではありません。未解決の不具合一件について、再現手順と期待結果を用意し、プランモードで関連ファイルと類似テストの調査だけを依頼してください。その報告を担当者が採点し、根拠の正確さ、見落とし、確認に要した手間を記録します。調査品質に納得できた場合だけ、次の段階でテストファイルの最小差分へ進めます。この順序なら、準備、確認、修正を含む総負担を見ながら、自社の保守工程に合う使い方を判断できます。