5-2 Claude Code プロンプトの書き方｜5 大原則と実例集

このレッスンで身につくこと

このレッスンは、第 5 章「プロンプト術」の中核です。前のレッスン 5-1 で書いた CLAUDE.md が 「常設の前提」 だとすると、ここで扱うプロンプトは 「今回の具体」 にあたります。前提が整っていても、毎回のプロンプトが雑だと出力品質は崩れます。逆に、プロンプトのコツを掴めば、CLAUDE.md が薄くてもそれなりに動かせます。

このレッスンが目指すのは、思いつきの一言を Claude Code 向けの「設計図」に変換する習慣 を体に染み込ませることです。同じ機能を作るのにも、雑なプロンプトで 3 往復するか、磨いたプロンプトで 1 往復で終わらせるかで、1 日にこなせる仕事量がまったく変わります。

所要時間 — 約 60 分（手を動かしながらなら 90 分） 難易度 — ★★☆☆☆（5-1 を読み終えていれば OK）

なぜプロンプトが大事か — AI は曖昧な指示に弱い

「プロンプトなんて、伝わればいいでしょ」と思うかもしれません。実際、雑な指示でも Claude Code は それっぽい何か を返してきます。問題は、その「それっぽい何か」が、あなたの頭の中の正解 とどれくらいズレているかです。

人間どうしの会話なら、相手は文脈・表情・前後の業務知識を読み取って補完してくれます。Claude Code はあなたの心を読めません。読めるのは、CLAUDE.md とそのセッションのメッセージ履歴、そして今投げたプロンプトだけ。「言わなくても分かるはず」は 99% のケースで通じません。

同じ作業で雲泥の差が出る例

具体例で見ます。「ログイン画面を作って」 とだけ投げると、Claude Code は次のような選択を勝手にします。

• 認証ライブラリは Better Auth？ NextAuth？ Clerk？ 自前？
• メール + パスワード？ ソーシャルログイン？ マジックリンク？
• フォームバリデーションは Zod？ react-hook-form？ 何も入れない？
• スタイルは Tailwind？ CSS Modules？ styled-components？
• ファイルは app/login/page.tsx？ app/(auth)/login/page.tsx？

5 つの分岐があり、Claude Code は それぞれ確率の高い側を選びます。結果、出来上がるのは「世間で一番ありがちなログイン画面」であり、あなたのプロジェクトに合っているかは別問題 です。

同じことを次のように頼んだらどうでしょう。

ログイン画面を作って。
- 既存の lib/auth.ts（Better Auth）を使う
- メール + パスワードのみ。ソーシャルログインなし
- フォームは react-hook-form + zod、エラーは @blueai/ui の FormInput が拾う
- 配置は app/routes/login.tsx、デザインは app/routes/signup.tsx と揃える
- ログイン成功後は /dashboard に遷移

5 つの分岐に 先回りで答え ています。Claude Code は迷う余地がなく、一発で意図通りのコードを返してきます。1 往復で終わるプロンプトは、雑なプロンプト 5 往復より楽 なんです。

プロンプトの 5 大原則

ここから、プロンプトを磨くための 5 つの軸 を順に見ます。覚え方は 「5W1H / 分割 / 例示 / 形式 / 否定」 です。

原則 1 — 5W1H を意識する — 何を（What）、誰のために（Who）、なぜ（Why）、どこで（Where）、いつまでに（When）、どうやって（How）。すべて埋める必要はありませんが、What と How は最低限。

原則 2 — 段階分割 — 大きすぎるタスクは 3〜5 ステップに分けて依頼。各ステップで動作確認してから次に進む。

原則 3 — 参考例を与える（Few-shot） — ゼロから書かせるより、「これに似た形で」と既存物を指差すほうが精度が出る。

原則 4 — 出力フォーマット指定 — JSON か Markdown か表か。形を指定すると、後段の処理（コピペ・自動処理・レビュー）が楽になる。

