Claude Codeの成果物の完成度を高めるプロンプト6原則

Claude Codeのようなコーディングエージェントは、コードの断片を生成するだけのツールではなく、リポジトリを探索し、複数のファイルを修正し、テストやコマンドを実行できる作業環境である。したがって、成果物の品質は文章がどれほどもっともらしいかよりも、作業範囲と検証方法をどれほど明確に定義したかに大きく左右される。

良いプロンプトとは、長い説明文ではなく実行可能な作業仕様書である。何を作るかだけでなく、なぜ必要なのか、どのような条件を守るべきか、失敗をどう処理するか、何を通過すれば完了なのかまで伝える必要がある。

まず区別すべきこと：プロンプトと実行環境

バイブコーディングは、自然言語で意図を伝え、AIエージェントが実装を担う協業方式である。しかし、自然言語で依頼したという事実が、コードの正確性や運用の安定性を保証するわけではない。

Claude Codeの作業には、次の要素が連動して作用する。

プロンプトを適切に作成するだけですべての問題が解決するわけではない。たとえば、Claude Codeは予約実行コードを作成できるが、コンピューターの電源が切れているときにも作業を実行するには、別途サーバー、CIサービス、またはオペレーティングシステムのスケジューラーが必要である。メール送信も、実際のプロバイダーの認証情報と送信権限がなければ完成させられない。

原則1. 背景・目的・制約を先に説明する

ニュース収集エージェントを作ってのように成果物の名前だけを提示すると、エージェントはユーザー、データソース、実行環境、成功基準を推測しなければならない。同じニュース収集ツールでも、事業開発担当者、投資家、大学新聞の編集者が必要とする情報源や分類基準は異なる。

不十分な依頼

AIニュース収集エージェントを作って。

改善した依頼

私はITスタートアップの事業開発担当者だ。
毎日の業務開始前に、AI、クラウド、フィンテック分野で
事業提携や製品戦略に影響するニュースを素早く確認したい。

目標：
- 指定したキーワードごとに最新記事の候補を収集する。
- URLが同じ記事と、タイトルが類似する重複記事を削除する。
- 3か月以内に製品または提携に関する意思決定が必要かどうかを基準に、
  影響度を高、中、低に分類する。
- 結果を韓国語のメールブリーフィングにまとめる。

制約：
- 現在のリポジトリのPythonバージョンとパッケージ管理方式を維持する。
- 新しいライブラリを追加する前に、必要性と代替案を説明する。
- APIキーとメールのパスワードをコードやログに記録しない。
- 実際にメールを送信する前は、プレビューファイルのみを生成する。

まずリポジトリの構造と実行方法を調査してから、実装計画を提案して。
不明な環境情報は推測せず、質問事項として整理して。

良い背景情報には、次の4つが含まれる。

1. ユーザーと利用状況： 誰が、いつ、どのような意思決定に使用するのか
2. 目標： コードの作成そのものではなく、解決すべき問題は何か
3. 制約： 維持すべき技術、セキュリティ規則、コストまたは時間の上限は何か
4. 非目標： 今回の変更で明示的に除外する機能は何か

非目標を記載すると、範囲が際限なく広がることを防げる。たとえば、今回の段階では予約実行と実際のメール送信は除外すると定めれば、収集と分類のロジックから安定的に検証できる。

原則2. 希望する出力形式を出力契約にする

メールで見やすく送っては、人によって解釈が異なる。出力形式は例だけを示すのではなく、必須フィールド、許容値、欠落時の処理、並び順を併せて定義する必要がある。

メール件名：
[ニュースブリーフィング] {YYYY-MM-DD} 今日の重要ニュース

本文の記事形式：
1. {タイトル}
要約：{韓国語1～2文}
影響度：{高|中|低}
判定理由：{1文}
出典：{メディア名}
リンク：{原文URL}

並び順：
1. 影響度が高い順
2. 影響度が同じ場合は公開日時が新しい順

末尾の統計：
- 全記事数
- 影響度別の記事数
- 検索結果がなかったキーワード

制約：
- 要約で原文にない数値や主張を作らない。
- 日付を確認できない場合は推測せず、「確認不可」と表示する。
- リンクがない項目は最終ブリーフィングから除外する。

