Claude Code プロンプトの書き方｜公式推奨の型と失敗時の直し方

Claude Code のプロンプト設計は、「終わったかどうかを Claude 自身が確かめられる手段」と「どのファイル・どの状況・何をもって完了か」を一緒に書くと、やり直しが減ります。Anthropic の公式ベストプラクティスは、具体的な指示ほど修正が少なくて済むとしたうえで、検証手段（テスト、ビルド、スクリーンショット比較）を渡すことを勧めています。この記事では、その公式の型を日本語の指示例に置き換え、計画モードを使うべき場面、「think hard」が効くのかという疑問、うまくいかなかったときの直し方まで、公式ドキュメントの記述どおりに整理します。

Claude Code そのものの仕組みはClaude Codeとは何かを解説した記事に任せ、ここでは「何をどう書くか」だけを扱います。

Claude Code のプロンプトに最初に入れるべきものは何か？

答えは「Claude が実行できるチェック」です。公式ドキュメントは、検証手段がない状態では Claude は作業が終わったように見えた時点で止まり、ミスに気づく役目が人間側に残ると説明しています。

公式が挙げている Before/After を日本語にすると、次のとおりです。

頼みたいこと	Before	After
関数を作らせる	メールアドレスを検証する関数を作って	validateEmail 関数を書いて。テストケースは user@example.com が true、invalid が false、user@.com が false。実装後にテストを実行して
ビルドを直させる	ビルドが失敗している	ビルドがこのエラーで失敗する：[エラーを貼る]。直してビルドが通ることを確認して。エラーを握りつぶさず根本原因を直して

公式の英語原文はこうです。

write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing

もう一つ大事なのが、成功を「宣言」させず、証拠を見せさせることです。公式は、テストの出力、実行したコマンドとその結果、結果のスクリーンショットを示させるよう勧めています。プロンプトの最後に「実行したコマンドと出力をそのまま見せて」と一文添えておくとよいでしょう。

曖昧な指示はどう具体的にすればいいか？

公式ドキュメントは「Claude は意図を推測できるが、心は読めない」と書き、指示の具体化の方法を4つに分けています。

範囲を絞る：どのファイルか、どの状況か、テストの方針はどうするか
情報源を指す：答えを持っている場所（git の履歴など）を教える
既存のパターンを参照させる：同じ種類の実装がコードベースのどこにあるかを示す
症状を書く：何が起きているか、どのあたりが怪しいか、何をもって「直った」とするか

たとえば「foo.py のテストを追加して」は、公式の After では「ユーザーがログアウトしている場合のエッジケースを foo.py のテストで扱って。モックは使わないで」になります。「ログインのバグを直して」は、次のように症状・場所・完了条件がそろった形に変わります。

users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it

プロンプトを日本語で書くなら、たとえば次のような形です。

セッションのタイムアウト後にログインできないという報告がある。src/auth/ の認証フロー、特にトークン更新の処理を確認して。まず不具合を再現する失敗テストを書き、そのあとで修正して。

公式のプロンプト集（Prompt library）は、さらに3つの書き方を補っています。手順ではなく欲しい結果を書くこと（ファイルは Claude に探させる）、性能やカバレッジが目的なら測れる目標値を書くこと、説明が欲しいときは形式・長さ・読み手を指定することです。

バグ修正を頼むときは、再現するコマンド、再現手順、毎回起きるのか時々起きるのかを添えるよう公式のワークフロー集に書かれています。

ただし、プロンプトの曖昧な指示が常に悪いわけではありません。公式は、探索中で軌道修正の余裕があるときは「このファイルで改善するとしたらどこ？」のような緩い問いが、自分では思いつかない論点を拾うのに役立つとしています。

ファイル・画像・エラーログはどう渡せばいいか？

公式ドキュメントが挙げている渡し方は次のとおりです。

