Article

Claude CodeにWebアプリ開発を頼むときのプロンプトテンプレート集：新機能・バグ修正・UI改善・テスト・レビュー

Claude CodeでWebアプリ開発を進めるときに、コピペで使える依頼文テンプレートをまとめます。新規機能追加、バグ修正、UI改善、テスト追加、レビュー依頼の5タイプを、目的・前提・制約・受け入れ条件まで揃えた形で公開ベストプラクティスに沿って整理します。

This article is not published in this language yet, so the Japanese version is shown instead.

結論：Web開発の依頼は「目的・前提・制約・受け入れ条件」を埋めるだけにする

Claude CodeにWebアプリ開発を頼むときに、毎回ゼロから依頼文を書くのは効率が悪いです。本記事では、**5つの定番タスク（新規機能／バグ修正／UI改善／テスト追加／レビュー依頼）**をテンプレ化し、変数を埋めるだけで使える形に整理します。

ベースとしている考え方は、依頼文を目的・背景・入力・制約・出力・完了条件・禁止事項の7ブロックで書くプロンプトの基本構造と、検証可能性を最優先する受け入れ条件の作り方です。本記事はそれをWeb開発のシーン別にあてはめた早見表として使ってください。

公式のBest Practicesでは、「Give Claude a way to verify its work」（検証手段を与える）が単体で最も効果が高いと明言されています。各テンプレに実行可能な検証コマンドを入れているのはそのためです。

共通の前提：CLAUDE.mdに書く内容を分ける

テンプレートを使う前に、毎回書かなくてよい情報はCLAUDE.mdへ集約しておく前提です。次の情報はCLAUDE.md側に置き、依頼文には書かないようにします。

フレームワーク（Astro / React / Next.jsなど）
コードスタイル（インデント、import形式、命名）
テストランナー（Vitest / Jestなど）
ビルド・型チェック・リントの実行コマンド
レビュー観点と禁止事項

依頼文ではそのタスク固有の情報だけを書く運用にすると、毎回の依頼が短くなり、ミスも減ります。

テンプレ1: 新規機能追加

新機能を1機能ぶん追加する依頼です。1〜3ファイル／30分〜2時間で終わる粒度にタスク分解してから流すのが前提です。

## 目的
{何を作るか1文}（例: 商品詳細ページに在庫数バッジを追加する）

## 背景
- 想定ユーザー: {誰が何のために使うか}
- 既存実装: @{参照ファイル} を踏襲
- 関連UI: @{デザイン画像 or ページのスクリーンショット}

## 入力
- 触るファイル: src/components/ProductCard.tsx, src/lib/inventory.ts
- 触らないファイル: src/api/(認証まわりは別タスク)

## 制約
- 既存のpropsシグネチャは変えない
- 新規依存パッケージは追加禁止
- スタイルは既存のCSS変数（--color-warning など）を使う

## 出力
- ProductCardに在庫数バッジを表示
- 在庫0件のとき「在庫切れ」表示
- 在庫1〜3件のとき「残りN件」表示

## 完了条件
- `npm test -- src/components/ProductCard` が緑
- 追加テストが3件以上（在庫0／1〜3／10以上）
- `npm run typecheck` が緑
- `npm run lint` が緑

## 禁止事項
- スタイルの大規模リファクタ
- 関係のないファイルへの「ついで修正」
- 認証・カート機能への変更

Plan Modeで先に計画を作らせ、承認してから実装に移すと安全です。

テンプレ2: バグ修正

公式ベストプラクティスは、バグ修正で**「症状・想定箇所・直った状態」**を渡すよう推奨しています。再現テストを先に書かせるのが事故を減らすコツです。

## 目的
{バグの症状}を直す（例: ログイン後にカート内容が消える）

## 再現手順
1. /login で test@example.com でログイン
2. /products で商品Aをカートに入れる
3. ページをリロード
4. /cart を開く
5. → カートが空になっている（期待: 商品Aが残る）

## エラーログ／観測
- ブラウザコンソールに `Cookie SameSite=Strict warning` が出る
- セッションCookieは2回目のリクエストで無くなっている

## 想定される箇所
- src/middleware/auth.ts のCookie設定
- src/lib/cart-store.ts の永続化処理

## 制約
- 認証フローは変更しない（別タスク）
- Cookie設定は既存のenv変数 SESSION_COOKIE_SECURE を尊重

