プロンプトの根本原因分析
失敗の原因がコンテキスト、指示、形式、モデルの能力のどこにあるかを切り分けます。
「プロンプトの根本原因分析」はCoddyKit上の無料AI Prompt Engineeringレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはAI Prompt Engineering学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Prompt Engineeringコースには全4レッスンが含まれています。
根本原因分析が重要な理由
プロンプトが失敗したとき、原因は複数考えられます。文言を手当たり次第に変更すると時間を浪費するうえ、根本原因を解決せずに症状だけを修正してしまう可能性があります。その結果、入力が少し変わっただけで同じ失敗が発生します。
根本原因分析(RCA)とは、プロンプトが失敗する具体的な理由を切り分ける体系的なプロセスです。これにより、実際の問題に対応した修正が可能になります。
4つの根本原因カテゴリ
プロンプトの失敗は、必ず次の4つの根本原因のいずれかにたどり着きます。
- コンテキストの問題:モデルが正しく回答するために必要な情報を持っていない
- 指示の曖昧さ:指示に複数の妥当な解釈があり、モデルが誤った解釈を選んでいる
- 形式の競合:プロンプト内の2つの部分が矛盾する形式の指示を出している
- モデルの能力限界:タスクに、このモデルが確実に実行できる範囲を超えた推論や知識が必要である
根本原因1:コンテキストの問題
コンテキストの問題は、プロンプトに必要な情報が含まれていないために、モデルが誤って回答する場合に発生します。モデルは不足している情報を学習データで補いますが、その情報は古かったり、誤っていたり、ハルシネーションだったりする可能性があります。
テスト方法:不足している情報をプロンプトに直接追加し、回答が改善するか確認します。改善した場合、修正方法はコンテキストを追加することです(たとえばRAGによる検索を利用します)。
# Failing prompt — no context
prompt_v1 = 'What is the current price of our Pro plan?'
# Context problem test: inject the information
prompt_v2 = '''
Our pricing (as of today):
- Free: $0/month
- Pro: $19/month
- Enterprise: $99/month
Question: What is the current price of our Pro plan?
'''
# If v2 succeeds and v1 fails -> root cause is context problem根本原因2:指示の曖昧さ
指示の曖昧さは、プロンプトを複数の方法で合理的に解釈でき、モデルが誤った解釈を選んだ場合に発生します。
例:「簡潔に要約してください」。「簡潔に」とは、1文、1段落、または3つの箇条書きのどれを意味するのでしょうか。モデルは推測するしかありません。テストでは、曖昧な表現を正確な仕様に置き換え、失敗が解消されるか確認します。
# Ambiguous
prompt_ambiguous = 'Summarize the following article briefly.'
# Precise — ambiguity removed
prompt_precise = (
'Summarize the following article in exactly 2 sentences. '
'Do not exceed 50 words. Output only the summary, nothing else.'
)
# Test: if precise version succeeds, root cause was ambiguity
# Fix: replace vague qualifiers with exact specifications根本原因3:形式の競合
形式の競合は、プロンプト内の2つの部分が矛盾する指示を出した場合に発生します。モデルは一方を選び、もう一方を無視しなければなりません。通常は、より後に記述された指示や、より目立つ指示が選ばれます。
例:システムプロンプトでは「プレーンテキストで回答してください」と指定し、ユーザーメッセージでは「Markdownを使用してください」と指定するケースです。モデルはどちらにも従う可能性があり、結果が一貫しないことがあります。
# Format conflict example
system_prompt = 'You are a helpful assistant. Always respond in plain text without any formatting.'
user_message = 'List the top 5 benefits of exercise. Use markdown bullet points.'
# The model faces a conflict: plain text vs markdown.
# Detection: if output format is inconsistent across runs, look for conflicting instructions.
# Fix: ensure all format instructions agree. Move format to system prompt only.
system_prompt_fixed = (
'You are a helpful assistant. '
'Always respond using markdown bullet points for lists.'
)根本原因4:モデルの能力限界
能力限界による失敗は、タスクがモデルの信頼できる処理能力を実際に超えている場合に発生します。これは他の3つの原因とは異なり、プロンプトを変更しても完全には解決できません。
兆候:明確な指示と十分なコンテキストがあっても失敗率が高いことです。対策:より高性能なモデルを使う、タスクをより簡単な手順に分割する、または検証ステップを追加します。
# Capability limit test: try the same task on different models
models = ['gpt-4o-mini', 'gpt-4o', 'gpt-4o-2024-11-20']
results = {}
for model in models:
resp = client.chat.completions.create(
model=model,
messages=[{'role': 'user', 'content': complex_reasoning_prompt}]
)
results[model] = evaluate(resp.choices[0].message.content)
# If accuracy improves with more capable models -> capability limit
for model, score in results.items():
print(f'{model}: {score:.0%} accuracy')切り分け手法
どの根本原因が発生しているかを特定するには、体系的な切り分けを行います:
- 失敗するプロンプトを実行し、失敗の種類(誤答、形式など)を分類します
- 情報を追加 → 解決した場合:コンテキストの問題
- 指示を明確にする → 解決した場合:曖昧さの問題
- 矛盾がないか確認する → 解決した場合:形式の競合
- モデルをアップグレードする → 解決した場合:能力限界
修正は1つだけで済むはずです。複数の修正が必要なら、根本原因も複数あります。
def rca_test(base_prompt, test_input, expected_output):
results = {}
# Test 1: base (failing) prompt
results['base'] = run_and_evaluate(base_prompt, test_input, expected_output)
# Test 2: add context
results['with_context'] = run_and_evaluate(
base_prompt + '\nContext: ' + get_context(test_input),
test_input, expected_output
)
# Test 3: clarify instructions
results['clarified'] = run_and_evaluate(
clarify(base_prompt), test_input, expected_output
)
for name, passed in results.items():
print(f'{name}: {"PASS" if passed else "FAIL"}')除外と確認
RCAには2つの進め方があります:
- 除外:原因ではないものを除外します(各仮説を検証し、どの仮説では出力が変わらないかを確認します)
- 確認:修正すると、複数のテスト入力で一貫して失敗を解消する原因を特定します
確認には少なくとも3つのテスト入力が必要です。ある入力では機能しても他の入力では機能しない修正は、根本原因を解決していません。症状だけを解消している可能性があります。
def confirm_root_cause(fix_fn, test_cases, threshold=0.9):
'''fix_fn: a function that takes a prompt and returns a fixed prompt'''
passed = 0
for case in test_cases:
fixed_prompt = fix_fn(case['prompt'])
result = run_and_evaluate(fixed_prompt, case['input'], case['expected'])
if result:
passed += 1
pass_rate = passed / len(test_cases)
print(f'Fix pass rate: {pass_rate:.0%}')
if pass_rate >= threshold:
print('Root cause CONFIRMED — fix is reliable.')
else:
print('Root cause NOT confirmed — failure has multiple causes.')根本原因の記録
根本原因を特定したら、プロンプト変更ログに記録します。次の項目を含めてください:
- 確認された失敗の種類
- 根本原因のカテゴリ
- 検証した仮説
- 証拠(修正後にどのテストが通ったか)
- プロンプトに加えた具体的な変更
これにより、後から別のエンジニアが同じ失敗を再調査することを防ぎ、複数のプロンプトに共通するパターンを認識できるようになります。
rca_record = {
'prompt_id': 'summarize_v3',
'failure_type': 'wrong_format',
'root_cause': 'format_conflict',
'hypothesis': 'System prompt said plain text, user message asked for markdown',
'evidence': 'Removing markdown instruction from user message resolved failure on 8/8 test cases',
'fix_applied': 'Moved all format instructions to system prompt; removed format instructions from user template',
'fix_date': '2024-11-15'
}よくある間違い:誤った原因を修正すること
RCAで最もよくある間違いは、原因ではなく症状を修正することです。例:
- 症状:モデルが、余計な説明文を先頭に付けたJSONを返します
- 誤った修正:後処理を追加して、出力から説明文を取り除きます
- 実際の根本原因:プロンプトに形式の指示がなく、モデルが会話調をデフォルトにしていることです
- 正しい修正:「有効なJSONのみを返してください。それ以外のテキストは返さないでください」という明示的な指示を追加します
後処理によるその場しのぎの対策は、技術的負債として蓄積します。根本原因を修正する対策は、長期的に有効です。
断続的な失敗に対するRCA
失敗には断続的に発生するものもあります。プロンプトが80%の確率では機能するものの、20%の確率で失敗するケースです。この場合、プロンプトを一度実行すると正しい結果が得られるため、診断が難しくなります。
進め方:同じ入力に対してプロンプトを10~20回実行します。失敗率が0でなければ、そのプロンプトには確率的な根本原因があります。通常は指示の曖昧さ、またはtemperatureの値が高すぎることが原因です。対策:指示をより具体的にするか、temperatureを下げます。
def measure_failure_rate(prompt, test_input, expected, runs=20):
failures = 0
for _ in range(runs):
resp = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': prompt + '\n' + test_input}],
temperature=0.7
)
if not evaluate(resp.choices[0].message.content, expected):
failures += 1
print(f'Failure rate: {failures}/{runs} = {failures/runs:.0%}')理解度チェック
JSON形式の応答を求めるプロンプトが、まれに「承知しました。JSONはこちらです:」のような会話調の前置きを付けたJSONを返します。「有効なJSONのみを返してください。それ以外のテキストは返さないでください」と追加したところ、失敗しなくなりました。根本原因は何だったでしょうか。
復習:根本原因分析
プロンプトの失敗における4つの根本原因カテゴリ:
- コンテキストの問題:モデルに必要な情報が不足しています — 対策:RAGまたは直接注入によってコンテキストを追加します
- 指示の曖昧さ:複数の解釈が可能な曖昧な指示です — 対策:指示を具体化します
- 形式の競合:形式に関する指示が互いに矛盾しています — 対策:system promptに集約します
- モデルの能力限界:タスクがモデルの能力を超えています — 対策:モデルをアップグレードするか、タスクを分解します
体系的な切り分けを使って各仮説を検証します。複数のテストケースで修正を確認します。調査結果を記録します。次のレッスンでは、体系的な二分探索デバッグを扱います。
AI チューターと学ぶ AI Prompt Engineering — 無料
ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。
- コース
- 53
- レッスン
- 199
よくある質問
「プロンプトの根本原因分析」レッスンは無料ですか?
はい。「プロンプトの根本原因分析」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し(組み込みコードエディタと24時間対応のAIチューター)、AI Prompt Engineeringコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Prompt Engineeringコースには全4レッスンが含まれています。
「プロンプトの根本原因分析」で何を学びますか?
失敗の原因がコンテキスト、指示、形式、モデルの能力のどこにあるかを切り分けます。 ブラウザで直接実行するハンズオンコードでAI Prompt Engineeringを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
AI Prompt Engineeringを始めるのに経験は必要ですか?
事前経験は必要ありません。CoddyKitのAI Prompt Engineeringは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。
「プロンプトの根本原因分析」レッスンにはどのくらい時間がかかりますか?
ほとんどのCoddyKitレッスンは約5~10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このAI Prompt Engineeringレッスンでコードを書いて実行できますか?
はい。すべてのAI Prompt Engineeringレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- 予期しない出力を診断する
- プロンプトの根本原因分析
- 体系的なデバッグアプローチ
- ログ記録とドキュメント化の戦略