@ でファイルを参照する：入力資料の場所を言葉で説明する代わりに @ で指すと、Claude は回答前にそのファイルを読みます
画像を貼る：コピー＆ペーストかドラッグ＆ドロップでプロンプトに入れられます
URL を渡す：ドキュメントや API リファレンスの URL を渡します。よく使うドメインは /permissions で許可リストに入れられます
パイプで渡す：ログの中身を直接送れます

cat error.log | claude -p "explain this error"

コードベースについての質問なら特別な書き方はいらず、直接聞けばよい、と公式は書いています。

計画させてから書かせるべきなのはどんなときか？

公式の推奨ワークフローは「探索 → 計画 → 実装 → コミット」の4段階で、いきなりコードを書かせると間違った問題を解くコードができることがある、という理由で調査・計画と実装を分けるよう勧めています。その切り替えに使うのがプランモードです。プランモードの Claude はファイルを読んで計画を書きますが、ソースは編集しません。

プランモードへの入り方は3つあります。

セッション中に Shift+Tab を押す
1回のプロンプトだけ先頭に /plan を付ける
起動時に指定する

claude --permission-mode plan

提示された計画は Ctrl+G でテキストエディタに開き、直接書き換えてから進められます。計画を承認するとプランモードを抜けて編集が始まります。

一方で、公式は計画にはオーバーヘッドがあるとも明記しています。判断の目安は次のとおりです。

計画を挟む	直接頼む
進め方に確信がない	範囲が明確で修正が小さい
変更が複数ファイルにまたがる	typo の修正、ログ1行の追加、変数名の変更
触るコードに不慣れ	差分を1文で説明できる

プランモードの画面や設定の詳細はClaude Codeのプランモード解説で扱っています。

大きな機能はプロンプトを書く前に何をすればいいか？

最初から完璧なプロンプトを書こうとせず、Claude にインタビューさせる方法が公式に載っています。短い依頼文から始めて、AskUserQuestion ツールで質問させ、技術的な実装、UI/UX、エッジケース、トレードオフを洗い出してもらい、最後に仕様を SPEC.md に書かせる流れです。公式の例文は次のとおりで、[brief description] を作りたい機能の説明に置き換えて使います。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

仕様ができたら、新しいセッションで実装に入るよう公式は勧めています。実装だけに集中したきれいなコンテキストで始められるからです。役に立つ仕様の条件として、変更範囲となるファイルとインターフェースを名指しすること、対象外を書くこと、機能が動くことを示すエンドツーエンドの検証手順で終えることが挙げられています。

「think hard」は効くのか？ultrathink と effort の関係

ここは古い解説と現在の公式ドキュメントで食い違いやすい点です。現在のモデル設定ページによると、ultrathink は Claude Code がキーワードとして認識します。一方、「think」「think hard」「think more」といった言い回しは、普通の文としてそのまま渡され、キーワードとしては扱われません。

ultrathink をプロンプトのどこかに含めると、そのターンだけ深い推論を求める指示が文脈に追加されます。セッションの effort 設定は変わらず、API に送られる effort レベルも変わりません。

adaptive reasoning に対応したモデルでは、思考量を調整する主な手段は effort レベルです。

/effort を引数なしで実行するとスライダーが開き、/effort の後にレベル名を付けると直接設定できます
公式の使い分けでは、low は結果を毎回確認する短いやり取りや名前の変更のような小さな修正向け、high は既存コードのバグ修正のように検証が重要でエッジケースが出やすい作業向けとされています

加えて、もっと頻繁に（または少なく）考えてほしいときは、プロンプトや CLAUDE.md にそう書けば effort の範囲内で反映される、と公式に書かれています。使い分けとしては、難所の1ターンだけ ultrathink を足し、普段の調整は /effort で行う、という分け方が考えられます。

プロンプトに書くことと CLAUDE.md に書くことはどう分けるか？

CLAUDE.md は毎回の会話の開始時に読み込まれるファイルです。そのため公式は、広く当てはまることだけを入れ、ときどきしか要らない知識や手順はスキルに回すよう勧めています。分け方の目安はこうなります。

