Claude Codeで良いプロンプトを書く5つのコツ｜Before/After付き

「このコンポーネント、いい感じにリファクタしといて」

そう頼んだら、Claude Codeは関係ないファイルまで5つ書き換え、ついでに使ってないライブラリを1つ追加して、テストは1本も足さずに「完了しました」と返してきました。

僕はその差分を30分かけて巻き戻しました。

腹が立つ前に気づいたんです。悪いのはAIじゃない。「いい感じ」としか言ってない僕のほうだ、と。同じ依頼を、新人に渡したら同じ結果になります。何を直すのか、どこは触っちゃダメか、どうなったら合格か——全部こっちが省いていたんですから。

それ以来、プロンプトの書き方をひとつずつ直していきました。コツは5つに絞れます。しかも難しいテクニックじゃなくて、「頼み方の段取り」を変えるだけです。今日はそれを、僕が実際に踏んだ失敗と、Before/Afterの実例で書きます。

この記事の要点

• Claude Codeの出力がぶれる原因の大半は、モデルの賢さではなく依頼文の情報不足。
• 効くコツは5つ。①曖昧語を消す（具体性）、②文脈と制約を渡す、③出力形式を指定する、④例を1つ見せる、⑤一発で決めず反復で詰める。
• どれもBefore/Afterで効果がはっきり出る。長文を書く必要はなく、足りない材料を足すだけ。
• プロンプトを毎回ゼロから書かず、よく効いた依頼文は保存して使い回すと一気に楽になる。

なぜ「いい感じに」では動かないのか

最初に勘違いを1つ捨てておきます。プロンプトは「お願い文」ではありません。作業指示書です。

Claude Codeは推測で動けます。情報が足りなければ、足りないところを自分で埋めて進みます。問題は、その推測が増えるほど成果物があなたの頭の中とズレることです。「いい感じ」と書くと、AIはAIなりの「いい感じ」を全力でやる。だから事故る。

僕の感覚だと、出力の質はこの式で決まります。

出力の質 ＝ モデルの賢さ × 依頼文の情報量

モデルはもう十分賢いんです。だから伸びしろは右側の「情報量」にある。そして情報量は、長く書くことじゃなくて、抜けを埋めることで上がります。次の5つが、その「埋めるべき抜け」です。

ちなみに、Claude Codeがプロジェクトのどんな情報を読んで動くかは、公式の Claude Code overview に載っています。仕様はちょくちょく変わるので、権限や設定まわりは原典を見るのが確実です。

コツ	平たく言うと	抜けると起きること
①具体性	曖昧語を消す	見当違いの方向に全力で進む
②文脈と制約	前提と「やっちゃダメ」を渡す	サイトに合わない、設計を外す
③出力形式	欲しい形を指定する	受け取った後に整形し直す手間
④例示	お手本を1つ見せる	言葉だけでは伝わらない暗黙ルールがズレる
⑤反復	一発で決めず詰める	惜しい出力を捨てて最初からやり直す

ひとつずつ、Before/Afterでいきます。

コツ1：曖昧語を消して、具体的に頼む

いちばん効くのにいちばん雑になりがちなのが、これです。

「いい感じ」「ちゃんと」「最適化して」「きれいに」——この手の言葉は、人間同士なら空気で伝わります。でもAIには判定基準がない。「最適化」が速度なのか可読性なのかバンドルサイズなのか、向こうには分からないんです。

Before。曖昧語のかたまりです。

このアプリのパフォーマンスを最適化して。

After。何を、どの指標で、どこまでやるかを言い切ります。

src/pages/index.astro の初期表示を速くしたい。
目標: Lighthouse の Performance を 80 以上にする。
やること: 画像の遅延読み込みと、未使用CSSの削除まで。
やらないこと: ライブラリの追加や、デザインの変更。
最後に、変更点と Before/After の数値を報告して。

差は一目瞭然ですよね。Afterは「速さ＝Lighthouse 80」と判定基準を渡しているので、AIは自分で合格・不合格を判断できます。

僕が今でも気をつけているのは、形容詞を数字か固有名詞に置き換えること。「軽く」→「100KB以下に」、「読みやすく」→「1段落3行以内に」、「直して」→「このファイルのこの関数を」。これだけで出力が驚くほど安定します。

コツ2：文脈と制約を、先に渡す

Claude Codeはコードを読めます。でも、あなたの事業の事情や、過去にやらかした地雷までは読めません。だから前提（文脈）と、踏んでほしくない地雷（制約）を先に渡します。

ここで僕がいちばん効果を感じたのが「触らないことリスト」です。やってほしいことを書く人は多いけど、やってほしくないことを書く人は少ない。でも事故はたいてい「触ってほしくなかった場所」で起きます。

