結論：Claude Codeでコード生成の品質を上げるプロンプト設計は、「何を書かせるか」ではなく「どの文脈で、どこまで変更し、何で検証するか」を設計する作業です。
- 要点1：Claude Codeはコードベースを読み、編集し、コマンドを実行し、結果を検証するエージェント型の開発環境です。プロンプトも「会話」ではなく「作業指示書」として設計します。
- 要点2：良いプロンプトには、目的、参照すべき既存パターン、変更範囲、制約、検証コマンド、完了条件を入れます。
- 要点3：繰り返し使う指示は毎回チャットに貼らず、
CLAUDE.md、skills、hooks、settings に分離すると、チーム運用でも品質が安定します。
対象読者：Claude Codeを使い始めた開発者、テックリード、PM、社内導入を設計するエンジニアリングマネージャー。
今日やること：この記事の「実務用プロンプトテンプレート」を1つ選び、現在のリポジトリでテスト・lint・buildの検証条件まで入れて試してください。
「Claude Codeに頼んだのに、思ったのと違う実装になった」
この相談は、Claude Codeを使い始めたチームでかなりよく起きます。たいていの場合、原因はモデルの性能ではありません。プロンプトが「コードを書いて」だけで終わっていて、Claude Codeが読むべき文脈、守るべき制約、止まるべき条件が定義されていないんです。
Claude Codeは、単に回答文を返すチャットではありません。公式ドキュメントでは、Claude Codeはコードベースを読み、ファイルを編集し、コマンドを実行し、結果を検証する agentic coding tool と説明されています。つまり、プロンプトは「質問」ではなく、エージェントに渡す作業仕様に近いものになります。
正直、最初のうちは「詳細に書きすぎると逆に動きが悪くなるのでは？」と思うかもしれません。でも実務では逆です。Claude Codeが自律的に動ける範囲が広いからこそ、入口のプロンプトでゴール、境界、検証方法を明確にした方が、手戻りが減ります。
この記事では、Claude Codeの公式ドキュメントで確認できる機能だけを前提に、コード生成プロンプトの7原則を整理します。すぐ使えるプロンプト例、悪い例と良い例、チーム展開時の注意点までまとめました。
Claude Codeのプロンプト設計は「作業の設計」である
Claude Codeのプロンプト設計を理解するには、まず普通のチャットAIとの違いを押さえる必要があります。
公式ドキュメントの「How Claude Code works」では、Claude Codeの作業は「文脈を集める」「行動する」「結果を検証する」というループで説明されています。ファイル検索、編集、テスト実行、コマンド実行をまたいで進むため、1回のプロンプトがそのまま作業計画になります。
そのため、Claude Codeへの指示で重要なのは「どんなコードを出力してほしいか」だけではありません。むしろ、次の6点が抜けると品質が不安定になります。
- 何を達成したいのか
- どの既存コードや設計に合わせるのか
- どこまで変更してよいのか
- 何を変更してはいけないのか
- どのコマンドで検証するのか
- 成功・失敗をどう判断するのか
たとえば「ログイン機能を作って」では、Claude Codeは仕様を推測するしかありません。一方で、「既存の src/features/profile と同じ構成で、メールログインのエラーハンドリングを追加し、pnpm test auth と pnpm typecheck が通るまで修正してください」と書くと、作業のゴールがかなり明確になります。
Claude Codeの基本的な使い方全体を先に整理したい場合は、関連記事の Claude Code実践テクニック完全ガイド もあわせて読むと、この記事の7原則を運用に落とし込みやすくなります。
まず押さえるべき公式機能と前提
この記事で扱うプロンプト設計は、2026年7月7日時点で Claude Code公式ドキュメントに掲載されている機能を前提にしています。未確認の隠し機能、独自ショートカット、非公式プラグイン前提の書き方は使いません。
1. Claude Codeはコードベース全体を扱う
公式ドキュメントでは、Claude Codeはプロジェクトのファイル、ターミナル、git状態、CLAUDE.md、auto memory、MCP、skills、subagents などを文脈として扱えると説明されています。だから、プロンプトでは「このファイルだけ見て」よりも、「まず関連ファイルを探索して、既存パターンを確認してから実装して」と書く方が自然です。
2. CLAUDE.mdは毎回の共通指示に向いている
Claude Code公式の memory ドキュメントでは、CLAUDE.md はプロジェクトやチームの永続的な指示を書く場所として説明されています。ただし、これは強制設定ではなくコンテキストです。必ず守らせたい安全制御は、後述する settings や hooks 側で扱います。
3. settings は権限・環境・ツール挙動を設定する
公式 settings ドキュメントでは、~/.claude/settings.json や .claude/settings.json などのスコープ、権限、環境変数、hook 設定が説明されています。特に機密ファイルを読ませたくない場合は、permissions.deny で .env や credentials ファイルを除外する設計が重要です。
4. commands、subagents、hooks はプロンプト品質を補強する
Claude Codeには、/clear、/compact、/diff、/code-review などのコマンドがあります。subagents は探索や検証を別コンテキストで行うために使えます。hooks は特定のタイミングでシェルコマンドやHTTPエンドポイントなどを実行できる仕組みです。プロンプトだけで頑張るのではなく、これらを組み合わせると安定します。
コード生成プロンプトの7原則
ここから、Claude Codeで実務品質のコード生成を行うための7原則を見ていきます。細かいテクニックは多いですが、基本はこの7つに集約できます。
| 原則 | 狙い | プロンプトに入れる要素 |
|---|---|---|
| 1. 成果物を先に定義する | Claude Codeが何を完成と見るかを固定する | 目的、完成形、対象ユーザー、受け入れ条件 |
| 2. 文脈を渡す | 既存設計に沿ったコードを生成する | 参照ファイル、既存パターン、ドメイン知識 |
| 3. 変更範囲を切る | 余計なリファクタや副作用を防ぐ | 編集してよい領域、触らない領域、非目標 |
| 4. 検証方法を先に指定する | 「動いたつもり」を減らす | テスト、lint、typecheck、build、スクリーンショット |
| 5. 探索・計画・実装を分ける | 大きな変更で問題設定を間違えない | 調査、計画、承認、実装、確認 |
| 6. 繰り返す指示を外部化する | 毎回のプロンプトを短く保つ | CLAUDE.md、skills、commands、rules |
| 7. 安全境界とコンテキストを管理する | 長時間作業とチーム利用の事故を減らす | permissions、hooks、subagents、/clear、/compact |
この7原則は、特定の言語やフレームワークに依存しません。ReactでもRailsでもGoでもPythonでも、Claude Codeに渡す「作業仕様」の骨格は同じです。
原則1：成果物を先に定義する
最初の原則は、成果物を先に定義することです。Claude Code公式の Prompt library でも、うまく機能するプロンプトの特徴として「手順ではなく成果を説明する」ことが挙げられています。
ここでいう成果物とは、「コードを書いて」ではありません。どのユーザーが、どんな操作をしたとき、どんな結果になれば完成なのかまで含みます。
悪い例
ログイン機能を追加して。これだと、Claude Codeは認証方式、UI、API、バリデーション、テスト範囲をすべて推測します。既存プロジェクトなら、推測の余地が多いほど既存設計からズレます。
良い例
メールアドレスとパスワードでログインできる画面を追加してください。
完成条件:
- ユーザーは /login でメールアドレスとパスワードを入力できる
- APIが401を返した場合は、フォーム上に認証エラーを表示する
- 成功時は既存のダッシュボード遷移処理を使う
- 既存の認証ストアとルーティング設計に合わせる
- 不足している情報があれば、最初に質問してから作業を開始してください
検証:
- 関連する単体テストを追加する
- pnpm test auth と pnpm typecheck を実行する
- 失敗した場合は原因を説明して修正するこのプロンプトのポイントは、「作って」ではなく「完成条件」を書いている点です。Claude Codeにとって、検証可能な完成条件があると作業の終点が見えます。
成果物定義に入れるべき項目
- ユーザー操作：誰が何をするのか
- 期待結果：成功時と失敗時に何が起きるのか
- 対象範囲：画面、API、DB、テストのどこまで含めるのか
- 非対象範囲：今回やらないことは何か
- 検証方法：どのコマンドやテストで完了を確認するのか
実務では、「成果物を1文で説明できない状態」でClaude Codeに実装を頼むと、ほぼ確実に途中で仕様確認が発生します。最初に成果物を小さく切るだけで、生成コードの精度はかなり変わります。
原則2：文脈を渡す
Claude Codeはコードベースを読めます。だからこそ、文脈を渡すプロンプトが強いです。公式ベストプラクティスでも、具体的なファイル、制約、既存パターンを示すことが推奨されています。
ここで重要なのは、すべてを説明しすぎないことです。人間が長々と要約するより、「このディレクトリを読んで既存パターンを確認して」と指示した方が、Claude Codeの強みを活かせます。
参照ファイルを指定する例
既存の設定画面と同じUIパターンで、通知設定画面を追加してください。
まず以下を読んで、既存の構成・命名・フォーム処理を把握してください。
- src/features/settings/ProfileSettings.tsx
- src/features/settings/BillingSettings.tsx
- src/features/settings/settings.schema.ts
実装方針:
- 新規画面は src/features/settings/NotificationSettings.tsx に作る
- フォーム状態管理は既存設定画面と同じ方法にする
- 新しいUIライブラリは追加しない
- 仮定した点は必ず「仮定」と明記してください
検証:
- pnpm test settings
- pnpm lint
- pnpm typecheckこの書き方では、Claude Codeが「既存に合わせる」ための材料を渡しています。特に大規模コードベースでは、正しい文脈を見つけるだけで時間がかかります。参照ファイルを2〜5個指定するだけでも、かなり安定します。
文脈が足りないと起きること
- 既存の命名規則と違う名前でファイルを作る
- プロジェクトで使っていないライブラリを提案する
- 既存のエラーハンドリングを無視する
- 似た機能がすでにあるのに重複実装する
- テストの書き方が既存スタイルから外れる
ここは現場でよく詰まるポイントです。「Claude Codeが勝手に違う実装をした」と感じるとき、実際には「どの既存パターンに合わせるべきか」を人間が渡していないケースが多いんです。
原則3：変更範囲を切る
Claude Codeは、必要だと判断すれば複数ファイルを横断して編集できます。これは強力ですが、プロンプトが曖昧だと「ついでの改善」が増えることがあります。
コード生成で大事なのは、変更してよい範囲と、今回は触らない範囲を明記することです。特に既存プロダクトでは、リファクタリングと機能追加を混ぜるとレビューが難しくなります。
変更範囲を切るプロンプト
商品一覧APIに、在庫ステータスで絞り込むクエリパラメータを追加してください。
変更してよい範囲:
- src/api/products/**
- src/domain/product/**
- tests/products/**
変更しない範囲:
- 認証・認可の仕組み
- DBマイグレーション
- UIコンポーネント
- 既存のページネーション仕様
非目標:
- レスポンス形式の全面変更はしない
- パフォーマンス最適化は今回の対象外
受け入れ条件:
- ?stock=in_stock / low_stock / out_of_stock で絞り込める
- 無効な値は400を返す
- 既存のページネーションと併用できる
- 既存テストを壊さない
数字と固有名詞は、根拠またはコード上の参照箇所を添えてください。このように「変更しない範囲」と「非目標」を書くと、Claude Codeは過剰な設計変更を避けやすくなります。レビューする人間にとっても、差分の意図が読みやすくなります。
小さな差分に分ける判断基準
- DBスキーマ変更があるなら、実装とは別セッションにする
- UI変更とAPI変更は、可能なら別プロンプトにする
- 既存リファクタは、機能追加と同時に頼まない
- テスト追加だけのセッションを作ると、仕様の抜けが見つかりやすい
- レビュー差分が大きくなる場合は、先に計画だけ作らせる
関連して、チームでの権限設計や変更範囲の制御を考える場合は、Claude Code権限設計チームガイド も参考になります。
原則4：検証方法を先に指定する
Claude Code公式ベストプラクティスでは、Claudeに自分の作業を検証する方法を与えることが強調されています。テスト、build、lint、typecheck、スクリーンショット比較など、Claude Codeが読める合否シグナルを渡すと、実装後に自分で反復できます。
逆に、検証条件がないと「見た目上はできた」「コード上はそれっぽい」で止まりやすくなります。プロンプトには必ず検証コマンドを含めましょう。
検証条件つきの修正プロンプト
ユーザー一覧の検索で、空白だけを入力したときに全件取得されるバグを修正してください。
まず現状を確認:
- 検索処理の実装箇所を特定する
- 既存テストで近いケースがないか確認する
修正方針:
- 空白だけの入力は空文字として扱う
- APIリクエストに不要な query パラメータを送らない
- 既存の検索仕様を変えない
テスト:
- 空白だけの入力
- 前後に空白を含む検索語
- 通常の検索語
- 空文字
検証:
- pnpm test users
- pnpm typecheck
完了時:
- 変更ファイルの一覧
- 追加したテストケース
- 実行したコマンドと結果
- 残ったリスク
を短く報告してください。このプロンプトは、Claude Codeに「作業」だけでなく「証拠の出し方」まで指定しています。実務では、この最後の報告形式がかなり効きます。レビュー担当者が差分を見る前に、Claude Codeが何を確認したのかを把握できるからです。
検証コマンドが不明なときのプロンプト
このリポジトリで、フロントエンド変更後に実行すべき検証コマンドを調べてください。
確認してほしいもの:
- package.json の scripts
- README / CONTRIBUTING / CLAUDE.md
- CI設定
- 既存のテストディレクトリ
出力:
- 変更種別ごとの推奨コマンド
- 速い検証コマンド
- PR前に実行すべき完全な検証コマンド
- 判断根拠として参照したファイル
この段階ではファイルを編集しないでください。最初に検証コマンドを調べるだけのセッションを作るのも有効です。特に新しいリポジトリでは、いきなり実装させるより、まず検証の地図を作らせた方が後が楽になります。
テスト生成まで含めた使い方は、Claude Codeテスト生成・TDDガイド で詳しく扱っています。
原則5：探索・計画・実装を分ける
小さな修正なら、1つのプロンプトで実装まで頼んでも構いません。しかし、複数ファイルにまたがる変更や、仕様が固まっていない機能では、探索・計画・実装を分けるべきです。
公式ベストプラクティスでも、複雑な変更では「Explore first, then plan, then code」という流れが紹介されています。Claude Codeには plan mode もあり、実装前に調査と計画を切り出せます。
探索プロンプト
請求書PDF出力機能を追加したいです。
まず実装せず、既存コードを調査してください。
調査対象:
- 請求書データのモデル
- 既存のPDF生成または帳票生成処理
- ファイル保存・ダウンロード処理
- テストの書き方
- 権限チェックの実装パターン
出力してほしいもの:
- 関連ファイル一覧
- 既存パターンの要約
- 実装で触るべきファイル候補
- 不明点
- 先に決めるべき仕様
この段階ではファイルを編集しないでください。計画プロンプト
先ほどの調査結果をもとに、請求書PDF出力機能の実装計画を作ってください。
計画に含めるもの:
- 変更ファイル
- 新規作成ファイル
- API設計
- エラーハンドリング
- テスト方針
- 検証コマンド
- リスクと代替案
制約:
- 既存の請求書作成フローは変更しない
- 新しい外部サービスは追加しない
- PDFライブラリを追加する必要がある場合は、理由と代替案を示してください
まだ実装はしないでください。実装プロンプト
承認した計画に沿って、請求書PDF出力機能を実装してください。
守ること:
- 計画外の大規模リファクタはしない
- 仕様上の不明点が出たら、仮定して進めず質問する
- 既存の命名規則とテスト構成に合わせる
検証:
- 関連する単体テストを追加する
- pnpm test invoices
- pnpm typecheck
- 必要なら最小限の手動確認手順を提示する
完了報告:
- 変更概要
- 実行した検証
- 残った未対応事項
- レビューで見てほしい箇所この3段階に分けるだけで、Claude Codeが「仕様を誤解したまま大量に実装する」リスクを下げられます。特にPMやテックリードがClaude Codeを使う場合は、最初の探索・計画だけでも価値があります。
計画モードの使いどころは、Claude Code Plan Mode実践ガイド も参照してください。
原則6：繰り返す指示を外部化する
毎回同じプロンプトを貼っているなら、それはプロンプト設計ではなく運用設計の問題です。Claude Codeには、繰り返し指示を外部化するための仕組みがあります。
公式ドキュメントでは、プロジェクトの永続的な指示には CLAUDE.md、繰り返し使うワークフローには skills、特定のタイミングで必ず実行したい処理には hooks が紹介されています。
CLAUDE.mdに入れるべき内容
CLAUDE.mdには、Claudeが毎回知っておくべき事実だけを書きます。長いチュートリアルや一時的な仕様は入れません。
# Project Instructions
## Build and test
- Use pnpm, not npm.
- After TypeScript changes, run: pnpm typecheck.
- For focused tests, prefer: pnpm test <area>.
## Code style
- Follow existing feature directory structure under src/features.
- Do not introduce new UI libraries without asking first.
- Keep API error responses consistent with src/api/errors.ts.
## Workflow
- For multi-file changes, investigate first and present a plan before editing.
- After edits, report changed files and verification results.
- If requirements are ambiguous, ask questions before implementing.公式ドキュメントでも、CLAUDE.mdは短く、人間が読みやすく、Claudeがコードから推測できない情報に絞ることが推奨されています。長くしすぎると、かえって重要な指示が埋もれます。
skillsに向いている内容
skillsは、毎回は不要だけれど、特定の作業では何度も使う手順に向いています。たとえば「APIエンドポイント追加手順」「リリース前チェック」「脆弱性レビュー」などです。
この作業は、プロジェクトの API endpoint skill に従って進めてください。
対象:
- 管理画面向けのユーザー検索API
追加要件:
- 既存のページネーション形式に合わせる
- 権限チェックを既存 middleware で行う
- OpenAPI仕様も更新する
完了条件:
- APIテスト追加
- OpenAPI差分確認
- pnpm test api
- pnpm typecheckcustom slash commands も同様に、定型作業を短い呼び出しにできます。詳しくは Claude Codeカスタムスラッシュコマンド実践ガイド で解説しています。
原則7：安全境界とコンテキストを管理する
Claude Codeのプロンプト設計で最後に重要なのが、安全境界とコンテキスト管理です。これは「うまい言い回し」ではなく、長時間セッションとチーム利用で事故を減らすための設計です。
機密ファイルを読ませない
公式 settings ドキュメントでは、機密情報を含むファイルをClaude Codeから除外する方法として permissions.deny が紹介されています。プロンプトで「.envは読まないで」と書くだけでは運用上弱いので、設定側で制御します。
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)"
]
}
}プロンプトでは、次のように安全境界を明示します。
この作業では機密ファイルを読まないでください。
禁止:
- .env / .env.*
- secrets/**
- credentials を含むファイル
- 本番データを含むログ
必要な設定値が不明な場合は、仮のキー名を使い、実値は要求しないでください。
所属組織のセキュリティ規程に従ってください。hooksで検証を強制する
hooksは、Claude Codeのライフサイクル上の特定タイミングで、コマンドやHTTPエンドポイントなどを実行する仕組みです。公式 hooks ドキュメントでは、PreToolUse、PostToolUse、Stop などのイベントが説明されています。
たとえば「編集後に必ずlintを走らせる」「マイグレーションファイルへの書き込み前に確認する」といった運用は、プロンプトでお願いするより hooks 側に寄せた方が確実です。hooksの実装例は、Claude Code hooks自動化ガイド にまとめています。
長い会話はリセットする
公式ベストプラクティスでは、関係ないタスクの間で /clear を使ってコンテキストをリセットすること、長い会話では /compact を使って要点を圧縮することが紹介されています。
実務では、Claude Codeに同じ点を何度も修正しているときは、粘るより新しいセッションに切り替えた方が早いことがあります。そのときは、学んだ条件を短くまとめて次のプロンプトに入れます。
前のセッションで分かった制約を反映して、改めて実装してください。
分かったこと:
- 既存APIは null ではなく undefined を未指定値として扱う
- テストでは fetch を直接 mock しない
- エラー表示は Toast ではなく FormError を使う
今回の目的:
- ユーザー検索フォームの空白入力バグを修正する
検証:
- pnpm test users
- pnpm typecheck実務手順：30分で作るClaude Code用プロンプト
ここまでの原則を、実務で使える手順に落とします。大きな機能ではなく、半日〜2日程度の変更をClaude Codeに任せる想定です。
Step 1：タスクを1文にする
まず、タスクを1文で書きます。ここで曖昧なら、Claude Codeに渡す前に仕様が曖昧です。
ユーザー一覧画面に、部署とステータスで絞り込めるフィルターを追加する。Step 2：既存パターンを探させる
次に、関連しそうな既存実装をClaude Codeに探させます。
このリポジトリで、一覧画面のフィルター実装パターンを調査してください。
探してほしいもの:
- 類似の一覧画面
- URLクエリとの同期方法
- フォーム状態管理
- API呼び出し
- テストパターン
出力:
- 参考にすべきファイル
- 再利用できる関数・コンポーネント
- 実装時の注意点
まだ編集はしないでください。Step 3：受け入れ条件を書く
探索結果をもとに、受け入れ条件を具体化します。
- 部署フィルターで
departmentIdを指定できる - ステータスフィルターで
active/inactiveを指定できる - フィルター状態はURLクエリに反映される
- ページ再読み込み後もフィルターが維持される
- 既存のページネーションと併用できる
- 不正なステータス値は無視するか、既存のエラーパターンに合わせる
Step 4：実装プロンプトを作る
ユーザー一覧画面に、部署とステータスのフィルターを追加してください。
参照:
- 先ほど調査した一覧画面フィルターの既存パターン
- src/features/users/UserListPage.tsx
- src/features/users/users.api.ts
- tests/users/**
受け入れ条件:
- departmentId で部署フィルターができる
- status=active / inactive でステータスフィルターができる
- フィルター状態はURLクエリに反映される
- ページ再読み込み後も状態が維持される
- 既存ページネーションと併用できる
- 不正な値の扱いは既存パターンに合わせる
制約:
- 新しい状態管理ライブラリは追加しない
- UIコンポーネントは既存のものを使う
- APIレスポンス形式は変更しない
- ついでのリファクタはしない
検証:
- 関連テストを追加または更新する
- pnpm test users
- pnpm typecheck
- pnpm lint
完了報告:
- 変更したファイル
- 実行した検証コマンドと結果
- 仕様上の仮定
- レビューで注意してほしい点Step 5：差分レビュー用プロンプトを使う
実装後は、同じClaude Codeセッションでそのままレビューを頼むより、必要に応じて /diff や /code-review を使い、差分を別視点で確認します。
現在の差分をレビューしてください。
観点:
- 受け入れ条件を満たしているか
- 既存パターンから外れていないか
- 不要なリファクタが混ざっていないか
- テストが仕様を十分にカバーしているか
- エッジケースが漏れていないか
出力:
- 重大度順の指摘
- ファイル名と該当箇所
- 修正案
- 問題なしの場合は、残るリスクだけを挙げるコードレビューの運用まで整えるなら、Claude Codeコードレビュー効率化ガイド も参考になります。
用途別プロンプト例
ここでは、実務でそのまま使いやすいプロンプトを用途別にまとめます。いずれも「目的、文脈、制約、検証、完了報告」を入れた形です。
新機能実装
通知設定機能を追加してください。
目的:
- ユーザーがメール通知とアプリ内通知のON/OFFを設定できるようにする
まず確認:
- 既存の設定画面
- ユーザー設定API
- フォーム部品
- テストパターン
受け入れ条件:
- 通知設定画面を開ける
- メール通知ON/OFFを保存できる
- アプリ内通知ON/OFFを保存できる
- 保存成功・失敗の表示は既存パターンに合わせる
制約:
- UIライブラリを追加しない
- 認証処理は変更しない
- DB変更が必要なら、実装前に理由を説明して確認する
検証:
- pnpm test settings
- pnpm typecheck
- pnpm lintバグ修正
注文詳細画面で、キャンセル済み注文の合計金額が0円表示になるバグを修正してください。
現象:
- キャンセル済み注文でも、過去の請求金額は表示されるべき
- 現在は0円として表示される
進め方:
- まず原因箇所を特定する
- 既存仕様とテストを確認する
- 再現テストを書いてから修正する
制約:
- 注文ステータスの定義は変更しない
- 請求計算ロジックを全面リファクタしない
- 表示層だけで不自然に補正しない
検証:
- pnpm test orders
- pnpm typecheck
完了時:
- 根本原因
- 修正方針
- 追加したテスト
- 実行結果
を報告してください。リファクタリング
src/features/reports の集計ロジックを読みやすくリファクタしてください。
目的:
- 振る舞いを変えずに、集計条件の追加がしやすい構造にする
制約:
- 公開APIの型は変更しない
- 既存テストの期待値は変えない
- パフォーマンス改善は今回の主目的ではない
- 大規模なファイル移動は事前に提案してから行う
進め方:
- まず現状構造と問題点を整理する
- 小さなリファクタ計画を出す
- 承認後に実装する
- 既存テストが通ることを確認する
検証:
- pnpm test reports
- pnpm typecheck
- 必要に応じて追加テストを提案するテスト追加
既存の在庫アラート機能に不足しているテストを追加してください。
対象:
- src/features/inventory/**
- tests/inventory/**
確認してほしい観点:
- 閾値ちょうど
- 閾値未満
- 在庫数がnullまたは未設定
- 通知済み商品の重複通知防止
- 権限がないユーザー
制約:
- 実装コードは、テスト追加に必要な最小限の修正だけにする
- テストヘルパーは既存パターンを使う
- flakyになりそうな時間依存テストは避ける
検証:
- pnpm test inventory
- pnpm typecheck技術調査
このリポジトリでCSVインポート機能を追加する場合の実装方針を調査してください。
まだ実装しないでください。
調査対象:
- 既存のファイルアップロード処理
- バリデーション処理
- 非同期ジョブ
- エラー表示
- テストパターン
出力:
- 推奨アーキテクチャ
- 変更ファイル候補
- 先に決めるべき仕様
- リスク
- 最小実装のスコープ
- 検証コマンド候補よくある失敗パターンと回避策
Claude Codeの失敗は、プロンプトの曖昧さだけでなく、運用設計の甘さからも起きます。ここでは、特に多い失敗パターンを整理します。
失敗1：曖昧すぎる指示
❌ 悪い例：
この画面をいい感じに直して。⭕ 良い例：
ユーザー一覧画面のフィルターUIを、既存の注文一覧画面と同じレイアウトに合わせて修正してください。
参照:
- src/features/orders/OrderListFilters.tsx
- src/features/users/UserListPage.tsx
変更範囲:
- users配下のフィルターUI
検証:
- pnpm test users
- pnpm typecheck「いい感じ」は人間同士でもズレます。Claude Codeには、参照パターンと完成条件を渡しましょう。
失敗2：一度に多くを求めすぎる
❌ 悪い例：
管理画面を全部作り直して、テストも追加して、デザインも改善して。⭕ 良い例：
まず管理画面の現在の構成を調査し、改善計画だけを出してください。
実装はまだしないでください。
出力:
- 主要画面の構成
- 重複しているUIパターン
- 先に直すべき箇所
- 3段階の改善計画
- 各段階の検証方法大きい依頼は、探索、計画、実装、レビューに分けた方が安定します。
失敗3：検証条件を書かない
❌ 悪い例：
バグを直して。⭕ 良い例：
バグを修正し、再現テストを追加してください。
完了条件:
- 修正前に失敗するテストがある
- 修正後にそのテストが通る
- 既存の関連テストも通る
検証:
- pnpm test billing
- pnpm typecheckClaude Codeは検証コマンドがあると、自分で実行し、失敗を読んで修正できます。検証条件なしでは、そのループが閉じません。
失敗4：プロンプトに機密情報を貼る
❌ 悪い例：
この本番APIキーを使って動作確認して。⭕ 良い例：
APIキーの実値は使わず、環境変数名だけを前提に実装してください。
条件:
- 実値は要求しない
- .env は読まない
- 設定例はダミー値で書く
- 本番環境への接続はしない
必要な環境変数名が不明な場合は質問してください。機密情報や本番データは、プロンプトにもファイルにも安易に渡さないでください。組織利用では、settingsの permissions.deny や管理ポリシーと組み合わせるのが前提です。
チームで使うときのプロンプトレビュー基準
Claude Codeを個人で使うだけなら、多少雑なプロンプトでもリカバリできます。しかしチーム展開では、プロンプトそのものをレビュー対象にした方がよいです。
以下のチェックリストを、PRテンプレートや CLAUDE.md に入れておくと、プロンプト品質が揃います。
- 目的は1文で明確か
- 参照すべき既存実装が指定されているか
- 変更してよい範囲が明確か
- 変更しない範囲が明確か
- 検証コマンドがあるか
- 完了報告の形式があるか
- 不明点を質問する条件があるか
- 機密情報や本番データを扱わない設計になっているか
- 同じ指示を毎回貼っていないか
- 長時間タスクの場合、探索・計画・実装が分かれているか
チーム導入全体の進め方は、Claude Codeチーム展開ガイド が近いテーマです。プロンプトの書き方だけでなく、権限、レビュー、教育、運用ルールまで合わせて考える必要があります。
プロンプト設計を改善するための運用ループ
プロンプトは一度書いて終わりではありません。コードと同じように、失敗から改善していくものです。
1. 失敗したプロンプトを保存する
Claude Codeが想定外の動きをしたら、失敗したプロンプトを消さずに残します。何が曖昧だったのかを見返せるからです。
2. 修正指示を短く抽出する
たとえば「新しいUIライブラリを追加しない」「DBマイグレーションは事前確認する」「テストではfetchを直接mockしない」など、再発しそうな条件を抽出します。
3. CLAUDE.mdまたはskillに移す
毎回必要な指示なら CLAUDE.md、特定作業だけで必要な手順ならskillに移します。公式memoryドキュメントでも、CLAUDE.mdは毎セッション必要な事実に絞ることが推奨されています。
4. hooksやsettingsで強制すべきものを分ける
「できれば守ってほしい」指示は CLAUDE.md でよいですが、「絶対に読ませない」「必ず検証する」ものは settings や hooks 側に分けます。プロンプトは万能ではありません。
5. 新しいセッションで再テストする
長い会話の途中で改善したプロンプトを試すと、前の文脈に引っ張られることがあります。公式ベストプラクティスにもある通り、関係ないタスクの間では /clear を使い、きれいな文脈で試すのが安全です。
FAQ
Q1. Claude Codeのプロンプトは長い方がよいですか？
長ければよいわけではありません。目的、文脈、制約、検証、完了条件が入っていれば十分です。毎回必要な共通指示は CLAUDE.md やskillに移し、プロンプト本体はタスク固有の情報に絞る方が扱いやすいです。
Q2. まずClaude Codeに調査だけ頼むべきですか？
小さな修正なら直接実装で構いません。複数ファイルにまたがる変更、仕様が曖昧な機能、既存設計を理解する必要がある作業では、調査だけのプロンプトから始める方が安全です。
Q3. CLAUDE.mdには何を書くべきですか？
ビルド・テストコマンド、プロジェクト固有の設計ルール、命名規則、よくある落とし穴、レビュー前に実行する検証などです。コードを読めば分かる説明や、一時的な仕様、長いチュートリアルは避けます。
Q4. Claude Codeが勝手に余計な変更をした場合はどうしますか？
まず変更範囲と非目標をプロンプトに明記します。セッションが長くなっている場合は /clear で新しい文脈に切り替え、学んだ制約を短く入れ直します。差分確認には /diff やレビュー用プロンプトを使います。
Q5. 検証コマンドが分からないリポジトリではどうすればよいですか？
最初にClaude Codeへ「編集せずに検証コマンドを調査して」と頼みます。package.json、README、CI設定、既存テストを確認させ、変更種別ごとの推奨コマンドを出してもらうと、その後の実装プロンプトが安定します。
Q6. セキュリティ上、プロンプトで気をつけることはありますか？
APIキー、個人情報、本番データ、認証情報はプロンプトに貼らないでください。必要な場合も実値ではなく環境変数名やダミー値で扱います。機密ファイルは permissions.deny などの設定で読めないようにし、所属組織のセキュリティ規程に従ってください。
参考・出典
- How Claude Code works — Claude Code Docs（参照日: 2026-07-07）
- Prompt library — Claude Code Docs（参照日: 2026-07-07）
- Best practices for Claude Code — Claude Code Docs（参照日: 2026-07-07）
- How Claude remembers your project — Claude Code Docs（参照日: 2026-07-07）
- Claude Code settings — Claude Code Docs（参照日: 2026-07-07）
- Commands — Claude Code Docs（参照日: 2026-07-07）
- Create custom subagents — Claude Code Docs（参照日: 2026-07-07）
- Hooks reference — Claude Code Docs（参照日: 2026-07-07）
まとめ：今日から始める3つのアクション
- 今日やること：次にClaude Codeへ頼む作業で、「目的」「参照ファイル」「変更範囲」「検証コマンド」「完了報告」を入れたプロンプトに書き換える。
- 今週中にやること：よく使う検証コマンドとプロジェクト固有ルールを
CLAUDE.mdに整理し、チームでレビューする。 - 今月中にやること：繰り返し作業をskillsやcustom commandに分け、強制したい安全制御はsettingsやhooksに移す。
Claude Codeのプロンプト設計は、魔法の言葉を探す作業ではありません。エージェントに渡す作業仕様を、どれだけ検証可能に書けるかです。まずは小さなタスクで、この記事のテンプレートをそのまま使ってみてください。
あわせて読みたい：実装パターンを広く見たい場合は Claude CodeフロントエンドReact開発ガイド、バックエンド側のコード生成に寄せたい場合は Claude CodeバックエンドAPI開発ガイド も参考になります。
著者：佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）で生成AI活用法を発信。企業向けAI研修・導入支援、Claude Codeを含むAIエージェント活用支援を行う。著書『AIエージェント仕事術』（SBクリエイティブ）。