原則 5 — 否定条件を伝える — 「やらないこと」を明示する。「外部ライブラリを追加しない」「コメントを書き換えない」など。

各原則の Bad / Good 対比

5 つの原則それぞれについて、悪い例と良い例を並べます。自分のプロンプトのどこに穴があるか を探しながら読んでください。

対比 1 — 5W1H を埋める

ダッシュボードを作って

社員向けの売上ダッシュボードを作って。

What  — 月次売上、商談件数、トップ顧客 5 社の 3 つを表示
Who   — 営業マネージャー（毎朝 5 分だけ眺める想定）
Why   — 月次定例の前の状況把握
Where — app/routes/dashboard.tsx
How   — データは /api/v1/dashboard から fetch、表示は @blueai/ui の StatCard

対比 2 — 段階分割する

予約システムを作って。空き状況確認、予約、キャンセル、リマインドメール全部。

予約システムを 4 ステップで作っていく。今回はステップ 1 だけ。

ステップ 1 — 空き状況確認画面（今回）
ステップ 2 — 予約フォーム（次回）
ステップ 3 — キャンセル機能（その次）
ステップ 4 — リマインドメール（最後）

ステップ 1 の要件:
- 日付選択カレンダー（30 日先まで）
- 1 時間枠ごとの空き状況を○×で表示
- API: GET /api/v1/availability?date=YYYY-MM-DD
- ファイル: app/routes/booking/availability.tsx

対比 3 — 参考例を見せる

商品管理ページを作って、シャレた感じで

商品管理ページを、app/routes/users.tsx と同じパターンで作って。
- 列構成だけ変える: 商品名 / カテゴリ / 価格 / 在庫数 / 更新日
- フィルター UI は users.tsx の loader の使い方をそっくり真似る
- ボタン配置・余白・色は users.tsx に揃える

対比 4 — 出力フォーマットを指定する

このリポジトリの依存ライブラリを教えて

このリポジトリの依存ライブラリを、以下の JSON 形式で返して。
それ以外の文章は不要。

{
  "runtime": [{ "name": "", "version": "", "purpose": "" }],
  "dev": [{ "name": "", "version": "", "purpose": "" }]
}

対比 5 — 否定条件を伝える

既存のログイン画面に、パスワード強度メーターを追加して

既存の app/routes/login.tsx にパスワード強度メーターを追加して。

制約:
- 外部ライブラリは追加しない（独自関数で 8 文字 / 大小 / 数字 / 記号を判定）
- 既存のスタイル変数（var(--brand)）を流用、新規 CSS 変数を作らない
- 既存のバリデーションロジックには触らない
- 強度判定は components/password-strength.tsx に切り出す

段階分割の実践 — 大きいタスクを小さく

原則 2「段階分割」は、慣れていないと一番難しいポイントです。どのくらい細かく分けるか の感覚を、3 つの具体例で掴みます。

例 1 — ブログ機能

「ブログ機能を作って」を分割します。

5 ステップに分解 したら、各ステップを 個別のプロンプト として投げます。ステップ 2 が終わったら必ず動作確認、そこで違和感があったら ステップ 3 に進む前に修正。これで「最後にまとめてエラー祭り」がほぼ起きません。

例 2 — 既存機能のリファクタ

「コード全体をリファクタして」 は最悪のプロンプトです。次のように分けます。

ステップ 1 — まずファイル一覧を見て、リファクタ候補を 5 つ挙げて。
            実装はしないで、優先順位とリスクだけ報告。

ステップ 2 — ステップ 1 で挙げた 1 番から、リファクタ案を 3 行で説明。
            OK を出したら実装に進む。

ステップ 3 — 実装。テストが落ちたら止まって報告。

ステップ 4 — 1 番が完了したら 2 番に進む。

調査 → 提案 → 実装 → 次へ の 4 段。Claude Code に勝手にコードを書き始めさせない仕掛けです。調査だけのフェーズを最初に挟む のがコツ。

