Claude Codeプロンプトの書き方｜精度を高める5要素と実務テンプレート8選

Claude Codeへ「バグを直して」「コードを整理して」と依頼しても、変更範囲や成果が毎回変わることがあります。原因は、プロンプトが短いことではなく、達成したい結果、作業対象、制約、検証方法、報告内容が曖昧なことにあります。

Claude Codeは回答文を返すだけのAIチャットではありません。コードベースを読み取り、ファイルを編集し、許可されたコマンドを実行できるため、通常のAIチャット以上に「どこまで変更してよいか」と「何をもって完了とするか」の指定が重要です。

一方で、開発ルールを毎回のプロンプトへすべて書く必要はありません。今回だけの依頼は通常のプロンプト、プロジェクト共通の規約はCLAUDE.md、繰り返す作業手順はSkillsへ分けることで、指示を短く保ちながら再現性を高められます。

本記事では、Claude Codeプロンプトの基本構造となる5要素、実務で使えるテンプレート8選、失敗要因と対策、Cursor・GitHub Copilot・Codexとの違い、チーム標準化の進め方を解説します。なお、プロンプトはアクセス制御の代替にはなりません。企業利用では、パーミッション、サンドボックス、レビュー工程を組み合わせる必要があります。

Claude Codeプロンプトの基本と通常のAIチャットとの違い

Claude Codeのプロンプトは、質問文というよりも、エージェントへ渡す作業仕様書です。細かな操作を一つずつ命令するのではなく、達成したい状態と作業の境界、合格条件を伝える必要があります。

作業の目標と境界を伝えるClaude Codeプロンプト

Claude Codeは、依頼内容に応じてコードベースを探索し、関連ファイルを読み、変更を加え、テストやビルドなどを実行します。そのため、プロンプトの役割は「42行目にnullチェックを追加する」と実装手段を固定することではありません。

たとえば、次の2つの指示を比較します。

悪い例：
「src/auth/login.tsの42行目にnullチェックを追加してください」

改善例：
「メールアドレス未登録のユーザーがログインすると処理が停止する問題を修正してください。問題を再現するテストを追加し、既存APIの返却形式は変更しないでください」

前者は、原因が42行目にあるという利用者側の推測をClaude Codeへ押し付けています。後者は、利用者から見た問題、再発防止、変更してはいけない条件を示しているため、コードベースを調査したうえで適切な修正方法を選べます。

対象箇所が明確な小規模修正では、ファイルや関数を指定した方が探索量を抑えられます。一方、原因箇所が不明な障害では、最初から変更を求めず、「関連箇所を調査し、原因候補と変更計画を報告する」と依頼する方が安全です。

Claude Codeのプロンプトは、委任する仕事の受け入れ条件をまとめた短い仕様書と捉えると、必要な情報を整理しやすくなります。

通常のAIチャットと異なるプロンプト設計

通常のAIチャットは、主に文章やコード例を回答として返します。誤った回答が含まれていても、利用者が採用しなければリポジトリへ直接的な変更は発生しません。

Claude Codeは、許可された範囲でファイル編集、シェルコマンドの実行、Git操作などを行えます。曖昧な指示は、不要なファイル変更、想定外の依存関係追加、レビュー範囲の拡大につながる可能性があります。

通常のAIチャットでは「背景・質問・出力形式」が中心です。Claude Codeでは、これに加えて「目標・対象範囲・制約・検証・報告」を明確にします。ファイルパス、再現手順、完全なエラーログ、既存実装の参照先など、コードベースに結び付く情報も重要です。

【表①：通常のAIチャットとClaude Codeのプロンプト設計比較】

比較項目	通常のAIチャット	Claude Code
指示の目的	回答、説明、文章、コード例を得る	コードベース上の作業を委任する
主なコンテキスト	背景、質問、参考情報	ファイル、関数、ログ、再現手順、既存実装
変更範囲	原則として回答内	許可されたファイルや環境へ影響する
検証	利用者が回答を読む	テスト、ビルド、型チェックなどを実行可能
主なリスク	誤回答の採用	意図しない編集、コマンド実行、レビュー範囲拡大
必要な要素	背景、質問、出力形式	目標、対象、制約、検証、報告

回答を読むためのプロンプトと、作業を任せるプロンプトではリスクが異なります。ChatGPTやClaudeの一般的な質問テンプレートを、そのままClaude Codeへ機械的に流用しないことが重要です。

Claude Codeプロンプトを安定させる5つの構成要素

Claude Codeへの依頼は、目標、対象・文脈、制約、検証・完了条件、報告形式の5要素に分けると整理しやすくなります。すべてを長文で書く必要はありません。タスクの失敗につながる情報を優先し、短くても合否を判断できる形にします。

要素1｜達成したい結果を示す目標

目標には、操作内容ではなく、利用者やシステムが最終的にどうなるべきかを記載します。

「ログイン機能を直す」「コードを改善」「処理を最適化する」といった表現では、完了状態を判断できません。次のように、観測可能な結果へ置き換えます。

• ログイン機能を直す → セッション切れ後に再ログインすると元の画面へ戻れない問題を解消する
• 処理を高速化する → 1万件のCSVを読み込む処理について、同一の検証環境で実行時間を計測し、ボトルネックを特定する
• テストを増やす → calculateFee関数に対し、正常系、境界値、負数入力のテストを追加する
• READMEを更新する → 新しい環境変数の設定手順を、初めて環境構築する開発者向けに追記する