Before。範囲が無限大です。

記事のSEOを改善して。

After。前提と境界線をはっきりさせます。

このサイトは Astro の content collection で記事を管理しています。
対象は site/src/content/blog/5-tips-for-better-prompts.mdx の1ファイルだけ。

触ってよい範囲:
- frontmatter の title / description / tags
- 本文

触らない範囲:
- heroImage、ファイル名（slug）
- 他の記事、ビルド設定

守ってほしいこと:
- description は120字以内
- 本文に内部リンクを2本以上、公式の外部リンクを1本以上

文脈がないと、きれいだけどこのサイトの空気に合わない記事が出てきます。制約がないと、隣の記事まで「ついでに」直されます。両方渡すと、レビューが一気に楽になります。

毎回この前提を打ち込むのは正直だるいです。僕はプロジェクト共通のルールは CLAUDE.md に寄せて、毎回書かずに済むようにしています。やり方は CLAUDE.mdの書き方ベストプラクティス にまとめました。

コツ3：出力形式を指定する

意外と見落とされがちなのが、「どんな形で返してほしいか」です。

形を指定しないと、AIは長い散文で返してきます。読むのは大変だし、後で使うときに自分で表やJSONに直す羽目になる。だったら最初から形を指定したほうが速いです。

Before。形がフリーダムです。

このAPIのエラーをまとめて。

After。表で、列まで指定します。

src/api/ のエラーハンドリングを調べて、結果を Markdown の表にして。
列は「ファイル」「行」「エラー種別」「対処の優先度（高/中/低）」の4つ。
表の前後に説明文はいらない。表だけ出して。

「JSONで」「箇条書き5個で」「diff形式で」「表で、列はこれ」——欲しい形を1行足すだけで、受け取った後の作業がゼロになります。

地味なコツですが、僕は「説明文はいらない、◯◯だけ出して」という一文をよく付けます。AIは親切心で前置きや要約を足しがちなので、それを先に断っておくと、コピペしてそのまま使える出力になります。

コツ4：例を1つ見せる

言葉で10行説明するより、お手本を1つ見せたほうが速いことがあります。これは「few-shot（数例提示）」と呼ばれる、平たく言えば「見本を渡す」やり方です。

特に、コミットメッセージの書式、命名規則、ログの出し方みたいな「暗黙のルール」は、言葉にしづらい。そういうときはサンプルを貼るのが一番伝わります。

Before。言葉で頑張って説明しています。

コミットメッセージは、種別を頭につけて、簡潔に、現在形で書いて。

After。お手本を1個貼るだけ。

これから作る変更に、コミットメッセージを付けて。
書式はこの例にそろえて:

feat: ログイン後の白画面を修正
fix: フォーム送信時のバリデーション漏れを追加
docs: READMEにセットアップ手順を追記

種別は feat / fix / docs / refactor から選ぶ。

例を1つ渡しただけで、種別の選び方も、文の長さも、語尾も、一気に揃います。言葉で縛るより、見本のほうが誤解が少ないんです。

注意点が1つ。悪い例も一緒に見せると、さらに精度が上がります。「こう書かないで」を1個添えるだけで、避けてほしい方向がはっきり伝わります。

コツ5：一発で決めず、反復で詰める

最後はマインドの話です。完璧なプロンプトを一発で書こうとしないでください。

僕は長いこと「最初の指示で全部決めなきゃ」と気負っていました。でも実際は、AIの最初の出力を叩き台にして、ズレたところだけ短く指摘するほうが、ずっと速くて正確です。

惜しい出力が来たとき、最初からやり直すのは大損です。そこから差分で詰めます。

（1回目の出力に対して）
方向はいい。3点だけ直して:
1. 見出しが多すぎる。h2を5個までに減らして。
2. コード例の変数名を snake_case にそろえて。
3. 最後に「未対応のこと」を箇条書きで3行足して。
他は今のままでいい。

ポイントは「他は今のままでいい」と言い切ること。これを付けないと、AIは良かった部分まで親切に作り直して、せっかくの出力が崩れます。

それでも噛み合わないときは、戻って①〜④のどれかが抜けていないか確認します。たいてい、具体性か制約のどちらかが足りていません。反復は、足りない材料を1つずつ足していく作業だと思うとうまくいきます。

コピペで使える：5コツ入りの依頼テンプレート

毎回ゼロから書く必要はありません。下のスクリプトを実行すると、5つのコツを全部含んだ依頼書のひな形 prompt-brief.md ができます。Goal と Scope を書き換えてから Claude Code に渡してください。

cat > prompt-brief.md <<'EOF'
# Claude Code 依頼書