プロンプトに書く：今回の目的、対象ファイル、今回の完了条件、今回だけの制約
CLAUDE.md に書く：Claude がコードから推測できない Bash コマンド、既定と違うコードスタイル、テストの実行方法、ブランチ名などのリポジトリの作法

書き方も公式に例があります。「コードを適切に整形して」ではなく「インデントは2スペース」、「変更をテストして」ではなく「コミット前に npm test を実行」のように、守れたかどうかを確認できる粒度で書きます。分量は1ファイル200行未満が目安で、長いほどコンテキストを使い、守られにくくなるとされています。

注意したいのは、CLAUDE.md は強制される設定ではなく「文脈」として扱われる点です。どんな場合でも止めたい操作があるなら、公式は PreToolUse フックを使うよう案内しています。CLAUDE.md の書き方そのものはCLAUDE.mdの書き方ガイドで詳しく扱っています。

思った結果にならないときは、どう指示し直せばいいか？

軌道修正には次の4つの操作が使えます。

Esc：作業の途中で止めます。コンテキストは残るので、そのまま方向を指示し直せます
Esc を2回、または /rewind：巻き戻しメニューを開き、以前の会話とコードの状態に戻します
「Undo that（今の変更を取り消して）」：Claude に変更を戻させます
/clear：無関係な作業の間でコンテキストをリセットします

指示し直す回数にも公式の目安があります。同一セッションの同じ問題で2回より多く修正した場合、コンテキストは失敗したやり方で散らかっているので、/clear してから、そこまでで分かったことを織り込んだより具体的なプロンプトで始め直すよう書かれています。

巻き戻しには限界もあります。チェックポイントは新しいターンを開始するプロンプトごとに作られますが、追跡されるのは Claude のファイル編集ツールによる変更だけで、Bash コマンドや外部プロセスによる変更は戻りません。公式も git の代わりにはならないと明記しています。git での確認・取り消しはClaude Codeのgit操作ガイドを参照してください。

長い会話でプロンプトが効かなくなるのはなぜか？

原因はコンテキストウィンドウです。公式は、ほとんどのベストプラクティスが「コンテキストはすぐ埋まり、埋まるほど性能が落ちる」という一つの制約から来ていると説明し、埋まってくると前の指示を「忘れる」、ミスが増えるといったことが起こりうるとしています。最初に書いた制約が後半で守られなくなったら、プロンプトの書き方より先にコンテキストの状態を疑ってください。

公式が挙げている失敗パターンと対処は次のとおりです。

失敗パターン	何が起きるか	対処
1つのセッションに無関係な作業を混ぜる	関係ない情報でコンテキストが埋まる	作業の切れ目で `/clear`
範囲を決めずに「調査して」と頼む	数百のファイルを読んでコンテキストが埋まる	調査範囲を絞るか、サブエージェントに任せる
同じことを何度も修正する	失敗したやり方が文脈に残る	同一セッションの同じ問題で2回を超えて修正したら `/clear` して書き直す

ほかにも、/compact に「API の変更に絞って」のような指示を付けて要約の方向を決めたり、会話に残す必要のない確認を /btw で聞いて履歴を増やさないようにしたりできます。調査は「use subagents to investigate X」のように頼むと、別のコンテキストで調べた要約が返ってくるため、メインの会話を実装向けに保てます。コンテキストの確認方法と圧縮の詳細はClaude Codeのコンテキストウィンドウ解説、サブエージェントの使い方はClaude Codeのサブエージェント活用ガイドにまとめています。

この記事の内容はいつ時点の公式記述か

ここまでの内容は、2026年10月18日に取得した Claude Code 公式ドキュメント（Best practices、Model configuration、Permission modes、Memory、Checkpointing ほか）の記述に基づいています。利用できる effort レベルはモデルによって異なり、一部の操作には Claude Code のバージョン要件があります。手元の挙動が違うときは、/effort status でいま効いている effort レベルを確認し、公式のモデル設定ページと見比べてください。

型を覚えたあと、自分の業務でどう当てはめるかを一緒に練習したい方は、月額1,980円から参加できる学習コミュニティのAI駆動ラボで質問しながら進められます。