実装方法を固定しすぎると、Claude Codeが既存コードを探索し、より適切な方法を選ぶ余地を失うことがあります。目標欄は原則1～2文に収め、独立した目的が複数ある場合はタスクを分けます。

目標は「何を変更するか」ではなく、「何が解決されたら完了か」で記載することが基本です。

要素2｜対象範囲と判断材料を示すコンテキスト

コンテキストは、Claude Codeが必要な情報へ早く到達するための判断材料です。大量の情報を渡すことではなく、編集対象、参照対象、再現情報、既存パターンを区別して伝えることが重要です。

対象が分かっている場合は、次のように直接参照します。

• 編集対象：`src/auth/session.ts`
• 参照対象：`src/auth/login.ts`のエラー処理
• 既存テスト：`tests/auth/session.test.ts`
• 仕様：`docs/authentication.md`
• 発生環境：Node.js 22、Chrome最新版
• 再現手順：ログイン後30分放置し、保存ボタンを押す
• 実際の結果：401エラー後も画面が更新されない
• 期待結果：再ログイン画面へ遷移し、認証後に編集画面へ戻る

バグ修正では、エラーメッセージを短く要約せず、可能な範囲で完全なスタックトレースを渡します。新規実装では、類似機能や従うべき設計パターンを参照先として示します。

一方、リポジトリ全体の説明や大量のコード全文を貼り付けると、重要な指示が埋もれます。対象箇所が分からない場合は、「まず調査だけを行い、変更候補と根拠を報告する」と依頼し、探索と実装を分けます。

要素3｜変更範囲と禁止事項を示す制約

制約は、Claude Codeが善意で行う過剰な対応を防ぐために記載します。依頼していないリファクタリング、依存関係の追加、公開APIの変更などは、成果物が動作していてもレビュー負荷や障害リスクを高めます。

代表的な制約は次のとおりです。

• 公開APIのインターフェースは変更しない
• 新しい依存ライブラリは追加しない
• `legacy/`配下は編集しない
• 既存の例外型と戻り値を維持する
• テストを削除、スキップ、弱体化しない
• 認証情報や本番データへアクセスしない
• Git commit、push、mergeは実行しない
• 外部ネットワークへ接続しない
• 作業範囲を広げる必要が生じた場合は停止して報告する

「既存コードに合わせる」だけでは、参照先が曖昧です。命名規則や実装パターンを示すファイルがある場合は、具体的に指定します。

ただし、制約を増やしすぎると相互矛盾が生じます。プロジェクト全体へ常時適用するコーディング規約や禁止事項はCLAUDE.mdへ移し、通常のプロンプトには今回の作業に固有の制約だけを残します。

なお、「機密ファイルを読まない」と書くことは、技術的なアクセス制御ではありません。重要な禁止事項は、Claude Codeのパーミッション設定やサンドボックスでも強制します。

要素4｜合否を判定する検証方法と完了条件

検証方法と完了条件は、Claude Codeが「コードを書いた段階」で停止せず、成果を確認するために必要です。「正常に動くこと」ではなく、機械的に合否を判断できる形へ変換します。

例：

• `npm test`が全件成功する
• `pnpm tsc –noEmit`のエラーが0件になる
• `npm run lint`で新規エラーが発生しない
• 再現テストが修正前に失敗し、修正後に成功する
• 指定された入力データ100件の処理結果が期待値と一致する
• ビルドが終了コード0で完了する
• 計画外のファイル変更がない
• 新しい依存関係が追加されていない

バグ修正では、先に問題を再現する失敗テストを作り、修正後に成功することを完了条件とします。UI変更では、指定デザインやスクリーンショットとの差分を確認する方法を与えます。

テストを通すために例外を握りつぶす、テストを削除する、型チェック対象から除外するといった回避策も禁止事項へ加えます。完了報告では、実行コマンド、終了コード、成功件数、失敗件数、未実施項目を示させます。

作業内容と検証方法をセットにすると、Claude Codeが実装と確認を繰り返すループを作りやすくなります。

要素5｜レビューに必要な報告形式

報告形式を指定すると、レビュー担当者が毎回同じ観点で差分を確認できます。最低限、次の項目を求めます。

• 変更したファイル
• ファイルごとの変更理由
• 実行したテスト、ビルド、型チェック
• 各コマンドの結果
• 追加した依存関係や設定変更の有無
• 計画から変更した点
• 未解決事項と残るリスク
• 人間が確認すべき箇所

長い説明が不要な場合は、「結論、変更箇所、検証結果、残課題の順に簡潔に報告」と指定します。セキュリティレビューでは、重要度、該当ファイル・行、発生条件、影響、修正案を固定形式で出力させると比較しやすくなります。

以下が、5要素を含む基本テンプレートです。

# 目標
[利用者またはシステムが、最終的にどうなるべきか]

# 対象・コンテキスト
- 編集対象：
- 参照対象：
- 再現手順：
- 実際の結果：
- 期待する結果：

# 制約
- 変更してよい範囲：
- 変更してはいけない範囲：
- 追加してはいけない依存関係：
- 範囲拡大が必要な場合は、作業を停止して報告する

# 検証・完了条件
- 実行するコマンド：
- 合格条件：
- 確認する差分：

# 報告形式
1. 原因または実装方針
2. 変更ファイルと変更理由
3. 実行した検証と結果
4. 未解決事項・残るリスク

Claude CodeプロンプトとCLAUDE.md・Skillsの使い分け

指示を毎回のプロンプトへ詰め込むと、入力の手間とコンテキスト消費が増えます。今回だけ変わる情報は通常のプロンプト、全セッションへ適用する規約はCLAUDE.md、繰り返す作業手順はSkills、独立性の高い調査や検証はsubagentへ分けます。

