はじめに
Claude Codeを使い始めたものの、「思い通りに動かない」「的外れなコードが出てくる」と感じたことはないでしょうか。
原因の多くは、Claude Code自体の性能ではなく プロンプトの書き方 にあります。Claude Codeはエージェント型の開発環境であり、チャットボットとは異なる指示の出し方が求められます。
この記事では、よくある「ダメなプロンプト」を10パターン取り上げ、それぞれ改善例と解説を示します。公式ドキュメントの Best Practices に基づいた内容です。
1. 曖昧すぎる指示
ダメな例
いい感じにして
ダッシュボードをもっと良くして
改善例
ダッシュボードのレスポンス一覧テーブルに、ステータスコード列とレスポンスタイム列を追加して。
テーブルはレスポンスタイムの降順でソートできるようにして。
変更後、既存のテストを実行して通ることを確認して。
ポイント
「いい感じ」「もっと良く」は人間同士でも認識がズレる表現です。Claude Codeに対しては 何を・どう変えるか を具体的に伝えましょう。公式ドキュメントでも「The more precise your instructions, the fewer corrections you'll need（指示が正確なほど、修正の回数が減る）」と明記されています。
2. コンテキストなしの質問
ダメな例
エラーが出る。直して
なんか動かない
改善例
npm run build を実行すると以下のエラーが出る。修正して、ビルドが成功することを確認して。
TypeError: Cannot read properties of undefined (reading 'map')
at UserList (src/components/UserList.tsx:12:34)
ポイント
Claude Codeは超能力者ではありません。エラーメッセージ、再現手順、該当ファイル を伝えることで、根本原因にたどり着けます。公式ドキュメントでも「address the root cause, don't suppress the error（根本原因を解決し、エラーを握りつぶさない）」というパターンが紹介されています。
ログをそのまま渡すなら cat error.log | claude でパイプ入力する方法も有効です。
3. 一度に大量の要求を詰め込む
ダメな例
認証機能を追加して、ダッシュボードのUIを刷新して、APIのレスポンスをキャッシュして、
テストを全部書き直して、READMEも更新して
改善例
まず認証機能を追加したい。src/auth/ を確認して、Google OAuthの実装計画を立てて。
変更が必要なファイルとセッションフローを整理して。
（認証機能が完了してから、次のタスクを別セッションで依頼する）
ポイント
Claude Codeのコンテキストウィンドウは有限です。公式ドキュメントでは 「Most best practices are based on one constraint: Claude's context window fills up fast」 と明記されています。大量のタスクを1セッションに詰め込むと、後半の品質が下がります。
タスクごとに /clear でコンテキストをリセットするか、別セッションで実行しましょう。
4. 既存コードを読ませずに変更を依頼
ダメな例
ユーザー一覧のコンポーネントにページネーションを追加して
改善例
@src/components/UserList.tsx を読んで、現在の実装を把握した上で、
ページネーション機能を追加して。1ページあたり20件表示にして。
既存のページネーションコンポーネント @src/components/Pagination.tsx のパターンに合わせて。
ポイント
@ でファイルを直接参照すると、Claude Codeは確実にそのファイルを読んでから作業します。「既存パターンに合わせて」と指定すれば、プロジェクト内の一貫性も保たれます。
公式ドキュメントでも「Reference files with @ instead of describing where code lives」と推奨されています。
5. 否定形だけの指示
ダメな例
anyは使わないで。classコンポーネントは使わないで。CSS-in-JSは使わないで。
改善例
TypeScriptの型は明示的に定義して。コンポーネントは関数コンポーネント + hooksで実装して。
スタイリングはTailwind CSSを使って。
ポイント
「何をしないか」だけでは、Claude Codeは 何をすべきか を推測するしかありません。否定形の制約は CLAUDE.md に書いておき、プロンプトでは「何をすべきか」を伝えるのが効果的です。
CLAUDE.md に書くべき内容の公式基準は「Would removing this cause Claude to make mistakes?（これを削除したらClaude がミスするか？）」です。プロジェクト全体の禁止事項はそちらに集約しましょう。
6. 過度に詳細な実装手順の指示
ダメな例
まず src/utils/validation.ts を開いて、3行目のimport文の後に新しいimportを追加して、
次に15行目にconst schema = z.object({ と書いて、
16行目に email: z.string().email(), と書いて、
17行目に name: z.string().min(1), と書いて...
改善例
src/utils/validation.ts にZodを使ったユーザー入力のバリデーションスキーマを追加して。
検証するフィールドは email（メール形式）と name（1文字以上）。
バリデーションエラー時は日本語のエラーメッセージを返すようにして。
テストも書いて、実行して確認して。
ポイント
Claude Codeはエージェントです。ファイルを読み、コードを書き、テストを実行する能力があります。行番号レベルの指示を出すと、その判断力を殺してしまいます。
ゴール（何を実現したいか） と 制約（守るべきルール） を伝え、実装方法はClaude Codeに任せましょう。公式ドキュメントでは「you describe what you want and Claude figures out how to build it」と説明されています。
7. ゴールが不明確な指示
ダメな例
パフォーマンスを改善して
セキュリティを強化して
改善例
ユーザー一覧APIのレスポンスタイムが3秒かかっている。
1秒以内に改善したい。
@src/api/users.ts のクエリを確認して、
N+1問題がないか調査し、改善案を提示して。
改善後、レスポンスタイムが短縮されたか確認する方法も教えて。
ポイント
「パフォーマンス改善」「セキュリティ強化」は範囲が広すぎます。現状の課題（3秒かかっている） と 目標（1秒以内） を具体的にすると、Claude Codeはスコープを絞って取り組めます。
公式ドキュメントでは Plan Mode を使って「Explore（調査） → Plan（計画） → Implement（実装）」のフェーズを分ける手法が推奨されています。漠然とした改善テーマにはまず Plan Mode で調査から始めましょう。
8. 前提知識を省略した専門用語の羅列
ダメな例
CQRS + ESでリードモデルのプロジェクションをSagaから非同期で更新するようにリファクタして
改善例
現在、コマンド（書き込み）とクエリ（読み取り）が同じモデルを共有している。
これをCQRSパターンで分離したい。
まず @src/models/ と @src/handlers/ を読んで、現状のアーキテクチャを把握して。
その上で、以下の方針でリファクタリング計画を立てて:
- 書き込みはイベントソーシングで永続化
- 読み取り用のプロジェクション（ビューモデル）を別途構築
- イベント発行後、非同期でプロジェクションを更新
まずは計画だけ出して。実装には入らないで。
ポイント
Claude Codeは専門用語を理解できますが、プロジェクト固有の文脈 は分かりません。同じ用語でもプロジェクトごとに意味や実装方針が異なります。
「まず読んで → 計画を立てて → 実装」のステップを明示すると、Claude Codeが既存コードに合った提案をしてくれます。公式ドキュメントでもこの「Explore → Plan → Implement」フローが推奨されています。
9. 矛盾する要求
ダメな例
テストカバレッジを100%にして。でも既存のテストは変更しないで。
あと、テストの実行時間も半分にして。
改善例
テストカバレッジを改善したい。現状と目標を整理して。
- 現在のカバレッジは src/services/ が60%程度
- まずは src/services/userService.ts のカバレッジを90%以上にしたい
- 既存のテストはそのまま維持して、不足しているケースを追加する形で
- 実行時間が大幅に増える場合は相談して
テストを追加して、カバレッジレポートを出力して確認して。
ポイント
「カバレッジ100%」「既存テスト変更禁止」「実行時間半減」はほとんどの場合、同時に達成できません。矛盾した要求を受けると、Claude Codeはどれかを犠牲にするか、中途半端な結果を返します。
優先順位を明確に し、トレードオフが発生する場合は「相談して」と伝えておくと、Claude Codeが判断に迷わずに済みます。
10. フィードバックなしの連続指示
ダメな例
（1回目）API作って
（結果を見ずに2回目）テスト書いて
（結果を見ずに3回目）デプロイスクリプト作って
（結果を見ずに4回目）ドキュメント書いて
改善例
（1回目）
@src/api/ を参考に、ユーザーのプロフィール更新APIを追加して。
エンドポイントは PUT /api/users/:id/profile で。
テストも書いて、実行して結果を見せて。
（結果を確認した上で2回目）
テスト通った。ただしバリデーションが甘いので、
name は空文字を許可しないように修正して。テストケースも追加して。
ポイント
Claude Codeの公式ドキュメントでは「The best results come from tight feedback loops（最良の結果は短いフィードバックループから生まれる）」と明記されています。
各ステップの結果を確認してから次に進むことで、問題の蓄積を防げます。もし方向がズレていたら Esc で中断するか、/rewind で巻き戻しましょう。2回修正しても改善しない場合は、/clear してプロンプトを書き直すのが公式推奨です。
まとめ：良いプロンプトの5原則
| 原則 | 説明 |
|---|---|
| 具体的に書く | 「何を・どこで・どう変えるか」を明示する |
| 検証手段を与える | テスト実行、スクリーンショット比較、期待出力の提示 |
| スコープを絞る | 1セッション1タスク。終わったら /clear して次へ |
| 既存コードを読ませる |
@ でファイル参照、パターンの指定 |
| フィードバックを返す | 結果を確認 → 修正指示 → 確認、の短いループ |
Claude Codeはエージェント型の開発環境です。チャットボットに質問するのとは異なり、「優秀な開発者に仕事を依頼する」 感覚で指示を出すと、その能力を最大限に引き出せます。
参考
- Best Practices for Claude Code（公式）
- Common Workflows - Claude Code（公式）
- Prompting Best Practices - Claude API Docs（公式）
- CLAUDE.md - Claude Code Docs（公式）
- How Claude Code Works（公式）
@kotaro_ai_lab
AI活用や開発効率化について発信しています。フォローお気軽にどうぞ！