ankuro.dev
← ブログ一覧に戻る
【Claude Code中級編 #14】Claude Codeに通る指示の書き方——プロンプト設計の基本
2026-04-21#Claude Code#AI#プロンプト設計#指示の書き方

【Claude Code中級編 #14】Claude Codeに通る指示の書き方——プロンプト設計の基本

Claude Codeで思った結果が出ないとき、原因の多くは指示そのものにある。「通る指示」には型がある。この記事では5つの原則とビフォーアフター例をまとめる。

この記事でわかること：

  • 通る指示を作るための5原則（対象特定・期待結果・制約・背景・検証）
  • NG例と改善例を並べたビフォーアフター集
  • 毎回ゼロから書かずに済むようCLAUDE.mdに落とし込む運用

「通る指示」の5原則

まず結論のチェックリスト。

□ 対象を特定している（ファイル・関数・変数まで書く）
□ 期待結果を明示している（何を満たせば完了か）
□ 制約を書いている（やらないでほしいこと）
□ 背景を一言添えている（なぜそうしたいか）
□ 検証手順を含めている（型チェック・テスト・動作確認）

5つすべて揃っている必要はないが、タスクが重要なほど抜けを減らすと結果が安定する。以下、それぞれの中身と書き方を見ていく。

原則① 対象を特定する

「バグを直して」「リファクタして」のような広い指示は、Claudeが対象の探索に時間を使い、勘違いしたまま的外れな修正をする原因になる。

特定するべき3階層

① ファイルパス: src/api/users/register.ts
② 関数・クラス: validateEmail 関数
③ 変数・引数: email 引数のバリデーションロジック

タスクの粒度に応じて、最も深い階層まで指定する。

ビフォーアフター

❌ 曖昧
「ユーザー登録のバリデーションを直して」

✅ 特定済み
「src/api/users/register.ts の validateEmail 関数、
  email 引数のバリデーションロジックを修正したい」

ファイル名を書くのが面倒に感じるかもしれないが、結果的に往復が減るので総時間は短くなる。

原則② 期待結果を明示する

「何をもって完了とするか」が指示に書かれていないと、Claudeは自分の基準で「完了」を判定する。その基準が人間の意図と一致している保証はない。

期待結果の書き方

① 入力 → 出力の形式
② 成功条件（何がtrueならOKか）
③ 失敗条件（何が起きたらNGか）

ビフォーアフター

❌ 期待結果なし
「email のバリデーションを直して」

✅ 期待結果込み
「email のバリデーションを修正。
  期待する動作:
  - "User@Example.COM" のような大文字混じりも受け入れる
  - 空文字・null はエラーで返す
  - @ を含まない文字列はエラーで返す」

期待結果を書くと、Claudeは自分で動作確認の観点を作れる。結果、「完了報告したが実は失敗していた」パターン（第13回パターン⑤ で扱った）が起きにくくなる。

原則③ 制約を書く

「やってほしいこと」だけでなく「やらないでほしいこと」を書くと、意図しない範囲変更を防げる。

よくある制約

- 他のファイルは編集しない
- 依存パッケージを追加しない
- 既存のAPI定義を変更しない
- テストファイル以外は触らない
- 変数名・関数名の変更はしない

ビフォーアフター

❌ 制約なし
「この関数のロジックを改善して」
  → 「ついでに周辺コードもリファクタしました」と広範な変更が来る

✅ 制約明記
「この関数のロジックを改善して。
  制約:
  - 関数のシグネチャ（引数・戻り値）は変更しない
  - 呼び出し元のファイルは編集しない
  - 新しい依存パッケージは追加しない」

Claudeは「気になった箇所を直す」傾向があるので、範囲を囲う一文は効果が大きい。

よく使う制約はCLAUDE.mdに

毎回書くのが手間な制約は、CLAUDE.mdにプロジェクト全体のルールとして書いておく。

## 変更範囲のルール

- 依存パッケージの追加は事前に相談すること
- ファイル名の変更は事前に相談すること
- 既存の公開API（export されている関数）のシグネチャ変更は事前に相談すること

指示のたびに書かずに済む。

原則④ 背景を一言添える

「なぜそうしたいか」を1行添えると、Claudeが判断に迷ったときに妥当な方向を選べる。

背景があるとどう変わるか

❌ 背景なし
「ユーザー一覧をページネーションして」
  → Claudeは一般的なページネーション（offset/limit）を実装するかも

✅ 背景つき
「ユーザー一覧をページネーションして。
  背景: ユーザー数が10万件を超える想定で、深いページでもパフォーマンスを落としたくない」
  → offset/limitではなくcursor-basedなど、背景に合った実装が選ばれる