今回のタスクだけに適用する通常のプロンプト

通常のプロンプトには、今回達成する目標、変更対象、固有の制約、完了条件、報告形式を書きます。チケット番号、今回だけ発生している不具合、対象ブランチ、期限付き仕様なども通常のプロンプト側です。

無関係なタスクへ切り替える場合は、新しいセッションを開始するか、必要に応じて`/clear`を利用します。1つのセッションへ別件を追加し続けると、古い会話やコマンド出力が新しい判断へ影響しやすくなります。

毎回変わる情報の例：

• 今回の目的
• 対象チケット
• 編集対象ファイル
• 再現手順
• 今回だけの禁止事項
• 完了期限
• 今回実行する検証
• 報告先が求める形式

全セッションで共有するCLAUDE.md

CLAUDE.mdは、Claude Codeへプロジェクト固有の継続的な情報を伝えるMarkdownファイルです。配置場所やディレクトリのスコープに応じて、適用範囲を分けられます。

記載に向く内容は次のとおりです。

• ビルド、テスト、型チェック、リンターのコマンド
• 主要ディレクトリとアーキテクチャ
• 命名規則やコーディング規約
• 参照すべき既存パターン
• 禁止している操作
• 既知の落とし穴
• 変更後に必ず確認する項目

一方、ファイルツリーを見れば分かる説明、長いAPI仕様、過去の変更履歴、一般的なプログラミング原則は入れすぎないようにします。`/init`で生成した内容も、そのまま採用せず、誤りや冗長な説明を削除してから共有します。

CLAUDE.mdの内容が古くなると、正しいプロンプトを書いても誤ったルールが優先される可能性があります。規約変更時と定期レビュー時に更新します。

【表②：通常のプロンプト・CLAUDE.md・Skills・subagentの使い分け】

保存・実行先	向いている内容	具体例	更新のタイミング
通常のプロンプト	今回だけ変わる依頼	チケット、対象ファイル、今回の完了条件	タスクごと
CLAUDE.md	全体または特定ディレクトリの恒常ルール	テストコマンド、命名規則、禁止事項	規約変更・定期レビュー
Skills	繰り返す作業手順	コードレビュー、リリース確認、文書更新	手順変更時
subagent	独立性の高い調査・検証	全体調査、セキュリティ確認、再検証	タスクごと

繰り返し使う作業手順を保存するSkills

Skillsは、特定の作業で必要になる手順、知識、出力形式を再利用するために使います。コードレビュー、リリース前チェック、テスト生成、ドキュメント更新など、開始条件と終了条件が明確な作業に向いています。

常時読み込む必要がない長い手順をCLAUDE.mdへ入れると、すべてのタスクでコンテキストを消費します。必要なときだけ呼び出すSkillsへ分離することで、プロジェクトメモリを簡潔に保てます。

Skill内にも、対象範囲、禁止事項、検証方法、報告形式を含めます。単なる短縮コマンドではなく、作業品質を再現するための標準手順として設計します。チームで利用する場合はGitで管理し、変更時にレビューを行います。

独立した調査や検証を委譲するsubagent

subagentは、コードベース全体の調査、セキュリティレビュー、テスト結果の再検証など、独立性の高い作業を切り出す場合に有効です。メインセッションへ大量の調査結果を抱え込まず、担当範囲を限定できます。

subagentへは、担当範囲、利用できる情報、最終成果物、停止条件を明示します。実装担当と検証担当を分けると、同じ判断を自己採点する状態を避けやすくなります。

ただし、小規模な修正へsubagentを多用すると、コンテキストと実行コストが増えます。作業の独立性、規模、必要な専門性を基準に判断します。

Claude Code・Cursor・GitHub Copilot・Codexのプロンプト設計比較

4つのツールには、今回の依頼を入力するプロンプトと、プロジェクト共通の指示を保存する仕組みがあります。ただし、ファイル名、適用範囲、優先順位、反復作業の仕組みは異なるため、指示ファイルの名前だけを変えて移行する方法は避けます。

4ツールにおける通常プロンプトと恒常ルールの違い

Claude CodeではCLAUDE.md、Cursorでは`.cursor/rules`、GitHub Copilotでは`.github/copilot-instructions.md`やパス別のinstructions、CodexではAGENTS.mdが、主な恒常指示の保存先です。

共通する考え方は、通常のプロンプトへ今回の目標や完了条件を書き、恒常指示へプロジェクトの規約、テスト方法、アーキテクチャを記載することです。

一方、Cursorにはルールの適用方法があり、GitHub Copilotは利用するIDE、GitHub上のエージェント、コードレビューなどによって対応する指示方式が異なります。CodexのAGENTS.mdも、配置したディレクトリのスコープや製品の実行環境を確認する必要があります。

【表③：Claude Code・Cursor・GitHub Copilot・Codexの指示設計比較】

比較項目	Claude Code	Cursor	GitHub Copilot	Codex
通常依頼	セッション内のプロンプト	Chat・Agentへのプロンプト	Chat・Agent・レビューへの依頼	Codexへのタスク
主な恒常指示	CLAUDE.md	`.cursor/rules`	`.github/copilot-instructions.md`	AGENTS.md
パス別指示	ディレクトリ階層のCLAUDE.md等	Project Rulesの適用設定	`.github/instructions/*.instructions.md`等	ディレクトリ階層のAGENTS.md
反復作業	Skills	Rules・Commands等	Prompt files・custom agents等、利用環境による	Skillsや環境側の設定、対応機能を確認
検証	ローカルコマンド、テスト、ビルド	Agentが利用できるツール	IDE・GitHub上の実行環境による	実行環境でテスト・コマンド
チーム共有	リポジトリで管理	`.cursor/rules`を管理	`.github`配下などを管理	AGENTS.mdを管理
主な注意点	権限・コンテキスト・CLAUDE.mdの鮮度	ルールの適用方式	製品・IDEごとに対応方式が異なる	実行環境・権限・AGENTS.mdのスコープ

