0:00 0:00
記事
Claude Codeに伝わるプロンプトの基本構造：目的・制約・完了条件・禁止事項を分けて書く型
Claude Codeへの依頼文を「目的・背景・制約・入力・出力・完了条件・禁止事項」に分けて書く基本テンプレートをまとめます。コピペで使える雛形と、悪い依頼文の改善例も整理します。
結論：依頼文は「目的・制約・完了条件」を分けて書くだけで精度が上がる
Claude Codeに渡す依頼文は、長く書くよりブロックを分けて書くほうが結果が安定します。具体的には次の7ブロックを基本構造にします。
- 目的（Goal）: 何を達成したいか。1〜2文。
- 背景（Context）: なぜこの変更が必要か。読むべきファイルや関連仕様。
- 入力（Input）: 具体的な対象ファイル・データ・スクリーンショット。
- 制約（Constraints）: 触ってよい範囲、依存追加の可否、互換要件。
- 出力（Output）: 何を返してほしいか（差分・計画・要約など）。
- 完了条件（Done When）: 何が満たされれば終わりか（テスト・ビルド・型チェック）。
- 禁止事項（Don’t）: やってはいけないこと、便乗修正の禁止。
公式のベストプラクティスでも、具体的な文脈を渡すことと検証手段を与えることが「最も効果が高い」と繰り返し書かれています。本記事はその2点を依頼文の中で強制するための型です。
CLI操作そのものに不安がある方は、基本コマンドと最初の機能追加の手順を先に読んでください。
なぜ「ブロック分割」が効くのか
公式ドキュメントは、悪い例としてadd tests for foo.py、良い例としてwrite a test for foo.py covering the edge case where the user is logged out. avoid mocks.を挙げています。違いは情報量ではなく構造です。良い例では「対象（foo.py）」「観点（ログアウト時のエッジケース）」「禁止事項（モック禁止）」が分離されています。
Claude Codeはプロンプトの長さよりも、文脈の解釈に必要なブロックが揃っているかで振る舞いが変わります。長い散文より、短くてもラベル付きブロックのほうがブレません。
コピペで使える基本テンプレート
最初はこの型をコピーして埋めるだけで十分効きます。
## 目的
<1〜2文で「何を達成したいか」>
## 背景
- 読むべきファイル: <パスを列挙、@ で参照すると確実>
- 関連する仕様: <参照ドキュメント・URL・チケット番号>
- 過去の経緯: <あれば1〜2行>
## 入力
- 対象ファイル: <パス>
- サンプル入力: <あれば>
- 参考にするパターン: <既存実装のファイル・関数名>
## 制約
- 触ってよい範囲: <ディレクトリ・関数>
- 触ってはいけない範囲: <ディレクトリ・関数>
- 依存追加: <可 / 不可、可なら理由必須>
- 後方互換: <維持する / 破壊可、破壊する場合は計画で明示>
## 出力
- まず: <計画 / 差分 / 要約 のどれを返してほしいか>
- 形式: <箇条書き / コードブロック / 表>
## 完了条件
- <テスト名> が通ること
- `npm run build` が通ること
- `npm run typecheck` で新規エラーがないこと
- 差分が <ファイル数 / 行数> を超えないこと
## 禁止事項
- 依頼外のリファクタ・整形・インポート並び替えはしない
- 環境変数や秘密情報をテストに書かない
- 新しいライブラリを承認なしに追加しない
## 進め方
1. まず Plan Mode で計画を出す
2. 私が「この計画で進めて」と返したら実装
3. 実装後、差分とテスト結果を要約して報告このテンプレートをそのまま.claude/templates/に置いておき、依頼ごとにコピーして埋めると運用が安定します。
ブロック別の書き方のコツ
目的（Goal）
「ユーザーが嬉しくなること」まで言語化します。「サインアップフォームのバリデーションを追加する」より、「不正なメールアドレスでサインアップできてしまう問題を直し、フロントエンドで早期にエラーを出す」のほうが伝わります。
背景（Context）
ファイル指定は@で渡すのが最も確実です。Claude Codeは@src/forms/signup.tsを見ると、説明より先にファイルを読みに行きます。
## 背景
- @src/forms/signup.ts のバリデーションが空文字を素通しする
- 仕様は @docs/forms/signup.md の3節
- 過去のPR #1234 で同様の修正をユーザー名側だけ入れた入力（Input）
UIタスクならスクリーンショットを直接貼るのが一番速いです。公式ドキュメントのProvide rich contentにもあるように、画像はコピペやドラッグで渡せます。
制約（Constraints）
「やらないこと」を必ず1〜3個書きます。書かないと、Claude Codeは「ついでに気になった所」を直しがちです。
出力（Output）
「何を返してほしいか」を最初のターンで限定します。例えば「まず計画だけ。実装はしない」と書くだけで、Plan Modeを使わなくても計画フェーズに留まります。Plan Modeの強制方法は計画してから実装させるプロンプト例を参照してください。
完了条件（Done When）
検証コマンドを依頼文に書くと、Claude Code自身が完了判定できます。公式ベストプラクティスのGive Claude a way to verify its workで「最も効果が高い」とされる項目です。
## 完了条件
- `npm test -- src/forms` が緑
- `npx tsc --noEmit` でエラーなし
- 既存のサインアップ画面のスクリーンショットと、修正後のスクリーンショットを比較し、差分が「エラーメッセージ表示」だけになっている禁止事項（Don’t）
依存追加・整形・依頼外修正を禁止しておきます。CLAUDE.mdに共通禁止事項を書いておけば、毎回の依頼文を短くできます。CLAUDE.mdの整備は最初に作るべきCLAUDE.mdの書き方を参照してください。
悪い依頼と改善例
| 悪い例 | 何が問題か | 改善例 |
|---|---|---|
| 「サインアップを直して」 | 目的・対象・完了条件が不明 | 「@src/forms/signup.ts の空文字バリデーションを追加。完了条件は npm test -- src/forms が緑」 |
| 「テストを追加して」 | 観点が不明、モック方針も不明 | 「@src/services/order.ts の createOrder に対し、在庫切れ時の例外を再現するテストを1つ追加。モックは既存の __mocks__/inventory.ts を使う」 |
| 「もっと良くして」 | 何が良いか不明 | 「@src/api/users.ts のページング処理を、cursor方式に変更。既存の offset 方式は当面残し、後方互換を維持」 |
| 「全部リファクタして」 | スコープが無限 | 「@src/services/order/ の重複ロジック1箇所だけ共通化。1コミットで完了する範囲に限定」 |
| 「バグを直して」 | 症状・再現手順が不明 | 「@src/auth/ で、セッションタイムアウト後の遷移が真っ白になる。再現は10分放置→画面遷移。期待は再ログイン画面へ。失敗テストを先に書いて」 |
「悪い依頼は『短い』のではなく、『分割されていない』」と覚えておくと改善しやすいです。
起動時に依頼文を渡すワンライナー
依頼文の本体はエディタや別ファイルで書き、Claude Code起動時に流し込むと整理しやすくなります。
claude "$(cat docs/prompts/signup-validation.txt)" @参照は依頼文中に書けばClaude Codeが自動で読み込みます。
claude "@src/forms/signup.ts のバリデーション追加。詳細は @docs/prompts/signup-validation.txt を読んで進めて" 非対話モードで使うなら、-pに同じ文字列を渡します。
claude -p "$(cat docs/prompts/signup-validation.txt)" CLIフラグの全体像は基本コマンドを参照してください。
「言ってはいけない」依頼文のパターン
| パターン | なぜ避けるか |
|---|---|
| 「いい感じに直して」 | 評価軸がないため、AIが自分で目的を発明する |
| 「色々試して動くやつにして」 | 試行錯誤の境界が無限になる。コストも膨らむ |
| 「とりあえず実装して、テストは後で」 | テストがないと完了判定ができない。差分が大きくなりがち |
| 「動かなかったら別のライブラリ入れていいよ」 | 依頼意図と無関係な依存追加を呼ぶ |
| 「人間が見るからセキュリティは気にしないで」 | レビュー漏れと組み合わさると事故になる |
これらは「短い」のが問題ではなく、判断基準を渡していないのが問題です。
チェックリスト：投げる前の30秒確認
依頼文を送る前に、次の6項目を頭の中でチェックします。
- 目的を1〜2文で言えるか
- 触ってよい範囲と、触らない範囲を書いたか
- 完了条件にコマンド（テスト・ビルド・型チェック）を書いたか
- 出力の最初の1ターンで何を返してほしいかを限定したか（計画 / 差分 / 要約）
- 禁止事項（依存追加・便乗修正・整形）を1個以上書いたか
- 中断条件を書いたか（テスト2回連続失敗で停止、など）
このチェックを30秒で済ませるだけで、後の手戻りが大きく減ります。
まとめ：型を持つと依頼文は短く速くなる
「良い依頼文を書く」は才能ではなく型を埋める作業です。目的・背景・入力・制約・出力・完了条件・禁止事項の7ブロックを意識すれば、短くても精度の高い依頼が書けます。
- 7ブロックを1度テンプレ化すれば、以降はコピーして埋めるだけ
- 検証コマンドを完了条件に入れると、Claude Code自身が完了判定できる
- 禁止事項は依頼文か
CLAUDE.mdに書く
次のステップとしては、計画してから実装させるプロンプト例で計画フェーズの依頼文をさらに磨き、最初の機能追加の手順で通しのワークフローに型を組み込んでください。共通の禁止事項は最初に作るべきCLAUDE.mdの書き方に集約すると、毎回の依頼が短くなります。
