gaia-debugging

GAIA デバッグスキル

GAIA の質問に失敗した場合は、根本原因を体系的に診断し、的を絞った修正を提案します。

使用するタイミング

• 特定の task_id が誤った回答を返す、またはタイムアウトする場合
• 2 回の実行間で合格率が低下し、回帰の原因を特定する必要がある場合
• 特定の質問クラスが一貫して失敗する理由を把握したい場合

失敗モードの分類

コード	モード	症状	修正の方向性
TG	ツール不足	エージェントに必要なツールがありません（画像 OCR なし、PDF リーダーなし）	カタログにツールを追加する
RM	推論ミス	エージェントは正しいデータを持っていますが、誤った結論を導きます	システムプロンプトを改善し、CoT の指示を追加する
EB	抽出バグ	回答はトレース内にありますが、FINAL_ANSWER: の正規表現が一致しません	回答の抽出パターンを修正する
LI	ループの問題	エージェントがループし（同じツール呼び出しを再度要求し）、ターン上限に達します	最大ターン数を増やすか、ループ検出を追加する
DS	データセットシフト	正解データが現在ウェブに表示されている内容と異なります	HAL データセット監査の対象として報告する
AT	API タイムアウト	ツール呼び出しがタイムアウトし、エージェントが結果を取得できません	ターンごとのタイムアウトを延長する

診断ワークフロー

ステップ 1 — 質問のトレースを読み込む

# Find the result for the task_id in the latest run
RESULTS=~/.cache/ruflo/gaia/results-latest.json
node -e "
  const r = JSON.parse(require('fs').readFileSync('$RESULTS'));
  const q = r.results.find(x => x.task_id === '$TASK_ID');
  console.log(JSON.stringify(q, null, 2));
"

ステップ 2 — 失敗を分類する

トレースの出力を確認します。

1. ツールがまったく呼び出されていない → RM または設定の問題
2. ツールは呼び出されたがエラーを返した → TG または AT
3. ツールはデータを返したが、回答が誤っている → RM または EB
4. トレース内の回答は正しいのに、不正解と判定される → EB
5. max-turns に到達した → LI、または現在のモデルには質問が難しすぎる

ステップ 3 — 拡張ログを有効にして再実行する

node v3/@claude-flow/cli/bin/cli.js gaia-bench run \
  --level 1 --limit 1 \
  --task-id $TASK_ID \
  --models claude-sonnet-4-6 \
  --max-turns 20 \
  --output json

ステップ 4 — 的を絞った修正を適用する

失敗	対応
TG — web_browse が不足	gaia-tools/index.ts が web_browse をエクスポートしていることを確認し、ツール登録を確認する
TG — 画像 OCR が不足	image_describe ツール呼び出しを追加し、GOOGLE_AI_API_KEY を確認する
RM — 推論	システムプロンプトに「回答する前に、収集したすべての事実を列挙してください」という指示を追加する
EB — 抽出	トレースに対して FINAL_ANSWER_RE の正規表現を手動でテストする
LI — ループ	gaia-agent.ts にツール呼び出しの重複排除ガードを追加する
AT — タイムアウト	DEFAULT_PER_TURN_TIMEOUT_MS を大きくするか、--max-turns フラグを使用する

ステップ 5 — 修正を検証し、パターンを保存する

# Re-run the single question
node … gaia-bench run --task-id $TASK_ID --models $MODEL --output json

# If now passing, store the pattern
npx @claude-flow/cli@latest memory store \
  --namespace gaia-debug-patterns \
  --key "fix-$FAILURE_CODE-$(date +%Y%m%d)" \
  --value "task_id=$TASK_ID, mode=$FAILURE_CODE, fix=$FIX_DESCRIPTION"

クイックリファレンス：ツールカタログの確認

node -e "
  const { createDefaultToolCatalogue } = require('./v3/@claude-flow/cli/src/benchmarks/gaia-tools/index.js');
  const cat = createDefaultToolCatalogue({});
  console.log('Tools registered:', cat.definitions.map(t => t.name));
"

想定値：web_search、file_read、web_browse、image_describe、python_exec

パターンの保存

デバッグセッションを解決したら、調査結果を保存します。

npx @claude-flow/cli@latest memory store \
  --namespace gaia-debug-patterns \
  --key "session-$(date +%Y%m%d-%H%M)" \
  --value '{"task_id":"$TASK_ID","failure_mode":"$CODE","fix":"$FIX","verified":true}'

過去の類似した失敗を検索します。

npx @claude-flow/cli@latest memory search \
  --namespace gaia-debug-patterns \
  --query "extraction bug final answer regex"