Claude Codeのプロンプト術 - 効率的な指示の出し方

Claude Codeはターミナル上で動作するAIエージェントで、コードベースの理解・編集・Git操作などを自然言語の指示で実行できる。指示の書き方次第で出力の品質と作業効率が大きく変わるため、効果的なプロンプトのパターンを整理する。

良い指示の基本原則

原則説明
具体的に書く「直して」ではなく「何を」「どう」直すかを明示する
範囲を限定する対象ファイル・関数・行範囲を指定する
期待する出力を示す最終的にどうなっていればよいかを伝える
制約を明記する使用ライブラリ、コーディング規約、変更してはいけない箇所を指定する
一度に一つの目的複数の目的を混ぜず、一つずつ指示する

悪い指示 vs 良い指示（Before / After）

パターン1: バグ修正

❌ Bad:
ログイン機能がバグってるから直して

✅ Good:
src/auth/login.ts の handleLogin 関数で、パスワードが空文字の場合に
バリデーションエラーが発生せずAPIリクエストが送信される問題を修正してください。
空文字の場合は「パスワードを入力してください」のエラーメッセージを表示してください。

改善ポイント: 対象ファイル・関数名、再現条件、期待する動作を明示している。

パターン2: 新機能追加

❌ Bad:
ダークモードを追加して

✅ Good:
MUIのテーマ切り替え機能を使って、ダークモードを追加してください。
- src/theme/index.ts にダークテーマの定義を追加
- Header.tsx にトグルボタンを配置（IconButton + Brightness4Icon）
- テーマ状態はlocalStorageに保存し、リロード時に復元
- 既存のプライマリカラー #1d7997 はダークモードでも維持

改善ポイント: 実装方針・使用コンポーネント・状態管理の方法・デザイン制約を具体的に指定している。

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

❌ Bad:
このコードをきれいにして

✅ Good:
src/utils/helpers.ts の formatDate 関数群を以下の方針でリファクタリングしてください。
- date-fns を使わず、Intl.DateTimeFormat に統一
- 各関数のJSDocコメントを追加
- 既存のテスト (helpers.test.ts) が通ることを確認
- 関数のインターフェース（引数・戻り値の型）は変更しない

改善ポイント: リファクタの方向性、使用する手法、変更してはいけない境界を明確にしている。

パターン4: コードレビュー

❌ Bad:
このPRレビューして

✅ Good:
PR #42 の変更内容をレビューしてください。以下の観点で確認をお願いします。
- SQLインジェクションなどのセキュリティリスク
- エラーハンドリングの漏れ
- 型定義の適切さ（any の使用がないか）
- 既存のコーディング規約（Prettierの設定）との整合性

改善ポイント: レビュー観点を列挙し、何を重点的に見るかを伝えている。

パターン5: テスト作成

❌ Bad:
テスト書いて

✅ Good:
src/utils/validation.ts の validateEmail 関数のユニットテストを作成してください。
- テストファイル: src/utils/__tests__/validation.test.ts
- テストフレームワーク: Vitest
- 以下のケースをカバー:
  - 正常なメールアドレス（user@example.com）
  - @がないケース
  - ドメインがないケース
  - 空文字
  - 日本語を含むケース

改善ポイント: テストファイルの配置場所、フレームワーク、具体的なテストケースを指定している。

パターン6: ドキュメント作成

❌ Bad:
READMEを更新して

✅ Good:
README.md の「セットアップ」セクションに以下を追記してください。
- Node.js 20以上が必要であること
- pnpm install の後に pnpm db:migrate が必要であること
- .env.example を .env にコピーして環境変数を設定する手順
既存の記述スタイル（見出しレベル、箇条書きの形式）に合わせてください。

改善ポイント: 追記する内容と場所を具体的に指定し、既存スタイルへの準拠を指示している。

パターン7: パフォーマンス改善

❌ Bad:
このページ遅いから速くして

✅ Good:
src/pages/Dashboard.tsx の初回レンダリングが遅い問題を改善してください。
原因として、useEffect内で3つのAPIを直列で呼んでいる箇所が疑われます。
- Promise.all で並列化
- 各APIレスポンスにはReact Queryのキャッシュを適用（staleTime: 5分）
- コンポーネントの再レンダリングを React.memo で抑制

改善ポイント: 推定原因と具体的な改善手法を示しており、Claude Codeが方向性を迷わない。

タスクの分割

大きな変更を一つの指示で依頼すると、意図しない変更が混入したり、途中でコンテキストが曖昧になりやすい。タスクを分割して段階的に進めるのが効果的。