背景を書くと実装方針の判断までClaudeに任せやすくなる。書かないと一般解が返ってきて、後から「うちのケースでは違う」と手戻りする。

書きすぎない

背景は長くしすぎると逆効果。**1〜2行で「なぜ」と「制約となる事実」**を書くのが目安。

✅ 良い背景
「ユーザー数が10万件を超える想定のため、深いページでも性能を落としたくない」

❌ 冗長な背景
「うちのサービスは2020年から始まって、最初は小規模だったが、最近...（長文）」

原則⑤ 検証手順を指示に組み込む

第13回でも触れたが、事前に指示へ組み込むのが最も確実。事後に「確認して」と言うより、最初から完了条件に含める方が往復が減る。

検証コマンドを明示する

❌ 検証指示なし
「ユーザー登録APIを実装して」

✅ 検証込み
「ユーザー登録APIを実装して。
  完了後に以下を実行し、全てパスしたことを確認してから完了と報告:
  - npm run type-check
  - npm run lint
  - npm test src/api/users/
  エラーが出た場合は修正してから再実行してください。」

「実行して確認」まで書く

コードを書くだけでなく、実際に動かして期待値を満たすかまで確認させる指示を入れる。

「curl でエンドポイントを叩き、以下のレスポンスが返ることを確認:
  POST /api/users {"email":"test@example.com"} → 201 Created
  POST /api/users {"email":""} → 400 Bad Request」

「動くはず」ではなく「動いたことを確認した」状態で完了報告が来るようになる。

ビフォーアフター集

5原則を組み合わせた例を3ケース分。

ケース①：バグ修正

❌ ビフォー
「ログイン機能がおかしいので直して」

✅ アフター
「src/api/auth/login.ts のログイン処理で、
  正しいパスワードでも401が返るバグを修正したい。

  【再現手順】
  curl -X POST /api/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"email":"test@example.com","password":"correct"}'
  → 現状: 401 Unauthorized
  → 期待: 200 OK + JWT トークン

  【制約】
  - src/api/auth/ 配下のみ編集
  - 認証ロジックの仕様自体（bcrypt使用など）は変更しない

  【検証】
  npm test src/api/auth/ が通ることを確認してから完了と報告」

ケース②：機能追加

❌ ビフォー
「ユーザー削除機能を追加して」

✅ アフター
「ユーザー削除APIを追加したい。

  【エンドポイント】
  DELETE /api/users/:id

  【要件】
  - 認証必須（既存のauthミドルウェアを使う）
  - 自分自身のみ削除可能（他ユーザーの削除は403）
  - 削除は論理削除（deletedAt カラムに現在時刻をセット）

  【背景】
  GDPR対応で、ユーザーが自分のアカウントを削除できる必要がある

  【制約】
  - 新しい依存パッケージは追加しない
  - 既存の User モデルのカラム追加のみ（スキーマの大幅変更は相談）

  【検証】
  - type-check / lint を通す
  - 追加したエンドポイントのテストを書いて通す」

ケース③：リファクタ

❌ ビフォー
「このコード読みづらいのでキレイにして」

✅ アフター
「src/utils/parser.ts の parseConfig 関数をリファクタしたい。

  【現状の問題】
  - 関数が150行あり読みづらい
  - ネストが深い（最大5段）

  【方針】
  - ヘルパー関数に分割してネストを減らす（最大3段まで）
  - 関数シグネチャ（引数・戻り値の型）は変更しない

  【制約】
  - 呼び出し元のコードは変更しない
  - 既存のテストが全てパスすることを優先

  【検証】
  - npm test src/utils/parser.test.ts が全てパス
  - 型チェック・lintを通す」

まとめ

原則 チェックポイント
対象を特定 ファイルパス・関数名・変数名まで書いたか
期待結果を明示 成功条件・失敗条件を指示に含めたか
制約を書く 編集範囲・禁止事項を1行でも添えたか
背景を添える 「なぜ」を1〜2行で書いたか
検証を含める 型チェック・テスト・動作確認までを完了条件にしたか

「通る指示」は才能ではなく型。5原則をチェックリストとして持っておき、重要なタスクほど抜けを減らす。繰り返し使う制約・検証はCLAUDE.mdに書き戻して、毎回ゼロから書かずに済む仕組みにするのが長続きするコツになる。

← 第13回：デバッグ・エラー対処——よくある失敗パターンと解決法 ｜ 第15回：Channelsで通知を飛ばす——Webhook・Discord連携の実装 →

← ブログ一覧に戻る