プログラム間で結果を受け渡す必要がある場合は、人が読む例と併せてJSONスキーマまたは型定義を求めるとよい。

{
  "title": "string",
  "summary": "string",
  "impact": "high | medium | low",
  "reason": "string",
  "source": "string",
  "url": "absolute URL",
  "published_at": "ISO 8601 string | null"
}

出力契約には形式だけでなく意味も含まれる。impact: highが何を意味するのか判定基準がなければ、JSONの構文が正確でも分類結果は一貫しない可能性がある。

原則3. 例外状況と復旧ポリシーを明示する

運用コードの完成度は、正常系よりも失敗経路に表れる。プロンプトには、予想可能な失敗、再試行の可否、ユーザーに通知する条件、記録してはならない情報を併せて記載する必要がある。

次のようにポリシーを具体的に依頼できる。

ネットワークタイムアウトは再試行可能なエラーとして処理して。
再試行の間には待機時間を設け、最大回数を超えた場合は該当する情報源のみを失敗として処理して。
認証エラーと不正なリクエストは繰り返しても解決しないため、直ちに中断して。

すべてのエラーログには、時刻、作業段階、情報源、エラー種別を残す一方で、
APIキー、メールアドレス全体、認証ヘッダー、記事本文の全文は記録しないで。
プロセスの終了状態によって、全体成功、部分的成功、全体失敗を区別して。

3回再試行や5秒待機のような値に、普遍的な正解はない。外部サービスの公式な制限、作業の緊急性、重複実行のリスクに応じて、プロジェクト内で決定する必要がある。決済やメッセージ送信のように副作用のある作業は、冪等性を保証せずに自動再試行すると重複処理される可能性がある。

原則4. 計画・最小実装・検証の順で段階的に開発する

複数の外部サービスと自動実行を一度に接続すると、エラー原因を切り分けにくい。実装を小さな検証単位に分ければ、各段階の入力と出力を確認できる。

推奨する進行順序

1. リポジトリ構造、関連ファイル、実行コマンドを調査する。
2. コードを変更する前に、計画と影響を受けるファイルを提示させる。
3. 1つのキーワードと固定されたサンプルデータで収集機能を実装する。
4. 重複排除と影響度分類をそれぞれテストする。
5. メールは実際に送信せず、ローカルプレビューで検証する。
6. テストに合格してから、実際のプロバイダー連携と予約実行を追加する。

最初の依頼は、次のように制限できる。

今は第1段階だけを実行して。
リポジトリを調査し、次の内容を報告して。
- 現在のアプリケーションのエントリーポイント
- 関連モジュールとテストファイル
- 使用しているパッケージ管理およびテストコマンド
- 変更が必要になると予想されるファイル
- 実装前に決定すべき質問

まだファイルは修正しないで。

計画を確認した後は、変更範囲を絞って実装する。

承認した計画のうち、ニュース収集と重複排除だけを実装して。
分類、メール送信、予約実行は追加しないで。
固定されたテストデータで実行できるようにし、
修正したファイルと実行したテスト結果を最後に要約して。

Claude Code環境で計画専用モードを使用できる場合は、探索と設計の段階で活用できる。ただし、計画がもっともらしいという事実は実装が正確であることを意味しないため、実際のテストとコードレビューを続けて行う必要がある。

原則5. フィードバックを失敗事例と数値で伝える

結果がいまいちだ、パフォーマンスが遅い、分類が間違っているだけでは、修正方針を決めにくい。現在の状態、期待する状態、再現用の入力、許容可能な変更範囲を伝える必要がある。

長さの修正依頼

現在、メール本文は約3,000文字で生成される。
モバイルですばやく読めるよう、500文字以内に短縮したい。
各記事の要約を1～2文に制限し、判定理由は維持して。
原文URLはタイトルにリンクし、個別のリンク行は削除して。
末尾の統計は維持して。

分類基準の修正依頼

テストデータ10件のうち8件が「高」に分類された。
長期的な技術展望や一般的な製品紹介は「低」に分類して。
3か月以内に価格、製品ロードマップ、規制対応、または提携の決定を変更すべき
具体的な根拠がある場合のみ、「高」に分類して。