他ツールへ流用できる指示と製品固有の指示

複数のコーディングエージェントで再利用しやすいのは、次の5要素です。

• 達成したい目標
• 編集対象と参照対象
• 変更してはいけない範囲
• 検証コマンドと合格条件
• レビュー用の報告形式

一方、次の情報は製品固有です。

• ファイル参照の記法
• Plan Modeなどの操作モード
• 権限モードや承認方法
• Skillsやルールファイルの配置
• 利用できるツール、コマンド、MCP
• クラウド実行環境やネットワーク条件

複数ツールを併用する企業では、共通の開発原則を中立的な文書へまとめ、製品固有の設定だけをCLAUDE.md、`.cursor/rules`、Copilot instructions、AGENTS.mdへ分ける方法があります。同じ文章を複数ファイルへコピーする場合は、参照元と更新責任者を決めないと内容が分岐します。

比較時は、モデル性能だけでなく、指示の適用範囲、権限管理、監査性、既存IDEやGitHub運用との整合性を確認します。

Claude Codeプロンプトの実務テンプレート8選

ここでは、コード理解、機能実装、バグ修正、リファクタリング、テスト作成、コードレビュー、ドキュメント更新、定型ファイル処理に使えるテンプレートを紹介します。角括弧内を自社の情報へ置き換えて使用してください。

テンプレート1｜既存コードの構造把握

新規参加者や他部門の担当者がコードベースを理解する場合は、最初に編集を禁止し、調査結果だけを求めます。

# 目標
[対象機能]の責務、主要ファイル、データフロー、外部依存関係を整理してください。

# 対象・コンテキスト
- 対象ディレクトリ：[パス]
- エントリーポイント：[パス]
- 関連ドキュメント：[パス]

# 制約
- ファイルを編集しないでください
- コマンドは読み取り専用に限定してください
- 推測と確認済みの事実を分けてください

# 完了条件
次をMarkdownで出力してください。
1. 主要コンポーネント一覧
2. 呼び出し関係
3. データの流れ
4. 外部依存関係
5. 未確認事項

処理フローはMermaidでも示してください。

大規模なリポジトリでは、最初に全体像を確認し、その後に対象モジュールを絞ります。

テンプレート2｜新機能の実装

新機能では、利用者の操作と期待結果、既存設計との整合性、検証方法を指定します。

小規模機能向け：

# 目標
[利用者の操作]を行うと、[期待する結果]になる機能を実装してください。

# 対象・コンテキスト
- 編集候補：[パス]
- 類似機能：[パス]
- 利用中のフレームワーク：[名称・バージョン]

# 制約
- 公開APIは変更しない
- 新しい依存関係は追加しない
- [既存UIまたは実装パターン]へ合わせる

# 検証
- [単体テストコマンド]
- [型チェックコマンド]
- [ビルドコマンド]

# 報告
変更ファイル、実装方針、検証結果、残課題を報告してください。

複数ファイル向け：

まずPlan Modeで調査し、次を含む変更計画だけを提示してください。まだ編集しないでください。
- 変更が必要なファイル
- ファイルごとの変更内容と理由
- 既存機能への影響
- 互換性上のリスク
- 実装後の検証方法
私が計画を承認した後、承認範囲だけを実装してください。

テンプレート3｜バグの原因調査と修正

バグ修正は、症状だけでなく、発生条件、完全なエラー、再現手順、期待動作を与えます。

# 目標
[症状]の根本原因を特定し、再発防止テストを含めて修正してください。

# 発生情報
- 発生環境：
- 発生条件：
- 再現手順：
- 実際の結果：
- 期待する結果：
- 関連ファイル：
- 完全なエラーログ：
[ここへ貼り付け]

# 制約
- 原因を隠す例外処理を追加しない
- テストを削除、スキップ、弱体化しない
- 対象外のリファクタリングを行わない
- 原因箇所が不明な場合は、調査結果を報告してから実装する

# 完了条件
1. 修正前に問題を再現するテストを追加
2. 修正後に再現テストが成功
3. 関連テストがすべて成功
4. 根本原因、変更箇所、残るリスクを報告

テンプレート4｜動作を変えないリファクタリング

「きれいにする」ではなく、重複削減、責務分離、可読性、性能など、目的を一つに絞ります。

# 目標
[対象ファイル・関数]について、[重複削減／責務分離／可読性改善]を行ってください。

# 変更してよいもの
- 内部関数の分割
- 変数名
- 重複処理の共通化
- [その他]

# 変えてはいけないもの
- 公開インターフェース
- 戻り値と例外
- 外部から観測できる動作
- 既存テストの期待値
- 依存ライブラリ

# 進め方
1. 影響範囲と計画を提示
2. 承認後に実装
3. 既存テスト、型チェック、静的解析を実行
4. 動作差分がない根拠を報告

テンプレート5｜不足テストの追加

テスト件数を増やすのではなく、対象リスクと期待値を明確にします。

# 目標
[対象関数・機能]について、未カバーのリスクに対応するテストを追加してください。

