【vol.13】Claude Codeで結果が激変するプロンプト設計5原則 改善前→改善後の実例つき
シリーズ第3回です(第1回はこちら/前回はこちら)。
Claude Codeを数日使うと、多くの人がこう感じます。「便利だけど、思っていたほど一発で決まらない」。
原因のほとんどはAIの性能ではなく、指示の設計にあります。私も最初の頃は出力の手直しに時間を使っていましたが、指示の型を変えてから、やり直しの回数が体感で半分以下になりました。
チャットAI向けのプロンプト術と、エージェント向けのそれは別物です。エージェントは「実際に作業する」ので、作業者への仕事の頼み方——つまり、ゴール・制約・確認方法までを含めた依頼が必要になります。この記事ではそれを5つの原則に整理します。
この記事で学べること
エージェントへの指示がチャットAIと違う理由
結果が変わる5原則(すべて改善前→改善後の実例つき)
大きな変更で事故らないプランモードの使い方
プロジェクトの規模に応じた指示の使い分け方
「作ってほしいもの」ではなく「仕事の完了条件」を伝える
5原則に入る前に、根っこの考え方を1つ。Claude Codeへの指示で最も重要なのは、「何を作るか」に加えて「何ができたら完了か」を伝えることです。
外注に仕事を頼む場面を想像してください。「いい感じのサイトを作ってください」では見積もりすら出ません。「この3ページ構成で、スマホ対応必須、公開前にこのチェックリストで確認」なら、期待通りのものが返ってきます。エージェントへの指示は外注への発注書に近い、というのが本質です。
原則①:ゴールと制約をセットで伝える
改善前:
検索機能を追加して改善後:
商品一覧ページに検索機能を追加して。
- 対象: 商品名と説明文の部分一致
- 入力のたびに絞り込み(検索ボタンなし)
- 既存のUIコンポーネントを使い、新しいライブラリは追加しない改善前の指示だと、Claude Codeは検索方式もUIも勝手に決めるしかありません。それが期待とずれると全部やり直しです。制約(特に「〜しない」)を先に伝えるのが、手戻りを減らす最大のコツです。
原則②:既存コードを「先に読ませて」から作業させる
改善前:
ユーザー登録のAPIを作って改善後:
まず src/app/api/login/route.ts を読んで、このプロジェクトの
APIの書き方(エラー処理・バリデーションの流儀)を把握して。
そのスタイルに合わせてユーザー登録APIを作って。既存プロジェクトでの作業は、これだけで品質が別物になります。参照先を指定しないと、AIは一般的な書き方で書くため、プロジェクト内に「流儀の違うコード」が混ざっていきます。
原則③:大きな仕事は「計画→承認→実装」に分ける
大規模な変更を一発で頼むのは失敗のもとです。Claude Codeには実装せず計画だけ立てるプランモード(Shift+Tabで切替)があります。
使い方の実例:
(プランモードで)
この記事管理アプリに下書き自動保存機能を追加したい。
影響するファイルと実装方針を先に説明して。計画を読んで、方針がずれていればその場で修正指示。納得してから「その計画で実装して」と進めます。書き直しのコストはコードより計画のほうが圧倒的に安い。これがエージェント時代の鉄則です。
原則④:検証方法まで指示に含める
改善前:
このバグを直して改善後:
カートの合計金額がマイナスになるバグを直して。
再現手順: 商品を追加→数量を0に変更→合計が-500円になる。
修正後は npm test を実行して、既存テストが全部通ることを確認して。
可能ならこのバグの再発を防ぐテストも追加して。Claude Codeはコマンドを実行できるので、「直したつもり」で終わらせず「検証済み」まで任せられます。テスト・型チェック・ビルドなど、完了の判定方法を必ず指示に入れてください。
原則⑤:繰り返し言うことはCLAUDE.mdに書く
3回同じ注意をしたら、それはCLAUDE.md(第2回参照→リンク)行きのサインです。
# CLAUDE.mdへの追記例
- コメントは日本語で書く
- 環境変数を追加したら .env.example にも反映する
- console.log をコミットに残さない指示のたびに書く内容が減るほど、日々のプロンプトは短く、結果は安定します。**良いプロンプト設計の最終形は「短い指示で意図が通じる環境づくり」**です。
失敗例:丁寧なのに失敗する指示
意外な落とし穴を1つ。長く丁寧に書けばいいわけではありません。
(失敗例)
ログイン機能とプロフィール編集と通知設定と検索とダークモードを
追加してください。それぞれ仕様は……(2000字)一度に5機能を頼むと、途中の判断ミスが後続全部に波及します。1回の依頼は1テーマ。5機能なら5回に分け、1つずつ動作確認しながら進めるほうが、結果的に速くて確実です。
プロジェクト規模別・指示の使い分け
5原則をすべて毎回フル装備する必要はありません。変更の規模に応じて力の入れ方を変えるのが実践的です。
・変更の規模: 小(1ファイル程度の修正)／目安: 誤字修正・スタイル調整等／使うべき原則: 原則①(制約)のみで十分
・変更の規模: 中(1機能の追加・修正)／目安: 検索機能追加等／使うべき原則: 原則①②④(制約・既存参照・検証)
・変更の規模: 大(複数ファイルにまたがる変更)／目安: 新機能一式・大規模リファクタ／使うべき原則: 原則①〜⑤すべて、特に③(プランモード)必須
判断のコツ: 「これが失敗したら手戻りにどれくらい時間がかかるか」を先に考えてください。手戻りコストが大きいと予想される変更ほど、プランモードでの事前確認に時間をかける価値があります。
自己診断チェックリスト
指示を送る前に、この5問で自己診断してください。
ゴールだけでなく、制約(〜しないこと)も伝えたか?
既存プロジェクトの場合、参照すべきファイルを指定したか?
変更が複数ファイルにまたがる場合、先に計画を確認したか?
完了の確認方法(テスト・ビルド等)を含めたか?
同じ注意を3回以上伝えていないか?(CLAUDE.mdへの移動サイン)
3つ以上「いいえ」があれば、原則に立ち返ってプロンプトを見直してみてください。
ケーススタディ:指示が変わった2週間
1週目: 「◯◯を実装して」という一文だけの指示が中心。出力は動くには動くが、既存コードのスタイルと合わず、毎回手直しが発生していた。
2週目: 原則②(既存コードを先に読ませる)を意識し始め、大きな変更には原則③(プランモード)を使うようにした。結果、手直しの回数が大きく減り、「思っていたのと違う」という手戻りがほぼなくなった。
このケースからの学び: 5原則を一度に全部使いこなす必要はありません。まず「既存コードを読ませてから作業させる」の1つから始めるだけでも、既存プロジェクトでの作業品質は大きく変わります。
用語集
・プランモード：実装前にAIに計画だけを説明させ、人間が承認してから実装に進むモード
・完了条件：「何が確認できれば完了とみなすか」を明示した基準(テスト通過等)
・制約：やってほしいことの範囲を限定する条件(使う技術・変更してよい範囲等)
・手戻り：方向性のズレにより、やり直しが発生すること。プランモードで事前に防げる
よくある質問
Q. 毎回長いプロンプトを書くのは面倒です。短くする方法は?
A. 繰り返し伝えている注意点はCLAUDE.md(第2回)に書いておくと、毎回書かなくても環境が守ってくれます。指示自体は短く保てます。
Q. 「まず計画を説明して」を毎回付けるべきですか?
A. 変更が小さい(1ファイル程度)場合は不要なことが多いですが、複数ファイルにまたがる変更や重要な機能では、プランモードで先に方向性を確認する方が手戻りが少なくなります。
Q. 5原則を全部守らないと使えませんか?
A. いいえ、まずは「ゴールと制約を具体的に伝える」の1つだけ意識するだけでも成果は大きく変わります。慣れてきたら他の原則を足していく進め方で十分です。
外部リンク候補
Anthropic公式のプロンプトエンジニアリングガイド
エージェントへの指示は「発注書」。ゴール+制約+完了条件をセットで
既存コードは先に読ませてから書かせる
大きな変更はプランモードで計画→承認→実装
検証(テスト・ビルド)まで指示に含めて「確認済み」で受け取る
繰り返しの注意はCLAUDE.mdへ。指示は短く、環境で質を上げる
なお、この5原則を実務の各場面(要件定義・設計・レビュー・バグ修正など)に落とし込んだ完成版プロンプト60本は、第8〜10回の「Claude Code Ultimate Prompt Collection」で公開予定です。
型を覚えたら、作りましょう。第4回「Claude CodeでWebアプリを作る方法」では、企画からデプロイまで、実際の指示の流れをそのまま見せながらToDoアプリを完成させます。初めての「AIと作り切る」体験です。
→ 第4回はこちら
※機能名・操作は執筆時点(2026年7月)の情報です。最新情報はAnthropic公式ドキュメントをご確認ください。