例 3 — 不具合修正

バグ修正も段階分割すると安全です。

ステップ 1 — 症状を再現する最小コードを示して。実装変更はしない。
ステップ 2 — 原因仮説を 3 つ挙げて、優先順位をつけて。
ステップ 3 — 仮説 1 に基づく修正案を、変更箇所だけ diff で見せて。
ステップ 4 — OK が出てから実装。テストを 1 つ追加して再現を防ぐ。

仮説を 3 つ出させる ところで Best of N（次のレッスン 5-3）の発想と繋がります。原因がはっきりするまで実装に入らない、という規律が事故を防ぎます。

参考例の与え方 — Few-shot プロンプト

原則 3「参考例」を、もう一段深掘りします。Few-shot プロンプト とは、入力と出力のペアをいくつか見せて、望ましいパターン を Claude Code に学習させる手法です。

Zero-shot vs Few-shot

Zero-shot（例なし）と Few-shot（例あり）の違いを見ます。

# Zero-shot — 例を見せない
> 顧客名から会社名らしき部分を抽出して。

# Few-shot — 入出力ペアを 3 つ見せる
> 顧客名から会社名らしき部分を抽出して。以下の例に倣って。
>
> 入力: 株式会社ブルーエーアイ 平原直樹
> 出力: 株式会社ブルーエーアイ
>
> 入力: 田中商事 営業部 山田太郎
> 出力: 田中商事
>
> 入力: 佐藤花子
> 出力: （会社名なし）
>
> 入力: NHIRA Inc. - John Smith
> 出力: NHIRA Inc.
>
> では、以下を処理して。
> 入力: 合同会社みらい 鈴木一郎

Zero-shot だと「ブルーエーアイ」と短縮されたり、敬称が混ざったりします。Few-shot は 3〜5 例で十分 です。例が多すぎると「例にぴったり同じ形しか出さない」過学習に近い挙動になります。

Few-shot が効く場面

Few-shot は次のような場面で特に効きます。

• 出力の体裁を厳密に揃えたい（例えばコミットメッセージ、PR タイトル、コメント文）
• 判定基準が曖昧な分類タスク（このメールは「営業」？「カスタマーサポート」？）
• 独自の DSL や記法 を Claude Code に教える（独自のテンプレート言語、自社の JSON 形式）
• Bad と Good を両方見せる（「こう書かないで」「こう書いて」のペア）

# Bad / Good ペアで体裁を教える
> コミットメッセージを書いて。以下の形式で。
>
> Bad: 「修正」「fix」「typo」
> Good: 「fix(login): trim メール大文字小文字を区別しないように」
> Good: 「feat(invoice): add 0% tax rate handling」
>
> 今回の変更内容: ボタンの色を青に変えた

「こうしないで」を 1 つ混ぜる だけで、出力の安定性が大きく上がります。

出力フォーマット指定

原則 4「出力フォーマット指定」を、4 つの代表形式で掘り下げます。形を決めると、後工程が楽になります。

JSON — 機械処理する用

スクリプトで処理したい、別ツールに食わせたい、API レスポンスの雛形を作りたい——そんなときは JSON。スキーマを Markdown のコードブロックで先に提示 するのがコツです。

> このディレクトリの TS ファイル全部から関数一覧を抽出して、
> 以下の JSON で返して。それ以外の前置きや説明は不要。
>
> {
>   "files": [
>     {
>       "path": "string",
>       "functions": [
>         { "name": "string", "exported": true, "lines": 12 }
>       ]
>     }
>   ]
> }

「それ以外の説明は不要」 の一文が大事。これがないと、JSON の前に「以下が結果です。」みたいな枕詞が付いてパースに失敗します。

Markdown 表 — ドキュメントに貼る用

社内 Wiki やノートにそのまま貼りたいなら Markdown 表。列名を先に提示 すると揃います。

