CodeCraft Lab

プロンプト設計の実践テクニック

指示の構造化、コンテキストの与え方、出力形式の制御など、Claude Codeへの指示を最適化する実践テクニックを解説します

実践17分で読了
プロンプト設計ベストプラクティステンプレート実践

このレッスンで学ぶこと

  • 指示を「背景→タスク→制約→出力形式」の型で構造化し、手戻りを減らす
  • ファイル参照・要約・絞り込みによって、必要なコンテキストだけを的確に渡す
  • 出力形式を指定して、JSON・Markdown・特定のコード規約に沿った結果を得る
  • よく使うプロンプトをテンプレート化し、再利用できる形にする

前提条件

  • 入門コースを修了し、Claude Codeの基本操作に慣れていること
  • 実践コース Lesson 1〜7 のいずれか（特にコードレビュー・テスト生成）を一通り試していること

なぜプロンプトの「質」が結果を左右するのか

Claude Codeは曖昧な指示でも何かしらの結果を返してくれます。しかし、その結果が「自分の意図と違う」「微妙にずれている」と感じたことがある人は多いはずです。

これは、Claude Codeの能力不足ではなく、指示に含まれる情報量が足りていないことが原因であるケースがほとんどです。Claude Codeはあなたの頭の中を読めません。プロジェクトの背景、暗黙のルール、期待する完成形は、指示の中で明示しない限り存在しないものとして扱われます。

逆に言えば、指示の構造を整えるだけで、修正の往復回数を大きく減らせます。このレッスンでは、その具体的な型とテクニックを扱います。

指示を構造化する: 背景→タスク→制約→出力形式

行き当たりばったりに指示を書くのではなく、次の4つの要素を意識して組み立てると、Claude Codeが迷わず動けるようになります。

要素役割書く内容の例
背景なぜこの作業が必要かを伝える「このAPIは外部パートナー向けに公開する予定」「既存のユーザーが多く後方互換性が必須」
タスク何をしてほしいかを明確にする「UserRepositoryにページネーション機能を追加して」
制約やってはいけないこと・守るべき条件「既存のメソッドシグネチャは変更しない」「外部ライブラリは追加しない」
出力形式結果をどう受け取りたいか「変更後はdiffで確認させて」「テストも一緒に書いて」

背景を一言添える

タスクの前に、なぜそれが必要なのかを短く説明します。背景があると、Claude Codeは「何を優先すべきか」の判断基準を持てます。

このリポジトリは決済処理を扱うため、エラーハンドリングの厳密さが特に重要です。

タスクを具体的に書く

対象のファイル・関数・機能を名指しします。「いい感じに直して」ではなく、対象を特定できる表現にします。

src/payment/charge.ts の processCharge 関数に、
カード会社からのタイムアウトエラーをリトライする処理を追加して。

制約を箇条書きで示す

やってほしくないことや守るべき条件を、漏れなく書き出します。

制約:
- リトライは最大3回まで
- 既存の関数シグネチャは変更しない
- リトライ間隔は指数バックオフにする

出力形式を指定する

結果の受け取り方を指定すると、確認の手間が減ります。

実装後は変更したファイルの一覧と、テストの実行結果を報告して。

この4要素をまとめると、次のような1つの指示になります。

このリポジトリは決済処理を扱うため、エラーハンドリングの厳密さが特に重要です。
 
src/payment/charge.ts の processCharge 関数に、
カード会社からのタイムアウトエラーをリトライする処理を追加して。
 
制約:
- リトライは最大3回まで
- 既存の関数シグネチャは変更しない
- リトライ間隔は指数バックオフにする
 
実装後は変更したファイルの一覧と、テストの実行結果を報告して。
毎回4要素をフルに書く必要はない

小さな修正（タイポ修正、1行追加など）では、この型をフルに使う必要はありません。スコープが明確で変更が小さいタスクは「〜して」の一言で十分です。複数ファイルにまたがる変更や、初めて触る領域での作業のときにこそ、この型が効いてきます。

コンテキストの与え方: ファイル参照・要約・絞り込み

Claude Codeに「何を見て判断してほしいか」を正確に伝えることも、指示の構造化と同じくらい重要です。

ファイル参照で「どこを見るか」を明示する

口頭で場所を説明するより、@記法でファイルを直接参照したほうが速く正確です。

@src/utils/validation.ts のロジックを参考にして、
src/utils/sanitize.ts に同じスタイルでサニタイズ関数を実装して。

ディレクトリ全体の構造を把握してほしい場合は、ディレクトリを参照します。

@src/components の構成を確認して、新しいUIコンポーネントをどこに配置すべきか提案して。

要約で「すでにわかっていること」を圧縮して渡す

長い調査結果や仕様のすり合わせ内容をそのまま貼り付けると、コンテキストを大量に消費します。要点を箇条書きにまとめてから渡すと、同じ情報量でもやり取りが軽くなります。

前提（調査済み）:
- 認証はJWTベースで、有効期限は1時間
- リフレッシュトークンはhttpOnly Cookieに保存
- /api/auth/refresh エンドポイントが既に存在する
 
これを踏まえて、トークン期限切れ時に自動でリフレッシュするインターセプターを
src/lib/api-client.ts に実装して。

絞り込みで「見るべき範囲」を制限する

「プロジェクト全体を確認して」のような指示は、Claude Codeに広範な探索を強いてコンテキストを圧迫します。対象を絞り込むほど、結果も速く的確になります。

src/features/checkout 配下のみを対象に、
未使用のexportがないか確認して。他のディレクトリは見なくていい。
絞り込みすぎにも注意

