なぜ指示の出し方が重要なのか

Claude Codeに「いい感じに作って」と指示しても、期待通りの結果は得られません。 プロンプトの書き方一つで、生成されるコードの品質は大きく変わります。 この記事では、初心者でもすぐに使えるプロンプトテクニックを解説します。

Claude Codeの基本操作がまだの方は、先に基本コマンド一覧を確認してください。

良い指示と悪い指示のBefore/After

ケース1：新しい機能を追加する

Before（悪い指示）：

ログイン機能を作って

この指示では、以下が不明です。

• 認証方式（メール？OAuth？）
• UIデザイン
• バリデーションルール
• エラーハンドリング

After（良い指示）：

メールアドレスとパスワードによるログイン機能を作ってください。

要件:
- NextAuth.jsを使用
- Credentials providerでメール+パスワード認証
- バリデーション: メール形式チェック、パスワード8文字以上
- ログインフォームはsrc/app/login/page.tsxに配置
- エラー時はフォーム上部にエラーメッセージを表示
- ログイン成功後は/dashboardにリダイレクト

結果の違い：

ケース2：バグを修正する

Before（悪い指示）：

ボタンが動かないので直して

After（良い指示）：

src/components/SubmitButton.tsxの送信ボタンをクリックしても
フォームが送信されません。

現象:
- ボタンをクリックしてもonSubmitが発火しない
- コンソールにエラーは出ていない
- 昨日までは動いていた

最近の変更:
- フォームのバリデーションロジックを追加した

原因を調査して修正してください。

バグ修正の指示では「現象・再現手順・最近の変更」の3点セットが重要です。

ケース3：リファクタリング

Before（悪い指示）：

コードを綺麗にして

After（良い指示）：

src/utils/api.tsをリファクタリングしてください。

改善したい点:
- 同じfetch処理が5箇所で重複している → 共通関数に切り出す
- エラーハンドリングがtry-catchで統一されていない → 統一する
- 型定義がanyになっている箇所がある → 適切な型に変更

変更しないでほしい点:
- 既存のAPI呼び出しの引数と戻り値の型は変えない
- テストが通る状態を維持する

「何を変えるか」だけでなく「何を変えないか」も伝えると安全です。

3つの基本原則

原則1：具体的に書く

曖昧な言葉を具体的な言葉に置き換えましょう。

原則2：構造的に書く

情報を整理して伝えましょう。

【目的】ユーザープロフィール編集画面を作る

【技術要件】
- React Hook Formでフォーム管理
- Zodでバリデーション
- 画像アップロード対応（最大5MB、JPG/PNG）

【UIの要件】
- 既存のデザインシステムに合わせる
- src/components/ui/のコンポーネントを使用
- レスポンシブ対応

【バリデーションルール】
- 名前: 必須、50文字以内
- メール: 必須、メール形式
- 自己紹介: 任意、500文字以内

箇条書きとカテゴリ分けで、Claude Codeが情報を正確に把握できます。

原則3：段階的に進める

複雑なタスクは一度に指示せず、段階的に進めましょう。

ステップ1: 「データベーススキーマを設計して」
    ↓ 確認・修正
ステップ2: 「APIエンドポイントを実装して」
    ↓ 確認・修正
ステップ3: 「フロントエンドのUIを作って」
    ↓ 確認・修正
ステップ4: 「テストを書いて」

各ステップで確認を挟むことで、手戻りを最小化できます。

5つのプロンプトパターン

実際の開発でよく使うパターンをテンプレート化しました。

パターン1：機能実装

【機能名】を実装してください。

技術スタック:
- （使用するライブラリ）

要件:
- （箇条書きで要件を列挙）

ファイル配置:
- （ファイルパスを指定）

注意点:
- （制約や既存コードとの整合性）

パターン2：バグ修正

【ファイルパス】で【現象】が発生しています。