> このリポジトリの環境変数を、以下の Markdown 表で一覧化して。
> 列: 変数名 / 用途 / デフォルト値 / 必須かどうか

コードブロック — そのままコピペする用

複数のコードスニペットを返してほしいときは、言語タグ付きのコードブロック を明示。

> 以下の 3 ファイルを生成して。すべてコードブロックで囲んで、
> ファイル名を見出しに書いて。説明文は不要。
>
> ## app/routes/booking.tsx
> ## app/components/booking-form.tsx
> ## app/lib/booking-api.ts

見出し + コードブロック の組み合わせは、複数ファイルの提案を 1 つのチャットで受けるときの定番です。

自由文 + 箇条書き — 普通の説明用

調査結果や提案を文章で受けたいときも、箇条書きで上限を切る と質が安定します。

> このリポジトリのパフォーマンス改善案を、
> 箇条書きで 5 つ。それぞれ 1 行（80 文字以内）。
> 効果が大きい順。

「5 つ」「80 文字以内」「効果が大きい順」 と 3 つの制約を入れるだけで、長文の散文が短い実用的なリストに変わります。

否定条件の指定 — 「○○しないで」「△△は含めない」

原則 5「否定条件」を、もう少し細かく見ます。Claude Code は何もしないと「親切のつもり」で範囲外まで触ります。それを止めるのが否定条件です。

よくある否定条件 10 選

実務でよく使う否定条件をまとめておきます。コピペして使い回せます。

- 外部ライブラリを追加しない（既存の依存だけで実装）
- 既存のファイルを削除しない / リネームしない
- 既存のテストを書き換えない（追加だけ OK）
- console.log / print デバッグ文を残さない
- TODO コメントを足さない（やるなら今やる、やらないなら書かない）
- ファイルの先頭のコメントブロック（コピーライト等）を変えない
- 他のページやコンポーネントには手を入れない（指定ファイルのみ）
- TypeScript の any を使わない（unknown + 型ガードで対応）
- 環境変数を新規追加しない（既存の VAR を流用）
- マイグレーションを自動で当てない（diff を見せて止まる）

否定条件は具体的に。「変な変更しないで」だと伝わりません。「○○ファイルを変更しないで」「○○ライブラリを使わないで」のように、チェック可能な粒度 まで落とします。

否定条件と肯定条件の比率

経験則として、プロンプトの 3 分の 1 が否定条件 でも問題ありません。むしろそれくらいで丁度いいケースが多いです。「やってほしいこと」だけ書いて短くまとめるよりも、「やってほしくないこと」も書いて長くする ほうが事故が減ります。

ロールプレイ指示 — 「あなたは経験 10 年の○○です」

ロールプレイ指示とは、Claude Code に役割を与える テクニックです。「あなたは経験 10 年のシニア Go エンジニアです」「あなたは UX デザイナーです」と宣言してから本題に入ると、出力のトーンと観点が変わります。

効果が出やすい役割

ロールが効きやすいのは 専門性が必要な観点切り替え をしたいときです。

> あなたは経験 15 年のセキュリティエンジニアです。
> 以下のログイン API コードを、セキュリティ観点だけでレビューして。
> パフォーマンスや可読性のコメントは不要。
> 指摘は深刻度（High / Med / Low）でラベル付け。
>
> [コードを貼る]

> あなたは UX ライターです。以下のエラーメッセージを、
> ユーザーが心理的に追い詰められないトーンに書き換えて。
> 元の意味は変えない。日本語、敬体。
>
> [エラーメッセージ一覧]

ロールを指定すると、Claude Code は その役割のチェックリスト を内部で立ててから返答します。指定しない場合との差は、細かい観点の網羅性 にはっきり出ます。

ロールプレイを使わないほうがいい場面