# 対象
- 実装：[パス]
- 既存テスト：[パス]
- テストフレームワーク：[名称]

# 追加する観点
- 正常系：
- 異常系：
- 境界値：
- 権限：
- 外部依存失敗：
- 回帰リスク：

# 制約
- 実装コードをテストへ合わせて変更しない
- 意味のないモックを増やさない
- 既存のテストスタイルと命名規則へ合わせる

# 完了条件
新規テストと関連テスト全体を実行し、ケースごとの入力、期待値、失敗時に示す問題を報告してください。

テスト観点は、「入力」「期待値」「失敗時に意味すること」をセットで整理すると、件数だけを増やす状態を防げます。

テンプレート6｜コードレビューとセキュリティ確認

コードレビューでは、一般的な感想ではなく、該当箇所、影響、重要度、修正案を求めます。

# 目標
[コミット／Pull Request／対象ファイル]をレビューしてください。

# レビュー観点
- セキュリティ
- 性能
- エラーハンドリング
- 可読性
- テスト不足
- 後方互換性

# 制約
- この段階ではファイルを変更しない
- 根拠が弱い指摘は「要確認」とする
- スタイル上の好みと、障害・脆弱性リスクを分ける

# 出力形式
問題ごとに次を記載してください。
- 重要度：Critical／High／Medium／Low
- ファイル・行
- 発生条件
- 影響
- 根拠
- 推奨修正
- 追加すべきテスト

最後に、マージ可否と確認が必要な項目をまとめてください。

テンプレート7｜README・仕様書の更新

ドキュメント更新では、推測による未実装機能の記載を防ぎます。

# 目標
[対象機能]の変更を、[想定読者]向けに[README／API仕様／運用手順書]へ反映してください。

# 確認対象
- 実装コード：
- 設定ファイル：
- テスト：
- 既存文書：

# 制約
- 実装とテストで確認できた事実だけを書く
- 未実装機能や将来予定を推測で追加しない
- 既存の見出し構造、文体、用語へ合わせる
- サンプルコードやコマンド形式を統一する

# 完了条件
- 文書内のコマンドや手順を実行可能な範囲で検証
- 変更箇所と根拠を報告
- 確認できない内容を未確認事項として分離

テンプレート8｜CSV・Excel・定型ファイル処理の自動化

業務ファイルを扱う場合は、元データ保護と処理前後の検算を含めます。

# 目標
[入力ファイル]を[変換目的]に沿って処理し、[出力形式]で保存してください。

# 入力
- ファイル：
- シートまたは列定義：
- 文字コード：
- 日付形式：
- 件数：

# 変換条件
- 欠損値：
- 先頭ゼロ：
- 重複行：
- エラー行：
- 集計単位：

# 出力
- 保存先：
- ファイル名：
- 形式：

# 制約
- 元ファイルは変更しない
- 別フォルダへ成果物を保存する
- 顧客情報を外部へ送信しない
- 不明な値を推測で補完しない

# 検算
- 処理前後の件数
- 合計値
- サンプル行
- エラー行数
- 重複件数

# 報告
使用したスクリプト、ライブラリ、再実行手順、検算結果を残してください。

顧客情報や機密データを扱う場合は、プロンプトを書く前に、検証環境、権限、ログ、保存先を確認します。処理の正確性だけでなく、データがどこへ保存され、誰が閲覧できるかまで設計が必要です。

Claude Codeプロンプトを使った4段階の実行手順

複数ファイルへ影響する作業は、探索、計画、実装、検証へ分けます。一度の長いプロンプトですべてを完了させるより、人間が途中で前提と変更範囲を確認できるため、手戻りを抑えやすくなります。

ステップ1｜変更前の現状探索

最初はPlan Modeまたは読み取り専用の指示で、対象機能、関連ファイル、データフロー、既存テストを調査させます。

対象機能の実装箇所、主要な呼び出し関係、既存テスト、変更時のリスクを調査してください。
まだファイルを編集しないでください。
確認済みの事実、推測、不明点を分けて報告してください。

利用者は、Claude Codeが正しい機能と依存関係を把握しているか確認します。前提が誤っている場合は、この段階で仕様書や参照先を追加します。

ステップ2｜変更計画と影響範囲の確認

次に、変更が必要なファイル、変更理由、検証方法を計画として出力させます。複数案がある場合は、互換性、保守負荷、メリット、デメリットを比較させます。

変更計画には、次の項目を含めます。

• 対象ファイル
• 変更内容
• 変更理由
• 既存機能への影響
• 主なリスク
• 検証方法
• 承認者

変更ファイル数が想定より多い場合は、タスクの分割や段階導入を検討します。利用者が採用案と修正点を明示するまでは、実装させません。

ステップ3｜承認範囲に限定した実装

実装開始時には、承認した計画、対象ファイル、禁止範囲を再確認します。途中で新しい問題が判明した場合は、無断で作業範囲を広げず、停止して報告させます。

承認した変更計画に沿って実装してください。
対象は[ファイル一覧]です。
計画外のファイル変更、新規依存関係、設定変更が必要になった場合は、実行せず理由を報告してください。
一定単位の変更ごとに[テスト／型チェック]を実行してください。

変更途中にも検証を入れることで、最後に多数のエラーが発覚する状態を避けやすくなります。

ステップ4｜検証結果と証拠の記録

完了時は、テスト、ビルド、型チェック、リンター、画面確認など、事前に定めた完了条件を実行させます。