## 目的（具体的に・曖昧語なし）
- 例: src/pages/index.astro の初期表示を Lighthouse 80 以上にする

## 文脈（前提）
- 使っている技術 / 参考にする既存ファイル:
- 守るべき設計ルール:

## スコープ（制約）
- 触ってよい:
- 触らない:

## 出力形式
- 例: 変更点を Markdown の表で。前置きの説明文は不要。

## お手本（例示・あれば貼る）
- 良い例:
- 避けたい例:

## 完了条件
- 判定できる合格ライン（数値・固有名詞で）:
- 最後に「変更点・確認したこと・残るリスク」を報告する。
EOF
echo "prompt-brief.md を作成しました。GoalとScopeを埋めてClaude Codeに渡してください。"

このひな形を1回作っておけば、あとは中身を差し替えるだけ。「具体性・文脈・制約・形式・例」が最初からそろうので、反復の回数もぐっと減ります。作った依頼文のうち「よく効いたもの」を保存して資産にする話は、Claude Codeプロンプトライブラリ運用 に詳しく書きました。チームで使うなら、こっちが本命です。

僕がやらかしたプロンプトの失敗3つ

正直に書きます。5コツにたどり着くまで、だいぶ遠回りしました。

ひとつ目は、情報を足すほど良いと思い込んだこと。前提を10行も書いたら、AIが本題を見失って、注意書きだけ丁寧な薄い成果物を返してきました。今は「目的・スコープ・形式」を先頭に置き、背景は後ろに短く回しています。順番も情報量のうちでした。

ふたつ目は、制約を書かずに後悔したこと。「触らないで」を省いたせいで、収益用の内部リンクを別の修正のついでに消された日があります。気づいたのは公開後。それ以来、「触らないことリスト」だけは何があっても書きます。

みっつ目は、惜しい出力を毎回捨てたこと。8割いい出力を、最初から作り直していました。差分で詰めるやり方を覚えてからは、同じ品質に半分の時間で着地できるようになりました。

よくある質問

Q. プロンプトは長く書いたほうがいいんですか？ 長さは関係ありません。大事なのは「具体性・文脈・制約・形式・例」の抜けを埋めることです。短くても抜けがなければ十分動きます。逆に、長くても曖昧語だらけならぶれます。

Q. 日本語と英語、どちらで書くべき？ 日常タスクは日本語で問題ありません。僕も普段は日本語です。ただし、コミットメッセージやコード内コメントなど「成果物の言語」が決まっているものは、その言語のお手本（コツ4）を貼ると揃いやすいです。

Q. 5つ全部、毎回入れないとダメですか？ いいえ。小さな依頼なら「具体性」と「制約」の2つでも十分なことが多いです。出力がぶれたと感じたら、足りていないコツを1つずつ足してください。反復（コツ5）で調整する前提で大丈夫です。

Q. どうしても思いどおりに動きません。 たいてい原因は2つです。合格ラインが判定不能（「読みやすく」など）か、触ってよい範囲が広すぎるか。まずこの2点を数値と固有名詞で締め直してください。それでも噛み合わなければ、お手本を1つ貼ると一気に伝わります。

Q. プロンプトを毎回考えるのが面倒です。 よく効いた依頼文は保存して使い回すのが正解です。上のテンプレートを起点に、自分の頻出タスク（バグ修正・記事生成・調査）ごとに型を持っておくと、考える時間そのものが消えます。

実際に試した結果

この5コツを自分の運用に入れてから、Claude Codeへの依頼の「やり直し率」が体感で半分以下になりました。

いちばん効いたのは、地味ですが**コツ2の「触らないことリスト」**です。やってほしいことより、やってほしくないことを書くほうが、事故が減る。冒頭の“勝手に5ファイル書き換え事件”は、たった2行「他の記事とビルド設定は触らない」と足すだけで起きなくなりました。

次に効いたのがコツ1の「形容詞を数字に置き換える」。「速く」「きれいに」を「Lighthouse 80」「1段落3行」に変えるだけで、合格・不合格をAI自身が判断してくれるようになり、僕がレビューで悩む時間が減りました。

結局のところ、良いプロンプトは才能じゃなくて段取りです。賢いAIを待つより、抜けのない頼み方を1つずつ身につけるほうが、はるかに速く成果に届きます。まずは次の依頼で、「触らないことリスト」を2行だけ足してみてください。それだけで、明日のレビュー時間が変わります。

繰り返し使う型を手元にそろえたいなら 教材一覧、チームのプロンプト運用ごと整えたいなら Claude Code研修・導入相談 もどうぞ。普段の作業の型は Claude Code生産性Tips も合わせて読むとつながります。