万能ではありません。ファイル操作や実装作業（コードを書く・実行する）には、ロールプレイは ほとんど効果がない です。ロールが効くのは 判断・レビュー・分類・文章生成 のような 解釈が入る作業 に限られます。コード生成では、CLAUDE.md と原則 1〜5 をきっちりやるほうが効きます。

自己レビュー指示 — 「書いた後に自分でチェックして」

自己レビュー指示とは、Claude Code に出力後の自己点検を依頼する テクニックです。「書き終わったら自分でチェックリストを回して、漏れがあったら修正してから提出して」と伝えます。

> 商品検索 API を実装して。

> 実装後、以下のチェックリストを自分で確認し、漏れがあれば修正してから完了報告:
> □ org_id でテナント分離されているか
> □ SQL インジェクション対策（プリペアド or sqlc）になっているか
> □ ページネーション（page / per_page）がついているか
> □ エラー時の戻り値が { error: string, code: number } 形式か
> □ openapi.yaml に該当エンドポイントが追加されているか

チェック項目を 5 つ くらいに絞るのがコツ。20 個並べると Claude Code は形だけ「全部 OK です」と返してくる傾向があります。5 個を真面目に のほうが効きます。

プロンプト失敗パターン

実務でやりがちな失敗 5 パターン を整理しておきます。再発防止のため、出会ったら自分のプロンプトを 1 行ずつチェックしてください。

失敗 1 — あいまい

「いい感じに」「もうちょっと」「適当に」 のような形容詞だけのプロンプト。Claude Code は最大公約数を返すしかありません。形容詞は数値・色名・既存物の名前に置き換えます。「いい感じに → ヘッダーは 56px、ロゴは左、ナビは右、間隔均等」。

失敗 2 — 文脈不足

どのファイルか・どの環境か・誰が使うか を書かない。Claude Code は推測を始め、半分の確率で外れます。最低でも ファイルパス + 利用者像 + 環境 の 3 点はプロンプトに入れます。

失敗 3 — 出力指定なし

「分かるように書いて」 だけ。返ってきた長文をどう使うかが決まっていません。使い道から逆算「Wiki に貼るから Markdown 表で」「スクリプトに食わせるから JSON で」と先に決めます。

失敗 4 — 一度に詰め込みすぎる

機能 3 つを一発依頼。Claude Code は薄っぺらい雛形を 3 つ並べて終わります。1 つを深く、を 3 回 のほうが早いし品質も上です。

失敗 5 — 矛盾している

「シンプルに、でも高機能に」「速く、でも丁寧に」 のような相反する要件。Claude Code はどちらかに寄せざるを得ません。トレードオフは自分で決めて から渡します。「速度優先、機能は最小、丁寧さは後回し」のように。

プロンプトテンプレート集

最後に、すぐコピペできるテンプレート 5 種 を置いておきます。最初は丸ごと真似て、慣れたら自分用に書き換えてください。

テンプレ 1 — 新規機能実装

[機能名] を実装して。

## 完成イメージ
- ユーザーは [Who] が [Where] で [What] できる
- 業務上の目的は [Why]

## 仕様
- 入力: [入力データの形]
- 出力: [出力データの形]
- API: [エンドポイント、未確定なら「不要 or 別途設計」]
- ファイル配置: [パス]

## 制約
- [使うライブラリ・使わないライブラリ]
- [既存コードとの整合性]
- [絶対に触らないファイル / 機能]

## 完成チェック
- [ ] [チェック項目 1]
- [ ] [チェック項目 2]
- [ ] [チェック項目 3]

テンプレ 2 — バグ修正

[機能名] のバグを直して。

症状 — [何が起きているか、ユーザー視点で 1 行]
再現 — [操作手順、3 ステップ以内]
期待 — [どうなってほしいか]
推測 — [原因の見立て、なければ「不明」]
関連ファイル — [パス、複数なら箇条書き]

## 進め方
1. まず原因仮説を 3 つ挙げて、優先順位だけ報告
2. OK が出てから修正に進む
3. 再現を防ぐテストを 1 つ追加