報告では、実行したコマンド、成功・失敗、終了コード、未実施項目、計画外の変更の有無を確認します。`git diff`や変更ファイル一覧も確認し、承認していないファイルが変更されていないかを見ます。

本番反映前には、人間によるコードレビューと必要な承認を残します。検証が失敗した場合は、無限に修正を続けさせず、「同じ原因で2回失敗したら停止して再計画を提示する」などの停止条件を設定します。

Claude Codeの自己申告ではなく、コマンド結果と差分を完了の証拠として残すことが重要です。

Claude Codeプロンプトを設計するメリットと限界

構造化したプロンプトは、作業品質やレビュー効率を改善する手段です。ただし、アクセス制御、品質保証、最終責任を代替するものではありません。

プロンプト構造化による業務上のメリット

目標と対象範囲が明確になると、不要な探索や過剰な変更を減らしやすくなります。完了条件を与えることで、テストやビルドを含む自己検証のループも作れます。

報告形式を固定すれば、レビュー担当者は毎回同じ観点で差分、検証結果、残課題を確認できます。テンプレート化により、担当者ごとの文章力や経験に左右されにくくなります。

CLAUDE.mdやSkillsと組み合わせると、同じ規約や手順を毎回入力する必要がありません。PoCでは、共通テンプレートと評価指標を使うことで、品質、工数、レビュー負荷の変化を比較しやすくなります。

主な効果は次の5点です。

• 品質：期待する結果と検証条件の明確化
• 作業時間：不要な探索、追加質問、再修正の削減
• レビュー：報告形式と確認観点の統一
• 再現性：担当者が変わっても同じ入力欄を使用
• 教育：良い指示の考え方をテンプレートで共有

プロンプトだけでは解決できない限界

同じプロンプトを使っても、生成結果が完全に固定されるわけではありません。重要な変更には人間のレビューが必要です。

「機密ファイルを読まない」「本番へ接続しない」と書くだけでは、技術的な制限になりません。denyルール、承認設定、サンドボックス、隔離された開発環境を使用します。

また、完了条件そのものが誤っていれば、Claude Codeが条件を満たしても業務上は不適切な成果になる可能性があります。テストが重要ケースを網羅しているか、レビュー観点が妥当かは人間が判断します。

外部ドキュメント、Webページ、MCP経由の情報には、信頼できない指示やデータが含まれる場合があります。重要なコマンドや機密ファイルの変更は承認前に確認し、取得元を限定します。

安全性は「プロンプト」「パーミッション」「サンドボックス」「人間の承認」の多層で確保する必要があります。

Claude Codeプロンプトの失敗要因と対策

実務では、曖昧な目標、広すぎる依頼、過剰なコンテキスト、自然言語だけの禁止指示、検証不足が主な失敗要因になります。症状だけでなく、原因、実害、対策を対応させて確認します。

失敗要因1｜完了状態を判断できない曖昧な目標

「いい感じに修正」「コードを改善」「可能な限り最適化」と依頼すると、Claude Codeは改善対象や優先順位を判断できません。広範囲を探索し、依頼していない改善を始めたり、何度も追加質問を行ったりする可能性があります。

その結果、トークン消費、変更ファイル数、レビュー範囲、再修正回数が増えます。

対策は、目標を利用者やシステムの状態変化で記載し、測定可能な完了条件を1つ以上置くことです。

変換例：

• 可読性を上げる → 200行を超える`processOrder`関数を責務別に分割し、公開インターフェースとテスト結果を維持する
• 高速化する → 現状の実行時間とボトルネックを計測し、同一条件で改善前後を比較する
• エラー処理を改善する → 外部APIがタイムアウトした場合に、利用者へ再試行可能なエラーを返し、監視ログへ原因を記録する

失敗要因2｜一度に依頼する範囲の広さ

認証機能の修正、UI改善、テスト追加、README更新を1つのプロンプトへまとめると、独立して検証できません。変更ファイルが増え、途中で方針が変わり、テスト失敗の原因も追いにくくなります。

大きすぎる依頼は、次のように分割します。

1. 認証エラーの再現と原因調査
2. 原因箇所の修正と回帰テスト
3. 仕様変更に伴うREADME更新

複数ファイルへ影響する場合は、探索と計画を先に行い、承認した計画だけを実装させます。別件へ切り替える場合は、新しいセッションまたは`/clear`を利用します。

失敗要因3｜重要な指示を埋もれさせる過剰なコンテキスト

長いプロンプトは、必ずしも精度を高めません。大量のコード全文、関係のない仕様書、長い会話履歴、古いルールを同時に読み込ませると、重要な指示が埋もれます。

症状として、以前の指示の見落とし、別機能の文脈との混同、回答や変更方針の不一致が発生します。Claude Codeのコンテキストには、会話、読み込んだファイル、コマンド出力が蓄積します。長いセッションでは、不要な文脈を減らす運用が必要です。

対策は、関連ファイルを直接参照し、コード全文を必要以上に貼らず、無関係なタスク間でセッションを分けることです。CLAUDE.mdは全体へ常時適用する高密度なルールに絞り、特定作業の長い手順はSkillsや別文書へ分離します。

失敗要因4｜禁止事項をプロンプトだけで制御する運用

自然言語で「危険なコマンドを実行しない」と書いても、実際の権限が許可されていれば技術的な制御にはなりません。承認時に危険なコマンドを見落とす、対象外ファイルへアクセスを試みる、外部サービスへ不要な通信を行うといったリスクが残ります。

対策として、`/permissions`、allow・ask・deny、Plan Mode、サンドボックス、組織の管理設定を目的に応じて利用します。機密ファイル、認証情報、本番環境、不要な外部ドメインは、denyルールや隔離環境で制限します。