添付した事例ではAとBが高、Cが低が正解だ。
分類ルールを修正し、これらの事例を回帰テストに追加して。

パフォーマンスの修正依頼

同じサンプル入力の平均実行時間は現在約45秒だ。
目標は同じ環境で30秒以内だ。
まず段階ごとの時間を測定し、ボトルネックを示して。
結果の正確性とエラー処理を削除せず、
改善案の効果とリスクを比較してから、最も小さい変更から適用して。

パフォーマンスの数値は、測定環境と入力データが同じ場合にのみ比較できる。1回の実行結果だけで改善したと判断せず、測定方法、サンプル、キャッシュ状態も併せて固定する必要がある。

原則6. 作業タイプ別のプロンプトテンプレートを使用する

新しいエージェントの作成テンプレート

[役割と状況]
私は{職業/役割}であり、{問題状況}を解決しようとしている。
この結果は{ユーザーまたは後続システム}が使用する。

[目標]
{達成すべき結果と成功基準}

[実行トリガー]
{手動実行、イベント、予約時刻など}

[入力]
- データソース：{ファイル/API/データベース}
- 必須フィールド：{フィールド一覧}
- 認証方式：{環境変数またはシークレット管理方式}

[処理ロジック]
1. {段階1}
2. {段階2}
3. {段階3}

[出力契約]
{ファイル形式、スキーマ、テンプレート、並び順と欠落時のルール}

[例外処理]
{空の結果、タイムアウト、認証エラー、部分的失敗のポリシー}

[制約と非目標]
- 維持すべき技術：{項目}
- 禁止事項：{項目}
- 今回の作業から除外する機能：{項目}

[検証]
- 合格すべきテスト：{項目}
- 完了報告に含める内容：変更ファイル、実行コマンド、テスト結果、残存リスク

まずリポジトリを調査し、実装計画を提示して。
不明な情報は推測せず、質問して。

既存機能の追加テンプレート

既存の{エージェントまたはモジュール名}に{新機能}を追加して。
新機能は{既存の段階A}の後、{既存の段階B}の前に実行される必要がある。

詳細ロジック：
- {条件と処理ルール}
- {入出力形式}
- {失敗時の動作}

維持条件：
- 既存の公開インターフェースと設定形式を変更しない。
- 既存のテストをすべて維持する。
- 関係のないファイルは修正しない。

まず影響範囲と回帰リスクを説明し、
既存の動作を維持するテストを追加してから実装して。

エラー修正テンプレート

次のエラーを再現し、根本原因を修正して。

エラーメッセージ全文：
{機密情報と個人情報を削除したエラーメッセージおよびスタックトレース}

発生条件：
- 実行コマンド：{コマンド}
- 入力：{最小再現入力}
- 環境：{オペレーティングシステム、ランタイム、関連バージョン}
- 発生時点：{どの段階か}

期待される動作：
{正常であれば現れるべき結果}

実際の動作：
{現在観察される結果}

依頼：
1. まずエラーを再現する。
2. 証拠に基づいて原因を説明する。
3. 最小限の範囲で修正する。
4. 同じエラーを防ぐ回帰テストを追加する。
5. 実行したテストと残存リスクを報告する。

エラーメッセージを貼り付ける際は、APIキー、セッショントークン、顧客データ、内部アドレスなどの機密情報を削除する必要がある。

完成例：ニュースブリーフィングエージェントの依頼

次の例は、6つの原則を1つの依頼に組み合わせたものである。

私はSaaSスタートアップの事業開発担当者だ。
AI、クラウド、フィンテック市場の変化のうち、3か月以内に製品や提携の決定を
変え得るニュースだけを毎日確認したい。

現在のリポジトリを調査し、ニュースブリーフィングツールを設計して。
最初の段階では、サンプルJSONを読み込んで重複を排除し、影響度を分類した後、
HTMLプレビューファイルを作成する機能までを実装する。
ウェブ検索、実際のメール送信、予約実行は今回の段階では除外する。

入力フィールド：
- title, url, source, published_at, body

処理ルール：
- 正規化したURLが同じ場合は重複とみなす。
- URLが異なっていても、タイトルが類似する場合は重複候補として表示する。
- 3か月以内に価格、規制対応、製品ロードマップ、または提携判断について
  具体的な変更が必要な記事のみ、影響度を「高」に分類する。