分割の例: 認証機能の追加

# Step 1: データ層
src/types/auth.ts にUser型とAuthState型を定義してください。
User: id(string), email(string), name(string), role('admin' | 'user')
AuthState: user(User | null), isLoading(boolean), error(string | null)

# Step 2: 状態管理（Step 1の完了後）
src/stores/authStore.ts にZustandストアを作成してください。
Step 1で定義した型を使い、login/logout/setErrorアクションを実装してください。

# Step 3: API層（Step 2の完了後）
src/api/auth.ts にログインAPIの呼び出し関数を実装してください。
エンドポイント: POST /api/auth/login
レスポンスをauthStoreに反映する処理も含めてください。

# Step 4: UI（Step 3の完了後）
src/pages/Login.tsx にログインフォームを作成してください。
MUI の TextField と Button を使い、Step 3のAPI関数を呼び出してください。

各ステップの完了を確認してから次に進むことで、問題の切り分けが容易になる。

コンテキストの与え方

Claude Codeはカレントディレクトリのファイルを自動的に読めるが、どのファイルが関連するかを明示すると精度が上がる。

ファイルパスの指定

# 対象ファイルを明示
src/components/UserList.tsx を修正してください。

# 関連ファイルも伝える
src/components/UserList.tsx を修正してください。
型定義は src/types/user.ts、APIは src/api/users.ts を参照してください。

既存コードのパターンを示す

src/pages/About.tsx と同じ構成で src/pages/Contact.tsx を作成してください。
- Helmet によるメタタグ設定
- Container + Typography のレイアウト
- 下部のコンテンツセクション（使い方・FAQ）

エラーメッセージを含める

以下のTypeScriptエラーを修正してください。

ファイル: src/hooks/useAuth.ts:24
エラー: Type 'string | undefined' is not assignable to type 'string'.

user.email が undefined になりうるケースのハンドリングを追加してください。

制約の伝え方

制約を明記することで、意図しない変更を防げる。

よく使う制約パターン

制約の種類指示例
ライブラリ制約「axiosではなくfetch APIを使ってください」
スタイル制約「既存のPrettier設定（.prettierrc）に従ってください」
変更範囲制約「このファイルの既存の関数は変更しないでください」
互換性制約「既存のAPIレスポンス形式を変更しないでください」
パフォーマンス制約「バンドルサイズが増える外部ライブラリは追加しないでください」
命名規約「コンポーネント名はPascalCase、関数名はcamelCaseで統一してください」

CLAUDE.md による制約の永続化

プロジェクトルートに CLAUDE.md を配置すると、Claude Codeが自動的に読み込む。繰り返し伝える必要のある制約はここに書く。

# プロジェクトルール

## コーディング規約
- セミコロンなし、シングルクォート（Prettier設定に準拠）
- コンポーネントはアロー関数で定義
- 型定義はinterfaceよりtypeを優先

## 禁止事項
- any型の使用禁止
- console.logの本番コードへの残存禁止
- default exportの使用禁止（named exportのみ）

CLAUDE.md の配置場所による優先度:

配置場所スコープ用途
~/.claude/CLAUDE.md全プロジェクト共通共通の作業ルール
プロジェクトルート/CLAUDE.mdプロジェクト固有コーディング規約、技術スタック
サブディレクトリ/CLAUDE.mdディレクトリ固有特定モジュールのルール

レビュー・修正の指示方法

Claude Codeの出力に対して追加の修正を依頼する場合も、具体的に伝える。

# 方向性の修正
今の実装だとコンポーネントが大きすぎるので、
UserList（一覧表示）と UserListItem（個別行）に分割してください。

# 部分的な修正
エラーハンドリングの部分だけ修正してください。
catch節で error が unknown 型なので、instanceof Error でチェックしてから
message を参照するようにしてください。

# スタイルの修正
動作は問題ないですが、以下のスタイルを修正してください。
- インデントが4スペースになっている箇所を2スペースに統一
- 未使用のimport文を削除

複数ファイルにまたがる変更

複数ファイルを同時に変更する場合は、変更の全体像を先に示す。

ユーザー削除機能を追加してください。以下のファイルを変更します。

1. src/types/user.ts - DeleteUserRequest型を追加
2. src/api/users.ts - deleteUser関数を追加（DELETE /api/users/:id）
3. src/stores/userStore.ts - deleteUserアクションを追加
4. src/components/UserList.tsx - 各行に削除ボタンを追加
5. src/components/UserList.tsx - 削除確認ダイアログを追加