`bypassPermissions`のように承認を省略するモードは、Claude Codeが損害を与えられない隔離コンテナやVMなど、影響範囲を技術的に閉じた環境以外で安易に利用しないことが重要です。

信頼できないWebコンテンツをシェルへ直接渡さず、提案されたコマンドと重要ファイルの変更を承認前に確認します。

失敗要因5｜自己申告だけで完了する検証不足

「修正してください」までしか依頼しない場合、コード生成後にテスト未実行、ビルド失敗、境界値の見落とし、計画外の変更が発覚する可能性があります。

対策は、テスト、型チェック、ビルド、静的解析、期待値比較をプロンプトへ含めることです。完了報告では、実行コマンド、結果、失敗項目、未実施理由を求めます。

ただし、テスト自体の妥当性は別の問題です。重要な業務ケースが網羅されているか、テストを通すために仕様が歪められていないかは人間が確認します。重要な変更では、実装担当とは別のsubagentまたは担当者による再検証も選択肢です。

【表④：Claude Codeプロンプトの失敗要因・リスク・対策】

失敗要因	主な症状	主なリスク	対策	確認担当
目標が曖昧	広範囲の探索、不要な改善	トークン増加、レビュー拡大	状態変化と完了条件を記載	タスク担当者
依頼範囲が広い	変更ファイル増加、方針変更	原因切り分け困難、手戻り	独立して検証できる単位へ分割	開発リーダー
コンテキスト過多	指示の見落とし、文脈混同	品質のばらつき	関連情報へ限定し、セッションを分離	タスク担当者
禁止事項を文章だけで制御	危険操作の提案、対象外アクセス	情報漏えい、環境破壊	deny、承認、サンドボックス	情報システム・セキュリティ
検証条件なし	テスト未実行、計画外変更	障害、再修正	コマンド、合格条件、証拠を指定	レビュー担当者

Claude Codeプロンプトをチーム標準化する5ステップ

チーム展開では、優れたプロンプトを個人が作るだけでは不十分です。対象業務、入力テンプレート、恒常ルール、安全設定、評価指標を共通化し、利用者が変わっても品質とレビュー方法を維持できる状態を作ります。

ステップ1｜対象業務と成功基準の限定

最初からClaude Codeを幅広い業務へ導入するのではなく、入力と完了条件が明確な業務を選びます。

PoCに向く業務：

• 再現手順があるバグ修正
• 既存テストへのケース追加
• 実装済み機能のドキュメント更新
• ルールが明確なCSV・Excel処理
• 変更範囲を限定できる小規模機能

条件付きで扱う業務：

• 複数サービスへ影響する機能追加
• 大規模リファクタリング
• 外部APIやMCPを利用する処理
• 個人情報を含むデータ処理

初期PoCで避ける業務：

• 本番環境への直接操作
• 要件が定まっていない大型開発
• 高機密データを含む作業
• 人間でも合否を定義できない業務

現行の作業時間、修正回数、レビュー時間、テスト成功率を事前に計測します。成功条件は速度だけでなく、品質、安全性、再現性、レビュー負荷で定義します。

ステップ2｜共通の5要素テンプレート作成

目標、対象・文脈、制約、検証、報告の5項目を入力フォームにします。各項目へ良い例と悪い例を付け、担当者の文章力に依存しない状態を作ります。

チーム共通入力シートの項目例：

• テンプレート名
• 対象業務
• 版番号
• 更新日
• 管理者
• 対象プロジェクト
• 目標
• 編集対象
• 参照対象
• 禁止事項
• 検証コマンド
• 合格条件
• 報告形式
• 承認者

共通テンプレートから、バグ修正、機能追加、レビュー、テスト、文書更新などの用途別テンプレートを派生させます。利用ログを確認し、不足する入力欄を追加し、使われない欄は削除します。

ステップ3｜CLAUDE.mdとSkillsへの恒常ルール分離

コーディング規約、テストコマンド、アーキテクチャ、禁止事項はCLAUDE.mdへ置きます。コードレビュー、リリース前確認、ドキュメント更新などの反復手順はSkillsへ分離します。

これらのファイルはGitで管理し、Pull Requestによるレビューと変更履歴を残します。個人設定とプロジェクト共通設定を分け、個人の好みがチームルールへ混入しないようにします。

管理責任の例：

• 通常プロンプト：タスク担当者
• CLAUDE.md：開発リーダーまたはアーキテクト
• Skills：対象業務の責任者
• 権限設定：情報システム・セキュリティ担当
• 個人設定：各利用者。ただし組織ルールに反しない範囲

四半期または規約変更時に、古い指示、矛盾、参照切れを確認します。

ステップ4｜権限・サンドボックス・承認工程の設定

読み取り、ファイル編集、Bash、WebFetch、MCPなど、業務ごとに必要な権限を整理します。初期PoCはdefaultまたはPlan Modeを基本とし、自動承認する範囲を限定します。

機密ファイル、認証情報、本番環境、不要な外部ドメインはdenyルールで制限します。サンドボックスや開発コンテナを利用し、ファイルシステムとネットワークの境界を設定します。

組織の管理設定を利用できる場合は、利用者が緩和できない共通ルールとして配布します。誰がプロンプトを作り、誰がコマンドを承認し、誰が成果をレビューするかも定めます。

ステップ5｜品質・工数・安全性による展開判断

同じタスクと評価条件を、複数担当者・複数回で実施し、出力のばらつきを測ります。印象や一度のデモ成功だけで導入を判断しないことが重要です。

