はじめに
2026年に入社した新人エンジニアtakumiです。業務でClaude Codeを使い始めて、プロンプトの書き方一つで出力の質が大きく変わることを実感したので、実際に試した「良いプロンプト」と「悪いプロンプト」の違いをまとめました。これから使い始める方の参考になれば幸いです。
Claude Codeとは
Claude Codeは、ファイルの読み取り・コマンド実行・コード編集を自律的に行うエージェント型のコーディング環境です。チャットボットのように質問に答えて待つのではなく、「何をしたいか」を伝えると、Claude自身が調査・計画・実装まで進めてくれます。
裏を返すと、指示があいまいだとClaudeが誤った前提で進んでしまうリスクもあります。だからこそプロンプトの質が成果物の質を左右します。
悪いプロンプトの特徴
新人がまずやってしまいがちなのが、次のような「ふわっとした」指示です。
- 「バグ直して」
- 「foo.pyのテスト追加して」
- 「ダッシュボードをいい感じにして」
- 「ExecutionFactoryのAPIって何であんな変な作りなの?」
これらに共通するのは、期待するゴールが具体的でない、検証手段が示されていない、参照すべきファイルや文脈が指定されていないという点です。Claudeは文脈を推測して進めますが、推測が外れると手戻りが発生し、結局こちらが全部チェックする羽目になります。
良いプロンプトの特徴
Anthropic公式のベストプラクティスでは、良いプロンプトには次の要素が含まれるとされています。
- 具体的なファイル・シナリオの指定
- 期待する出力・完了条件の明示
- 守るべき制約の提示
- 検証できる基準(テスト・エラー内容・再現条件など)の提供
先ほどの悪いプロンプトを、この観点で書き直すと以下のようになります。
| 観点 | Before(悪いプロンプト) | After(良いプロンプト) |
|---|---|---|
| 検証基準を渡す | implement a function that validates email addresses | write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing |
| UI変更を視覚的に検証 | make the dashboard look better | [デザイン画像を貼付] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them |
| 症状ベースで根本原因に対処 | the build is failing | the build fails with this error: [エラー内容を貼付]. fix it and verify the build succeeds. address the root cause, don't suppress the error |
| タスクの範囲を絞る | add tests for foo.py | write a test for foo.py covering the edge case where the user is logged out. avoid mocks |
| 参照元を指定する | why does ExecutionFactory have such a weird api? | look through ExecutionFactory's git history and summarize how its api came to be |
| 既存パターンを参照させる | add a calendar widget | look at how existing widgets are implemented on the home page. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget... |
| 症状・場所・完了条件を伝える | fix the login bug | 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 |
共通しているのは、「何を」「どこで」「どうなれば完了か」の3点を必ず含めていることです。
具体例:テストコードを書いてもらう場合
実際に手元で試した例です。
悪いプロンプト
テスト書いて
良いプロンプト
src/utils/validateEmail.ts に対するテストを書いてください。
- 正常系: user@example.com → true
- 異常系: invalid, user@.com → false
- モックは使わず実装をそのまま呼び出す
- 実装後に npm test を実行し、失敗があれば修正してください
前者は「テストがある」ことしか保証されず、観点が漏れたり、実装の意図と違うテストになったりします。後者はゴールと検証条件が明確なので、Claudeが自分でテストを実行し、失敗すれば修正まで完了させてくれます。
プロンプト以外に効果があったこと
プロンプト単体の工夫だけでなく、次の2つも出力の質に効いています。
Plan Mode(調査→計画→実装を分ける)
いきなり実装させると、見当違いの実装になることがあります。Plan Modeを使うと、Claudeはまずファイルを読んで理解するだけで、変更は行いません。理解した内容をもとに実装計画を立ててもらい、計画を確認してから実装フェーズに進むことで、手戻りを減らせます。
- 差分が1行で説明できる小さな修正 → Plan Mode不要、直接依頼
- 複数ファイルに影響する変更、不慣れなコードの変更 → Plan Modeで計画してから実装
CLAUDE.md(繰り返し伝える文脈を固定化する)
プロジェクトごとのコマンドやコーディング規約を毎回プロンプトに書くのは非効率です。CLAUDE.md に以下のような情報を書いておくと、Claudeが会話の最初に自動で読み込んでくれます。
# コマンド
- テスト実行: npm test
- Lint: npm run lint
# コーディング規約
- import はES Modules形式を使う(require禁止)
- 可能な限り分割代入を使う
公式ドキュメントでも「各行について、消したらClaudeがミスするか?を自問し、そうでなければ削る」ことが推奨されています。長すぎると重要なルールが埋もれて逆に無視されるようになるためです。
まとめ
- 悪いプロンプトは「ゴールがあいまい」「検証手段がない」「文脈の指定がない」
- 良いプロンプトは「対象ファイル」「完了条件」「制約」「検証基準」を含む
- 大きめの変更はPlan Modeで計画を挟むと手戻りが減る
- 繰り返し使う文脈はCLAUDE.mdに書いて毎回のプロンプトをシンプルにする
新人としてまだ手探りですが、プロンプトを「業務指示書」として書く意識に変えるだけで、Claude Codeの出力の安定感が明らかに変わりました。同じように使い始めた方の参考になれば幸いです。