## 進め方
1. まず再現する**失敗テスト**をtests/integration/cart.test.tsに追加してください
2. テストが赤になることを確認した上で、原因仮説と修正計画を提示
3. 私が承認したら修正を実装

## 完了条件
- 追加した失敗テストが緑になる
- 既存の `npm test` が壊れていない
- `npm run typecheck` が緑

**「失敗テスト先行」**を依頼に明記すると、症状を想像で直すのではなく、再現可能な形で固定できます。

テンプレ3: UI改善

UI改善はスクリーンショットを直接貼るのが一番効きます。Claude Codeは画像入力に対応しており、公式ベストプラクティスでも**「[paste screenshot] implement this design」**の例が示されています。

## 目的
商品一覧ページのカードをモバイルで見やすくする

## 現状と理想
- 現状: [現状のスクリーンショット画像を貼る]
- 理想: [Figma export または手描きスケッチを貼る]

## 触るファイル
- src/components/ProductGrid.tsx
- src/components/ProductCard.tsx
- src/styles/product-grid.css

## 制約
- ブレークポイントは既存の sm(640px)/md(768px)/lg(1024px) を使う
- アクセシビリティ: タップ領域は44pxを下回らない
- ダークモード対応を維持
- 新規依存パッケージは追加禁止

## 進め方
- 実装後、`npm run dev` でローカルを起動し、
  Chrome devtoolsで 375px / 768px / 1280px のスクリーンショットを撮って差分を報告してください

## 完了条件
- 3つのブレークポイントでスクリーンショットを取得
- 各サイズで「重なり」「文字あふれ」「タップ領域不足」が無いと自己確認
- `npm run typecheck` と `npm run lint` が緑

Claude in Chrome拡張が使える環境なら、Claude自身がブラウザを開いてスクリーンショット取得・差分検出まで行わせる依頼に置き換えられます。

テンプレ4: テスト追加

公式ドキュメントのCommon Workflowsでは、未カバー領域の特定→テストひな形→エッジケース→実行という流れが提案されています。それを依頼文に落とし込みます。

## 目的
src/services/order/ の未カバー関数にユニットテストを追加する

## 入力
- 対象ディレクトリ: src/services/order/
- 既存テスト: tests/services/order/
- 既存テストのスタイル: it("should ...", () => {})

## 制約
- モックは使わない（実DBはdocker compose up で立ち上げ済み）
- テスト用シードは tests/fixtures/orders.ts を使う
- テストごとに beforeEach で truncate

## 進め方
1. 未カバー関数の一覧と、各関数のエッジケース候補を提示
2. 私が優先度を選ぶ
3. 選んだ関数からテストを書き、`npm test` で1件ずつ通す

## 完了条件
- 各対象関数に正常系1件＋エッジケース2件以上
- カバレッジが90%以上（lib/coverage/lcov-report/index.htmlで確認）
- `npm test` 全体が緑
- 新規依存パッケージは追加無し

ポイントは**「モック禁止」「実DB前提」**のように、どの種類のテストを書いてほしいかを明記することです。Claudeはこのヒントが無いと、安易にモックで埋めて見かけのカバレッジだけ上げる解に流れがちです。

テンプレ5: レビュー依頼（Writer/Reviewerパターン）

実装と別セッションでレビュー専用の依頼を投げると、書き手のバイアスを避けられます。公式ベストプラクティスでも、Writer/Reviewerパターンが紹介されています。

## 目的
このPRの差分をレビューする（実装は私 or 別セッションが行いました）

## 対象
- 変更ファイル: 以下のdiffを参照
- @PR_DIFF.md（gh pr diff の出力を保存したもの）

## レビュー観点（優先順）
1. セキュリティ: 入力検証、認可、秘密情報、SQLインジェクション
2. ロジック: 仕様との一致、エッジケース、例外処理
3. パフォーマンス: 不要なN+1、ループ内fetch、メモリ
4. テスト: カバレッジ、モックの妥当性、flaky条件
5. 可読性: 命名、責務分離、依存追加の妥当性

## 出力
- 重要度（High/Med/Low）付きの指摘リスト
- 各指摘に対し file:line と修正案（diff形式）
- 全体所感を3行以内

## 制約
- 実装はしない（指摘のみ）
- 推測で「ここは多分こうしたほうが良い」を書かない
- 公式ドキュメント等の根拠が示せるなら添える