主な評価指標は次のとおりです。

品質：

• 初回テスト成功率
• 重大なレビュー指摘数
• 意図しない変更数
• 再修正回数

生産性：

• 総作業時間
• プロンプト作成時間
• Claude Codeの実行時間
• 人間のレビュー時間

コスト：

• トークン消費
• ライセンス費
• 教育工数
• テンプレート保守工数

安全性：

• 権限違反
• 機密情報の入力
• 危険コマンドの提案
• ルール逸脱
• 承認なしの範囲拡大

【表⑤：Claude CodeのPoC評価項目】

評価分類	指標	計測方法	比較対象	合格基準の例
品質	初回テスト成功率、重大指摘、再修正回数	同一タスクを複数回実施	従来手順、担当者間	事前に自社で設定
生産性	総作業時間、プロンプト作成、実行、レビュー	工程別に時間を記録	AI未使用時	総工数で改善
再現性	出力差、変更ファイル差、手順逸脱	同条件で複数担当者が実施	テンプレート未使用時	許容差を定義
コスト	トークン、ライセンス、教育、保守	利用ログと工数を集計	現行コスト	品質を維持して許容範囲
安全性	権限違反、機密入力、危険コマンド	ログ・レビュー記録	導入前の基準	重大インシデント0件

合格した業務だけを展開し、失敗した業務は、プロンプト、実行環境、テスト、対象業務のどこに原因があるかを切り分けます。プロンプトの改善だけで解決しない場合は、対象業務の見直しや権限設計が必要です。

チーム導入の評価では、生成速度だけでなく、レビュー時間と意図しない変更を含む総工数で比較することが重要です。

Claude Codeプロンプトの導入支援は「フリーコンサルタント.jp」へご相談ください

フリーコンサルタント.jpでは、事業会社やコンサルティングファーム出身のプロ人材が、生成AI・DX活用の戦略設計から現場のルール整備、社内への知見移転までを伴走支援します。実務経験豊富な人材が、上流の方針づくりから実行段階まで一貫して関わることで、導入後の定着まで見据えた支援が可能です。

フリーコンサルタント.jpによるAI導入支援の事例

フリーコンサルタント.jpでは、AI・DX推進領域全般で企業の支援実績があります。ここでは、社内に専門人材が不足していた企業の支援事例を2件紹介します。

事例①｜大手飲食企業：需要予測・発注レコメンドAIの開発支援

200店舗以上・400品目の発注業務を店舗担当者の経験と勘に頼っており、業務が属人化していた大手飲食企業の事例です。データサイエンティストなどAI活用の経験者が社内に不足し、AIの本格運用に向けたデータ活用の進め方が分からない状態でした。

当時の課題	・データサイエンティスト・データアナリスト人材、AI活用の経験者が社内に不足 ・店舗情報・POSデータをもとにした需要予測を、複数人が同じ精度で行うことが困難 ・発注業務が現場の勘に依存し、担当者の休暇・退職で業務が滞るリスクを抱えていた
実施したこと	・店舗ごとの特徴を踏まえた変数を定義し、データを整理 ・PoC（概念実証）を経て、店舗ごとに高い精度で需要予測ができるAIモデルを構築・運用

需要予測AIの活用により発注業務の多くを自動化し、作業時間を削減。バックオフィス業務の負荷が軽減し、店舗担当者が接客などの対応に時間を割けるようになりました。

事例②｜大手通信キャリア企業：デジタル活用推進に向けたCoE組織の立ち上げ支援

業務効率化を目的に、デジタル活用組織（CoE＝Center of Excellence。複数部門の知見を集約する専門組織）の立ち上げを決定したものの、組織立ち上げの推進とデジタル技術活用の両方を担える人材が社内に不足していた大手通信キャリア企業の事例です。

当時の課題	・デジタル領域の知見と組織立ち上げ経験を併せ持つ人材が社内に不足 ・業務効率化ツールの開発・運用体制をゼロから構築する必要があった
実施したこと	・CoE組織の立ち上げから全体設計・運用構築・実運用までを一気通貫で伴走支援 ・事業部門への課題ヒアリングをもとにしたツール開発の仕組みを構築し、プロパー社員が自走できる体制へ知見を移転

CoE組織の立ち上げと運用の安定化により、組織立ち上げ前と比較して業務工数を約25%削減。プロパー社員が主体的に運用できる体制を構築し、外部人材への依存から段階的に脱却しています。

まとめ

Claude Codeのプロンプトは、長さや特殊な言い回しではなく、目標、対象・文脈、制約、検証・完了条件、報告形式の5要素で構造化することが重要です。

大きなタスクは、探索、計画、実装、検証へ分割し、実装前と完了後に人間が確認します。毎回変わる依頼は通常のプロンプト、共通規約はCLAUDE.md、反復作業はSkillsへ分けると、指示の重複とコンテキスト消費を抑えられます。

また、プロンプトはアクセス制御ではありません。機密ファイル、本番環境、外部ネットワーク、危険なコマンドは、パーミッション、denyルール、サンドボックス、承認工程で制御します。

チーム導入では、テンプレートの利用率だけでなく、初回テスト成功率、再修正回数、レビュー時間、意図しない変更数、トークン消費を評価します。最初から全業務へ展開せず、完了条件が明確で検証可能なタスクからPoCを開始することが重要です。

Claude Codeの対象業務、プロンプト標準、権限設計、PoC評価を社内だけで整理することが難しい場合は、フリーコンサルタント.jpへご相談ください。