← 試験の目次へ

Developer Foundations ドメイン4: 評価・テスト・デバッグ（2.6%）

この章で学ぶこと: エラーの種類の見分け方、回復のしかたの選び方、トレースで失敗のパターンを見つける方法、問題が「つなぎこみ（統合レイヤー）」にあるのか「モデルの出力」にあるのかの切り分け。

スキル 配点
デバッグとエラー処理（Debugging and Error Handling） 2.6%

本番の53問のうち約1問の小さいドメインです。評価（eval）の作り方は Architect Professional で大きく扱います。

前の章とつながる部分:

1. エラーの種類を見分ける

Claude アプリで起きる問題は、大きく4つに分かれます。

種類 どう見えるか 例
A. リクエストの失敗（API エラー） HTTP 4xx / 5xx。本文に error.type 400 invalid_request_error、429 rate_limit_error、529 overloaded_error
B. 正常な応答だが途中で止まった HTTP 200。stop_reason が end_turn 以外 max_tokens、pause_turn、refusal、model_context_window_exceeded
C. ツールの失敗 自分のツールの実行が失敗、または Claude のツール呼び出しが不正 外部 API のタイムアウト、必須パラメータの欠け
D. 出力の中身の問題 形式は正しいが、中身が間違っている ハルシネーション、古い情報、指示の読み違い

1.1 stop_reason はエラーではない

公式ドキュメントは、stop_reason とエラーをはっきり区別しています。

stop_reason エラー
届き方 応答の本文の一部 HTTP 4xx / 5xx
意味 生成が止まった理由（正常に処理された） リクエストの処理そのものが失敗した
中身 正しい内容が入っている エラーの詳細が入っている

1.2 stop_reason の値と対応

値 いつ起きるか 対応
end_turn 自然に答え終わった そのまま使う
max_tokens max_tokens の上限に達した max_tokens を上げるか、続きを生成させる。ツール呼び出しの途中で切れたら、上限を上げて送り直す
stop_sequence 指定した停止文字列が出た どれが出たかは stop_sequence で確認
tool_use ツールを呼ぼうとしている ツールを実行して結果を返す
pause_turn サーバーツールのループが反復の上限に達した 応答をそのまま会話に足して、もう一度送ると続きをやる
refusal Claude が応答を断った stop_details を読み、必要なら別のモデルで再試行する
model_context_window_exceeded 応答がコンテキストウィンドウを使い切った 応答は途中で切れたものとして扱う

公式のベストプラクティス: どの応答でも、まず stop_reason を確認します。

2. 回復のしかたを選ぶ

問題 回復のしかた やってはいけないこと
429、500、529 などの一時的なエラー 指数バックオフで再試行。429 は retry-after に従う。公式 SDK は初期値2回まで自動で再試行する すぐに何度も連打する
400、401、403、413 など 原因を直してから送る（形式、キー、権限、大きさ） そのまま再試行する
max_tokens で途中切れ 上限を上げる、続きを生成させる、出力を小さく分ける 切れた JSON をそのまま使う
pause_turn アシスタントの応答を会話に足して送り直す エラーとして捨てる
refusal 依頼の内容を見直す。必要なら別のモデルで 同じ依頼を同じモデルに連打する
ツールの実行の失敗 tool_result に "is_error": true と、何が起きて次に何をすればよいかを書いて返す 「failed」だけを返す。空の結果を成功として返す
不正なツール呼び出し ツールの description を詳しくする。strict: true で入力をスキーマに合わせる 毎回ツール側で黙って補う
出力の中身の間違い プロンプトや渡すデータを直す（第4節） 再試行だけで直ると考える

2.1 ツールのエラーの返し方（公式の例の形）

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "Rate limit exceeded. Retry after 60 seconds.",
  "is_error": true
}

公式のポイント:

3. トレースで失敗のパターンを見つける

3.1 何を記録するか

記録するもの なぜ
request-id（応答のヘッダー、エラー本文の request_id） どのリクエストかを特定し、サポートに問い合わせる
stop_reason と usage（トークン数） 途中切れやコストの異常を見つける
ツールの呼び出しと結果 どのツールで失敗したか、何が返ったかを見る
モデル ID とプロンプトの版 変更の前後で比べる

3.2 Agent SDK の OpenTelemetry

Agent SDK は、エージェントがしたこと（どのツールを呼んだか、各モデル呼び出しにかかった時間、使ったトークン、どこで失敗したか）を OpenTelemetry のトレース・メトリクス・ログとして出せます。

ポイント 内容
有効にする CLAUDE_CODE_ENABLE_TELEMETRY=1 と、少なくとも1つのエクスポーター（例: OTEL_TRACES_EXPORTER=otlp）を設定するまでオフ
送り先 OTLP を受け付ける任意の基盤（ホスト型の監視サービスや、自前のコレクター）。OTEL_EXPORTER_OTLP_ENDPOINT で指定
トレース 各やりとり、モデル呼び出し、ツール呼び出し、フックのスパン。トレースはベータで、CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 も必要
つなげて見る スパンには session.id が付く。同じセッションの複数の query() を1本の時系列で見られる
失敗しても止まらない 送り先に届かなくても、エージェントはふつうに動き、データだけが捨てられる。届いているかはコレクター側で確認する
中身の扱い 初期設定では構造の情報（時間、モデル名、ツール名、トークン数）だけ。プロンプトやツールの中身は、OTEL_LOG_USER_PROMPTS=1 や OTEL_LOG_TOOL_CONTENT=1 などを付けたときだけ記録される