削除後はリストを再取得せず、ローカルのstateから該当ユーザーを除外してください。

変更ファイルのリストと各ファイルでの変更内容を一覧にすることで、Claude Codeが全体の整合性を保ちやすくなる。

planモードの活用

大規模な変更や設計判断が必要な場合は、plan モードで事前に計画を立てさせる。

使い方

# shift+tab で plan モードに切り替えてから指示する
認証機能をJWT + refresh tokenで実装したい。
既存のコードベースを確認して、実装計画を立ててください。

planモードではファイルの読み取りのみが許可され、書き込みは行われない。計画を確認してから実行に移せるため、大きな変更でも安心して進められる。

planモードが有効な場面

場面理由
アーキテクチャの変更影響範囲を事前に把握できる
大規模リファクタリング変更ファイルの一覧と順序を確認できる
新機能の設計ディレクトリ構成やファイル分割の方針を相談できる
既存コードの理解コードを読ませて構造を説明させる
移行作業段階的な移行計画を立てられる

実行への移行

planモードで計画を確認した後、shift+tab で通常モードに戻して実行を指示する。

# 計画を確認後
この計画で進めてください。Step 1 から順番に実装してください。

カスタムスラッシュコマンドの活用

よく使う指示パターンはカスタムスラッシュコマンドとして定義できる。.claude/commands/ ディレクトリにMarkdownファイルを配置する。

ファイル構成

.claude/
└── commands/
    ├── review.md      # /project:review で呼び出し
    ├── test.md        # /project:test で呼び出し
    └── new-page.md    # /project:new-page で呼び出し

コマンドの書き方

コマンドファイルはYAMLフロントマターとMarkdown本文で構成される。

---
description: コード変更のレビュー
allowed-tools: Read, Bash(git:*)
---

変更されたファイルを確認してレビューしてください。

変更ファイル一覧: !`git diff --name-only`

レビュー観点:
1. 型安全性（any の使用がないか）
2. エラーハンドリング
3. セキュリティリスク
4. パフォーマンスへの影響
5. テストの有無

問題があれば重要度（Critical / Major / Minor）をつけて報告してください。

フロントマターのオプション

フィールド説明例
descriptionコマンドの説明"PRのレビュー"
allowed-tools使用可能なツール"Read, Bash(git:*)"
model使用モデル"sonnet"
argument-hint引数のヒント"[ファイルパス]"

動的な値の埋め込み

# 引数の参照
$ARGUMENTS  # 全引数
$1, $2      # 個別の引数

# bashコマンドの実行結果を埋め込み
!`git branch --show-current`
!`date +%Y-%m-%d`

# ファイル内容の参照
@src/types/index.ts

実用的なコマンド例

新規ページ作成コマンド (.claude/commands/new-page.md):

---
description: 新規ページの作成
argument-hint: [ページ名] [パス]
allowed-tools: Read, Write, Edit
---

src/pages/Home.tsx のコード構成を参考にして、
新しいページ $1 を src/pages/ に作成してください。

パス: $2

以下を含めてください:
- Helmet によるSEOメタタグ
- Container + Typography のレイアウト
- コンテンツセクション（概要・使い方・FAQ）
- src/App.tsx へのルート追加
- src/pages/index.ts へのexport追加

コミット前チェックコマンド (.claude/commands/pre-commit.md):

---
description: コミット前のチェック
allowed-tools: Read, Bash(git:*), Bash(npm:*), Grep
---

コミット前に以下を確認してください。

変更ファイル: !`git diff --cached --name-only`

チェック項目:
1. TypeScriptの型エラーがないか（tsc --noEmit）
2. Lintエラーがないか
3. console.log が残っていないか
4. TODO コメントが残っていないか
5. 変更内容に対応するテストがあるか

問題があれば報告し、修正方法を提案してください。

効果的なプロンプトのチェックリスト

指示を書く前に以下を確認すると、手戻りが減る。

  • 対象ファイル・関数を特定しているか
  • 期待する最終状態を記述しているか
  • 変更してはいけない箇所を明記しているか
  • 使用するライブラリ・APIを指定しているか
  • エラーメッセージや再現手順を含めているか（バグ修正の場合）
  • 既存コードのスタイルへの準拠を指示しているか
  • 一つの指示に複数の目的を詰め込んでいないか
  • 大きな変更の場合、planモードで計画を立てたか

参考リンク