- 根拠が不足している場合は、高い等級を推測しない。

出力：
- タイトル、1～2文の要約、影響度、判定理由、出典、URLを表示する。
- 影響度が高い順に並べる。
- 全件数、重複排除件数、等級別件数を末尾に表示する。

例外処理：
- 必須フィールドがない項目は除外せず、別のエラー一覧に記録する。
- 不正な日付は推測せず、nullのままにする。
- ログに記事本文の全文や認証情報を残さない。

検証：
- 正常な入力、空の入力、重複URL、不正な日付、必須フィールドの欠落をテストする。
- 既存のテストがある場合は、すべて合格する必要がある。

作業順序：
1. リポジトリ構造と関連ファイルを調査する。
2. 修正するファイルとテスト計画を提示する。
3. 私が計画を確認するまではコードを変更しない。
4. 承認後に最小機能を実装し、テスト結果を報告する。

この依頼は、必要な機能をすべて一度に運用環境へデプロイするよう求めてはいない。範囲が制限され、出力の意味、失敗時の処理、テスト項目が併せて定義されているため、結果を判定しやすい。

プロンプトだけでは見落としやすい完成度の基準

多くのバイブコーディングの案内は、より詳細な指示を書くことに集中している。しかし、実際の完成度を左右する追加要素は、検証可能性、変更管理、可観測性、セキュリティ境界である。

1. 受け入れ条件をテストに変える

きちんと動くようにしてではなく、入力と期待する出力をペアで提供する。重要な分類事例は回帰テストとして残し、次の変更でも結果が維持されるか確認する。

2. エージェントの自己評価を最終的な証拠にしない

エージェントが完了したと言うことと、テストに合格したことは異なる。実行したコマンド、テスト結果、変更ファイル、未解決のリスクを報告させ、人がdiffを確認する必要がある。

3. 権限と機密情報を最小限にする

不要なディレクトリ、運用データベース、デプロイ資格情報まで一括で提供しない。APIキーはプロンプトやリポジトリに直接入れず、環境変数または承認済みのシークレット管理システムを使用する。出所不明のMCPサーバーやスクリプトには、機密性の高いリポジトリへのアクセス権限を与えない。

4. 観測可能なコードを求める

自動化作業には、段階別の状態、構造化されたエラー、実行時間、処理件数など、障害原因の特定に必要な情報を残す。一方で、認証情報と個人情報はログから除去する。

5. 変更を元に戻せるようにする

関係のないリファクタリングと機能追加を1つの変更に混在させない。小さな単位でdiffを確認してバージョン管理に記録すれば、誤った変更を切り分けて元に戻しやすい。

Claude Codeプロジェクトの運用ヒント

• 繰り返し使用するプロジェクトルールは、CLAUDE.mdに短く具体的に記録する。
• ビルド、テスト、lintコマンドは、実際に実行可能な形式で提供する。
• 機密情報、一時的なエラーログ、長い参考文書をCLAUDE.mdに入れない。
• 大規模な変更の前に、関連ファイルと依存関係を先に調査させる。
• 新しいパッケージを追加する際は、必要性、ライセンス、保守リスクを検討する。
• 危険な削除、デプロイ、データ変更コマンドを自動承認しない。
• 外部APIやMCPを接続する前に、データがどこへ送信されるか確認する。
• 完了時に、変更ファイル、実行コマンド、テスト結果、残っている制限を要約させる。

提出前チェックリスト

• ユーザーと利用状況が説明されているか
• 目標と非目標が分けられているか
• 既存技術と変更禁止範囲が明示されているか
• 入力データと出力形式が定義されているか
• 分類値と状態値の意味が説明されているか
• 空の結果、認証失敗、タイムアウト、部分的失敗のポリシーがあるか
• 計画と実装が段階別に分けられているか
• 正常・境界・失敗事例のテストがあるか
• 機密情報と個人情報がプロンプトおよびログから除外されているか
• 人が確認するdiffと実行証拠を求めているか

良いClaude Codeプロンプトの核心は、命令を長く書くことではない。エージェントが推測しなければならない部分を減らし、結果が正しいかどうかを第三者も再現して判定できるようにすることである。