テンプレ 3 — リファクタ

[対象ファイル / 機能] をリファクタしたい。

## 目的（リファクタする理由）
- [可読性 / パフォーマンス / 保守性 のどれか + 具体的な痛み]

## スコープ
- 対象: [ファイル / 関数]
- 対象外: [触らない場所]

## 制約
- 外部 API のシグネチャは変えない
- 既存テストは全部パスし続けること
- ライブラリ追加なし

## 進め方
1. リファクタ案を 3 つ出して比較表で見せる
2. 私が 1 つ選んだら実装に進む
3. 各コミットを小さく分ける（diff レビューしやすく）

テンプレ 4 — 調査・レビュー

[対象] を [観点] でレビューして。

## 観点
- [セキュリティ / パフォーマンス / 可読性 のどれか 1〜2 個]

## 出力形式
- 箇条書き、5 項目以内
- 各項目: 深刻度（High / Med / Low）+ 該当箇所のファイル:行 + 提案

## ロール
あなたは経験 10 年の [Go / React / セキュリティ] エンジニアです。

## 出力外
- 直接の修正コードは不要
- 良かったところの褒めも不要

テンプレ 5 — ドキュメント・文章生成

[ドキュメント種別] を書いて。

## 読者
- [誰が読むか、技術レベル、目的]

## 形式
- [Markdown / プレーンテキスト / 表]
- 字数: [目安、上限]
- 構成: [章立て、見出し階層]

## トーン
- [敬体 / 常体 / 英語 / フォーマル / フランク]
- 参考にする既存ドキュメント: [パス or URL]

## 含めないこと
- [絵文字 / 過剰な比喩 / 専門用語]

まとめ

このレッスンのポイントを 7 点で振り返ります。

1. プロンプトの 5 大原則（5W1H / 段階分割 / 参考例 / 出力フォーマット / 否定条件）を毎回最低 2 つ意識
2. Bad は「Claude Code が補完できる余地を残しすぎ」。具体化と否定条件で余地をゼロに
3. 大きいタスクは 3〜5 ステップに分割。1 ステップ 15〜30 分を目安に
4. Few-shot プロンプト は 3〜5 例で十分。Bad / Good ペアを混ぜると安定する
5. 出力フォーマットはプロンプトの末尾 に明記。JSON / Markdown 表 / コードブロックを用途で使い分け
6. 否定条件はプロンプトの 3 分の 1 でも OK。「不信」ではなく「設計」として書く
7. テンプレ 5 種 を持ち帰り、最初は丸ごと真似、慣れたら自分用に育てる

<Quiz question="プロンプトの 5 大原則に含まれていないものはどれですか？" options={["出力フォーマット指定","段階分割","ロールプレイ指示"]} answer={2} />

<Quiz question="Few-shot プロンプトについて正しい説明はどれですか？" options={["入出力ペアの例を 3〜5 個見せて、出力パターンを学習させる手法","プロンプトの末尾に必ずロールプレイ指示を追加する手法","Claude Code に 1 つの正解だけを断定的に指示する手法"]} answer={0} />

<Quiz question="否定条件についての説明として最も適切なものはどれですか？" options={["プロンプトの 3 分の 1 が否定条件でも問題なく、スコープ設計の一環として書く","否定条件は Claude Code への不信を意味するので、できるだけ書かないほうがよい","肯定条件と否定条件は 1 対 1 で書かないと矛盾が起きる"]} answer={0} />

次のレッスン 5-3: Best of N パターン では、ここで磨いたプロンプトを応用し、複数案を並列に出させて最適解を選ぶ テクニックを学びます。1 つのプロンプトでベストを引き当てるのが原則 1〜5 だとすれば、Best of N は 「ベストを引き当てる確率を統計的に上げる」 手法。両方を組み合わせて、Claude Code との対話を一段上のレベルへ持っていきましょう。