逆に絞り込みすぎると、本来参照すべき共通モジュールやインターフェース定義を見落とすことがあります。「関連がありそうなら他のファイルも確認していい」と一言添えておくと、過不足のないバランスになります。

出力形式を制御する

Claude Codeはテキストでの説明にも応答できますが、出力形式を明示的に指定すると、後工程で使いやすい結果が得られます。

JSON形式で構造化データを得る

スクリプトや別ツールに渡すデータがほしいときは、JSON形式とスキーマを指定します。

src/models 配下の全モデルファイルを調べて、以下のJSON形式で出力して。
 
{
  "models": [
    { "name": "モデル名", "file": "ファイルパス", "fields": ["フィールド名の配列"] }
  ]
}
 
説明文は不要、JSONのみを出力して。

Markdownで読みやすいレポートを得る

人間が読むためのドキュメントやレポートには、見出し構造を指定します。

このPRの変更内容を、以下の構成のMarkdownでまとめて。
 
## 概要
## 変更ファイル一覧
## 影響範囲
## 確認事項

特定のコード規約に沿わせる

プロジェクト固有のコードスタイルを毎回説明するのは非効率です。代表的な既存コードを示し、それに倣うよう指示すると精度が上がります。

src/api/users.ts のエラーハンドリングのスタイル（Result型を使う方式）に合わせて、
src/api/orders.ts も同じパターンでリファクタリングして。
出力形式はCLAUDE.mdにも書ける

「コミットメッセージは日本語で1行目要約」「PRの説明はテンプレートに従う」など、毎回繰り返す出力形式のルールは、都度プロンプトに書くよりCLAUDE.mdに記載しておくほうが効率的です。詳しくはLesson 4: CLAUDE.mdでプロジェクトの記憶を作るを参照してください。

曖昧な指示 vs 具体的な指示: 比較で見る効果

同じ意図でも、書き方ひとつで結果の精度が大きく変わります。実際の例で比較してみましょう。

場面曖昧な指示具体的な指示
バグ修正「ログイン周りにバグがあるので直して」「src/auth/session.tsでセッションタイムアウト後にログインに失敗する。再現手順: タイムアウトまで待機してからログインボタンを押す。失敗するテストを書いてから修正して」
機能追加「検索機能を強化して」「検索結果のページネーションを追加して。1ページあたり20件、APIはGET /api/search?page=の形式に対応済み」
リファクタリング「このファイルをきれいにして」「src/utils/format.tsの重複ロジックを共通関数に切り出して。外部から呼ばれているインターフェースは変えないで」
テスト追加「テストを書いて」「calculateDiscount関数に、クーポン期限切れ・在庫切れ・上限金額超過の3つの異常系テストを追加して」

曖昧な指示が常に悪いわけではありません。「このコードベースで気になる点は？」のような、Claude Code側に発見を促したい場面では有効です。しかし、結果を一発で確定させたいタスクでは、具体性が修正回数を直接減らします。

プロンプトの再利用: テンプレート化への第一歩

同じようなタスクを繰り返すなら、毎回ゼロから指示を書くのではなく、テンプレート化しておくと効率的です。

個人用テンプレートをメモとして持つ

よく使うプロンプトのパターンを、プロジェクトのメモやスニペット集として保存しておきましょう。

[テストレビュー依頼テンプレート]
@{対象ファイル} のテストカバレッジを確認して。
以下の観点でチェックして:
- 正常系・異常系・境界値のテストが揃っているか
- モックの使い方が他のテストファイルと一貫しているか
- テスト名が「何を」「どんな条件で」「どうなるか」を表しているか

チームで共有するテンプレート

チームで頻繁に使うプロンプトパターンは、docs/やCLAUDE.mdにまとめて共有すると、メンバー間で指示の質がそろいます。

## よく使うプロンプトパターン
 
### PRレビュー依頼
このブランチの変更をレビューして。
観点: セキュリティ、パフォーマンス、既存コードとの一貫性。
重大度（high/medium/low）付きで報告して。
 
### 移行作業の計画
{対象範囲}を{移行元}から{移行先}に移行する計画を立てて。
影響を受けるファイル一覧と、段階的な移行ステップを示して。
テンプレート化の先にあるSkills

さらに頻度の高いプロンプトは、スラッシュコマンドとして呼び出せる「Skills」という仕組みに発展させることができます。Skillsを使うと/review-testsのような短いコマンドで、定型化された指示一式を毎回呼び出せるようになります。これは応用コースで詳しく扱う発展的なテーマですが、「同じプロンプトを3回以上コピペした」と感じたら、テンプレート化・Skills化のタイミングだと考えてよいでしょう。

まとめ

このレッスンでは、Claude Codeへの指示の質を上げるための実践テクニックを学びました。

  • 「背景→タスク→制約→出力形式」の4要素で指示を構造化すると、手戻りが減る
  • ファイル参照・要約・絞り込みを使い分けて、必要なコンテキストだけを的確に渡す
  • JSON・Markdown・既存コード規約など、出力形式を明示すると後工程で使いやすい結果が得られる
  • 曖昧な指示は発見的なタスクに、具体的な指示は確定させたいタスクに向いている
  • 繰り返し使うプロンプトはテンプレート化し、将来的にはSkills化も視野に入れる

プロンプトの構造化は、一度型を身につければあらゆる場面で応用が利くスキルです。次のレッスンでは、この指示の質を支えるもう一つの重要な要素「コンテキスト管理」について、さらに踏み込んで学びます。

次のステップ

次はLesson 9: コンテキスト管理を最適化するに進み、コンテキストウィンドウの仕組みと、長く複雑なセッションを効率的に保つための戦略を学びましょう。