再現手順:
1. （手順1）
2. （手順2）
3. （手順3）

期待する動作: （こうなるべき）
実際の動作: （こうなっている）

エラーメッセージ:
```（エラーログ）```

原因を調査して修正してください。

パターン3：リファクタリング

【ファイルパス】をリファクタリングしてください。

改善目的:
- （可読性向上、パフォーマンス改善、など）

改善したい点:
- （具体的な問題点を列挙）

変更しないでほしい点:
- （維持すべき仕様や型）

テスト: 既存テストが通る状態を維持すること

パターン4：テスト作成

【ファイルパス】のテストを作成してください。

テストフレームワーク: （Jest / Vitest / etc.）

テストケース:
- 正常系: （期待する動作）
- 異常系: （エラーケース）
- 境界値: （0件、上限値など）

モック:
- （外部依存のモック方法）

パターン5：コードレビュー

以下の変更をレビューしてください。

確認してほしい観点:
- セキュリティ上の問題はないか
- パフォーマンスに懸念はないか
- TypeScriptの型定義は適切か
- エッジケースの考慮漏れはないか

変更の目的: （何のための変更か）

CLAUDE.mdとの組み合わせ

CLAUDE.mdに共通ルールを書く

毎回同じ指示を繰り返すのは非効率です。 CLAUDE.mdに共通ルールを書いておけば、プロンプトがシンプルになります。

CLAUDE.mdの例：

# プロジェクトルール

## 言語
- 日本語で応答すること
- コメントは日本語で書くこと

## コーディング規約
- TypeScript strictモードを使用
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- スタイリングはTailwind CSSのみ使用
- 命名規則: コンポーネントはPascalCase、関数はcamelCase

## ファイル配置
- コンポーネント: src/components/
- フック: src/hooks/
- 型定義: src/types/
- ユーティリティ: src/utils/

## テスト
- テストフレームワーク: Vitest
- テストファイルは __tests__/ ディレクトリに配置

CLAUDE.mdがある場合のプロンプト

CLAUDE.mdにルールを書いておくと、指示がシンプルになります。

CLAUDE.mdなしの場合：

ユーザー一覧コンポーネントを作ってください。
TypeScript strictモードで、関数コンポーネントで、
Tailwind CSSでスタイリングして、
src/components/に配置して、
コメントは日本語で...

CLAUDE.mdありの場合：

ユーザー一覧コンポーネントを作ってください。

表示項目: 名前、メール、登録日
機能: ページネーション、検索フィルタ

共通ルールはCLAUDE.mdに任せて、タスク固有の要件だけを伝えます。

CLAUDE.mdの詳しい書き方はCLAUDE.md活用ガイドを参照してください。

会話の流れを活かすテクニック

テクニック1：前の結果を踏まえて追加指示

Claude Codeは会話の文脈を覚えています。 前の応答を踏まえた追加指示が効果的です。

1回目: 「ユーザー一覧APIを作って」
  → APIが生成される

2回目: 「それにページネーションを追加して」
  → 既存コードを修正してくれる

3回目: 「ソート機能も追加して。名前と登録日でソートできるように」
  → さらに機能を追加してくれる

「それ」「これ」で前の文脈を参照できます。

テクニック2：確認してから進む

大きな変更の前に、方針を確認しましょう。

認証機能を追加したいです。
NextAuth.jsとSupabase Authのどちらがこのプロジェクトに
適しているか、メリット・デメリットを教えてください。
実装はまだしないでください。

「実装はまだしないでください」が重要です。 方針を確認してから実装に進むと、手戻りが減ります。

テクニック3：エラーをそのまま貼る

エラーが出たら、メッセージをそのまま貼り付けましょう。

npm run buildしたら以下のエラーが出ました。修正してください。

Type error: Property 'email' does not exist on type 'User'.

  45 |   return (
  46 |     <div>
> 47 |       <p>{user.email}</p>
     |              ^
  48 |     </div>
  49 |   );