3.3 トレースからパターンを探す（一般的な進め方）

公式ドキュメントに決まった手順はありません。一般的な進め方として:

  1. 失敗した例を集め、stop_reason、エラーの種類、ツールの結果で分類する
  2. 多い種類から順に見る（例: 「特定のツールでタイムアウトが多い」「長い入力のときだけ max_tokens」）
  3. 1つの例について、モデルが実際に受け取ったもの（システムプロンプト、会話、ツールの結果）を確認する
  4. 1つだけ変えて試し直し、評価用データで良くなったかを測る

Anthropic の Research システムでも、本番のトレースをすべて取れるようにしたことで、失敗の理由（悪い検索クエリ、悪い情報源、ツールの失敗）を見分けて直せるようになったと説明されています（ドメイン1 の出典）。

3.4 Claude Code での調べ方

道具 使い方
/doctor インストール、設定、拡張、コンテキストの使われ方を自動で調べ、直し方を提案する。起動しないときはシェルで claude doctor
/mcp MCP サーバーの状態を確認する
/context コンテキストを何が使っているかを見る
/feedback 問題を Anthropic に直接報告する

4. つなぎこみの問題か、モデルの出力の問題か

この節の切り分けの手順は、公式の事実（エラーと stop_reason の区別、ツールのエラーの返し方）にもとづいて組み立てた一般的な考え方です。

4.1 切り分けの順番

順 確認すること はいなら
1 HTTP エラーが出ているか つなぎこみ（リクエストの形、キー、権限、レート制限、大きさ）
2 stop_reason が end_turn 以外か 設定や処理の問題（上限、pause_turn の処理、ツールの実行）
3 ツールの結果がエラー・空・古い・不正確か つなぎこみ（ツール、外部システム、検索で取ってきたデータ）
4 自分のコードが応答を正しく読めているか（パース、どのブロックを読むか） つなぎこみ（応答の処理）
5 モデルが受け取った情報は正しく十分なのに、答えが間違っているか モデルの出力の問題（プロンプト、例、モデルの選択）

大事な考え方: 「モデルが間違えた」と決める前に、モデルが実際に何を受け取ったかを確かめます。古い文書や間違ったツールの結果を渡していれば、正しく答えられないのは当然です。

4.2 よくある例

症状 原因の場所 理由
ときどき JSON のパースに失敗する。そのとき stop_reason は max_tokens 設定 上限で切れている。上限を上げるか、構造化出力を使う
料金の答えが古い。ログを見ると、検索ツールが古い文書を返している つなぎこみ（データ） モデルは渡されたデータに従っている
同じ質問でも答えが毎回違い、どれも根拠がない モデルの出力 根拠のない推測。第4.3節の対策
応答は正しいのに画面に出ない つなぎこみ（応答の処理） 例えば最初のブロックだけ読み、後ろのテキストを見ていない

4.3 モデルの出力の問題を減らす（公式のハルシネーション対策）

手法 内容
「わからない」と言ってよいと伝える 不確かなときに認めることを明示的に許すと、誤った情報が大きく減る
先に原文を引用させる 長い文書（2万トークン超）では、まず原文の言葉どおりの引用を抜き出させてから作業させる
引用と出典で確かめる 主張ごとに引用と出典を付けさせる。裏付けの引用が見つからない主張は取り消させる
thinking を確認する 答えがおかしいとき、要約された thinking を読み、間違った論理や前提を探す
複数回で比べる（Best-of-N） 同じプロンプトを何回か実行して比べる。食い違いはハルシネーションのしるし
外の知識を使わせない 渡した文書の情報だけを使うよう指示する

5. 試験に向けたまとめ

問われ方 考え方
HTTP 200 なのに結果がおかしい エラーではない。まず stop_reason を見る
max_tokens で途中切れ 上限を上げる。再試行のバックオフでは直らない
pause_turn 応答を会話に足して送り直す
ツールが失敗した is_error: true と具体的な説明を返す
ツールの呼び出しが不正 説明を詳しくする。strict: true
本番の失敗の原因がわからない トレース（OpenTelemetry）、request-id、ツールの結果を見る
モデルのせいか、つなぎこみのせいか モデルが受け取ったものを先に確かめる

6. 用語集

用語 意味
トレース 1つの処理の中で何が起きたかを、時間の流れで記録したもの
スパン トレースの中の1つの区間（1回のモデル呼び出し、1回のツール呼び出しなど）
OpenTelemetry トレース・メトリクス・ログを集める共通の仕様
is_error ツールの結果がエラーであることを示す印
pause_turn サーバーツールのループが一時停止したことを示す stop_reason
ハルシネーション もっともらしいが事実でない内容を作ること

出典

第1節の4分類、第3.3節、第4.1節・第4.2節は、公式の事実を組み合わせた一般的な考え方で、公式ドキュメントからの直接の要約ではありません。内容は上の出典を要約・言い換えたものです（ライセンスに配慮して書き直しています）。