エラーメッセージを加工する必要はありません。 Claude Codeがコンテキストから原因を特定して修正します。

テクニック4：参考コードを見せる

既存のコードパターンに合わせてほしい場合は、参考を示しましょう。

src/components/UserCard.tsxと同じパターンで、
ProductCard.tsxを作ってください。

表示項目: 商品名、価格、画像、在庫状況

「同じパターンで」と指示すると、既存コードのスタイルに合わせてくれます。

よくある失敗と対処法

失敗1：一度にすべてを指示する

❌ ECサイト全部を作って。ユーザー認証、商品一覧、カート、
   決済、注文履歴、管理画面、メール通知...

Claude Codeは一度に大量の指示を受けると、品質が下がります。

✅ まず商品一覧ページから作りましょう。
   以下の仕様で実装してください...

失敗2：コンテキストを伝えない

❌ 修正して

何を修正するのか、どこが問題なのかが不明です。

✅ src/app/api/users/route.tsのGETエンドポイントで、
   削除済みユーザーもレスポンスに含まれてしまっています。
   deletedAtがnullのユーザーのみ返すように修正してください。

失敗3：矛盾する指示を出す

❌ シンプルに作って。でも全機能をカバーして。
   パフォーマンスも最高にして。

矛盾する要件はClaude Codeを混乱させます。

✅ まずMVP版をシンプルに作ってください。
   パフォーマンス最適化は後のステップで行います。

   MVP要件:
   - ユーザー登録
   - ログイン
   - プロフィール表示

優先順位を明確にしましょう。

プロンプトの実践例集

実践例1：API実装

RESTful APIを実装してください。

エンドポイント: /api/posts
メソッド: GET, POST, PUT, DELETE

GETの仕様:
- クエリパラメータ: page, limit, sort, search
- レスポンス: { posts: Post[], total: number }
- デフォルト: page=1, limit=20

POSTの仕様:
- リクエストボディ: { title: string, content: string }
- バリデーション: title必須(100文字以内)、content必須
- レスポンス: 作成されたPost

エラーハンドリング:
- 400: バリデーションエラー
- 404: リソースが見つからない
- 500: サーバーエラー

実践例2：デザイン修正

src/app/page.tsxのヒーローセクションを改善してください。

現状の問題:
- モバイルで文字が小さすぎる
- CTAボタンが目立たない

改善内容:
- 見出し: モバイルtext-2xl → デスクトップtext-5xl
- CTAボタン: 背景をgradient(blue-500→purple-600)に変更
- ボタンサイズ: パディングを大きくする（py-4 px-8）
- ホバー時にスケールアニメーションを追加

実践例3：パフォーマンス改善

このプロジェクトのパフォーマンスを改善してください。

現状:
- Lighthouseスコア: Performance 65
- LCP: 4.2秒
- 画像が最適化されていない

やってほしいこと:
1. next/imageコンポーネントへの置き換え
2. 不要なクライアントコンポーネントのサーバーコンポーネント化
3. dynamic importによるコード分割
4. フォント読み込みの最適化

対象ファイル: src/app/ 配下のすべてのページ

まとめ

Claude Codeへの指示で重要なポイントです。

• 具体的に書く：曖昧な表現を避け、数値や名前で指定する
• 構造的に書く：箇条書きとカテゴリ分けで情報を整理する
• 段階的に進める：大きなタスクは分割し、確認を挟む
• CLAUDE.mdを活用する：共通ルールを書いておき、毎回の指示を簡潔にする
• 5つのパターンを覚える：機能実装、バグ修正、リファクタリング、テスト、レビュー

次のステップとして、以下の記事もおすすめです。

• Claude Codeで最初のプロジェクトを作ろう - 実践で試す
• Claude Codeとは？ - 基本を復習する
• 非エンジニア向けClaude Code活用ガイド - 技術者以外の活用法