agent-experience

エージェント体験の監査

AI エージェントが実際にオンボーディングし、現実的なタスクを実行しようとしたときに、製品／SDK／ドキュメントがどれだけうまく機能するかを評価します。短い一文のプロンプトから始め、何も貼り付けない状態で行います。エージェントはドキュメントを見つけ、必要なものをインストールし、実際の作業を試みる必要があります。これがエージェント DX を評価する唯一の正直なテストです。

このスキルは複数のサブエージェントを並行して起動し、それぞれのツール呼び出しのトレースを記録して、Skill Test Arena のダッシュボードと同じ評価項目（セットアップの手間、速度、効率、エラーからの回復、ドキュメントの品質）で体験を評価します。

基本原則

手取り足取り教えないでください。 サブエージェントに与えるのは、「{製品} を始めて、{その主な機能} を使ってください」 のような短いプロンプトだけです。ドキュメントを見つけ、手順を選び、実際のエラーに遭遇する必要があります。優れたドキュメントならこの試練に耐えますが、そうでなければ耐えられません。

ワークフロー

以下の手順を順番に実行してください。先に進んで省略してはいけません。

ステップ 1 — 対象を特定し、抽象的な目標を定義する

ユーザーが何を監査しようとしているのかを特定します。対象は次の 3 つの形式のいずれかで指定されます。

• URL — ドキュメントサイトや製品ページ（例：https://docs.example.com）。サブエージェントはこの URL を起点にして調査を開始します。
• リポジトリ／ファイルパス — SKILL.md の監査や SDK のリポジトリの場合。
• 製品名 — ユーザーの指定が曖昧な場合（「自分の製品をテストして」など）は、AskUserQuestion を使って URL またはリポジトリを尋ねます。

このスキルは特定の製品に依存しません。ユーザーが何を監査したいのか、決して決めつけないでください。 オペレーターのメールドメイン、git のリモート、リポジトリ名、最近開いたファイル、メモリ、CLAUDE.md など、環境から得られる情報をもとに対象を推測してはいけません。文脈から特定の企業が強く示唆される場合でも、ユーザーへの質問で特定の製品、URL、企業名を事前入力したり、デフォルトにしたりしてはいけません。「URL を貼り付ける」「ローカルパスを貼り付ける」「製品名を入力する」のように、中立的な選択肢だけを提示して自由形式で尋ねます。ユーザーが呼び出し時に対象を指定していない場合は、先入観を持たず、最初からユーザーに尋ねてください。

ユーザーが対象を指定した後に、必要最小限の調査を行います。WebFetch は最大 1 回とし、製品が何か、スタートガイドがあるかを確認するだけで十分です。手順を抽出するのではなく、従うべきフローがあることを確認するための調査です。ドキュメントに進む道筋を示してもらうことが重要です。

手順ごとのチェックリストではなく、抽象的な目標を 1 つ定義します。 目標は「オンボーディングを完了する」や「製品の主な機能を一度使う」といったレベルにします。具体的な操作のリストにしてはいけません。

理由：手順を細かく指定すると、エージェントの行動を誘導してしまいます。「example.com にアクセスする」と指示したのに、ドキュメントのクイックスタートで別の URL にアクセスする場合、エージェントはユーザーの指示とドキュメントのどちらに従うべきか迷います。これではテストの妨げになります。

適切な抽象的目標の例（対象製品はユーザーが指定します。以下の例は説明のためのものであり、デフォルトではありません）：

• 検索 API → 「スタートガイドを完了してください。コードから API を呼び出し、ドキュメントで意味のある結果として扱われている内容を出力できれば成功です。」
• 決済 API → 「テスト決済を行うためのスタートガイドのフローを完了してください。決済 ID、または同等の確認情報を取得できれば成功です。」
• ブラウザー自動化 SDK → 「スタートガイドを最初から最後まで完了してください。ドキュメントで推奨されている方法を使って、クラウドブラウザーのセッションを実行するコードを用意できれば成功です。」
• SKILL.md → 「スキルの指示に従い、スキルがうたう用途で成果を上げてください。」

不適切な目標の例（指定が細かすぎるため、避けてください）：

• 「https://example.com にアクセスする」（ドキュメントでは別の URL を使うかもしれません）
• 「Playwright を使う」（ドキュメントでは Stagehand や Selenium を推奨しているかもしれません）
• 「ページのタイトルを出力する」（ドキュメントではセッション ID、レスポンス本文、その他の内容を出力するかもしれません）

サブエージェントは抽象的な目標に照らして、ドキュメントの説明どおりにオンボーディングを完了できたか（はい／いいえ／一部完了）を自己報告します。エージェントが実際に達成した具体的な成果は、あらかじめ定義したチェックリストではなく、トレース内の primary_outcome_achieved に記録します。

対象に明確なスタートガイドのフローがない場合（まれです。README でさえフローになり得ます）は、続行する前に、何をもって「完了」とするかをユーザーに尋ねてください。

ステップ 2 — AskUserQuestion を使って監査設定を収集する

AskUserQuestion を1 回の呼び出しで 4 つの質問とともに使用します。選択肢は質問ごとに最大 4 つです。

1. テストの深さ（単一選択、ヘッダー："Depth"）：

   • 5 agents (Recommended) — バランスの取れたカバレッジ
   • 3 agents — 手早い動作確認
   • 10 agents — 綿密な確認。コストは高くなります

2. プログラミング言語（複数選択、ヘッダー："Languages"）：最大 4 つ選択 — Python、TypeScript、Go、Shell/Bash（ユーザーが選択解除できるようにします）。

3. ペルソナ（複数選択、ヘッダー："Personas"）：

   • Standard (Recommended) — 行動上の味付けのない、中立的な基準です。「タスクを実行するだけ」です。偏りのない測定に最適です。
   • Pragmatic — とにかく動作させることを優先し、最短経路で進めます
   • Thorough — コーディングの前にドキュメントを最初から最後まで読みます
   • Skeptical — ドキュメントの主張を検証します

4. 実行モード（単一選択、ヘッダー："Exec mode"）：

   • Allow Bash (Recommended) — サブエージェントがマシン上で npm install、curl などを実行できます。最も実態に即した設定です。
   • Draft-only — サブエージェントはドキュメントを取得してコードを作成できますが、何も実行しません。より安全です。

ユーザーの回答後、モデルの選択についてもう 1 つ質問します。

5. モデル（単一選択、ヘッダー："Model"）：
   • Sonnet (Recommended) — コストと品質のバランスが取れており、ほとんどの監査に適したデフォルトです
   • Opus — 最も優れた推論能力を備え、コストは最高です。情報量が多いドキュメントや曖昧なドキュメントに適しています
   • Haiku — 最も低コストで高速です。小型モデルでもドキュメントを使いやすいか確認するのに適しています
   • Mixed comparison — エージェントを Opus、Sonnet、Haiku に振り分け、モデルサイズによってドキュメントの品質がどう変わるかを確認できます。「弱いモデルでも堅牢なドキュメントか」を調べるのに役立ちます

選択されたモデルを model パラメーターで各 Agent 呼び出しに渡します。Mixed の場合は、N 個のエージェントを 3 つのモデルにほぼ均等に割り当て（スロット番号順にラウンドロビン）、トレースとレポートに各エージェントが使用したモデルを記録します。

ユーザーの回答後、次の値が揃います：depth（N）、languages[]、personas[]、exec_mode、model。

exec_mode = "Allow Bash" の場合、認証情報について質問する 2 回目の AskUserQuestion を行います。

• 認証情報（単一選択、ヘッダー："Credentials"）：
  • Auto-discover (Recommended) — スキルがユーザーの環境変数、一般的なドットファイル、認証情報マネージャーを確認します。何も見つからない場合に限り、貼り付けを求めます。繰り返し使用する場合や、別の担当者が監査を実行する場合に最適です。
  • None — let agents block (friction test) — エージェントを認証情報がない状態にし、セットアップ上の摩擦として計上します。ドキュメントのみを監査する場合に最適です。
  • Paste manually — キーを直接貼り付けると、スキルが挿入します。キーをまだローカルに保存していない場合に使用します。

ユーザーが Auto-discover を選択した場合は、続行する前に以下のステップ 2.5を実行します。Paste manually を選択した場合（または自動検出で見つからなかった場合）、AskUserQuestion で認証情報の値を尋ねます。名前ではありません。その後、スキルは汎用的で製品に依存しない名前を使って、各ワークスペースの .env に認証情報を書き込みます。

• プライマリ認証情報 → API_KEY
• セカンダリ（例：プロジェクト ID／組織 ID）→ PROJECT_ID
• 3 つ目（例：Webhook シークレット）→ SECRET

BROWSERBASE_API_KEY、EXA_API_KEY、STRIPE_SECRET_KEY のような製品固有の名前は使用しないでください。そのような名前があるとエージェントの誘導につながります。環境変数に BROWSERBASE_API_KEY があるのを見ると、SDK が実際にどの環境変数を想定しているかを調べるためにドキュメントを読むのを省略してしまいます。汎用名を使えば、エージェントは次の作業を行う必要があります。

1. ドキュメントを読み、製品が実際に使用する環境変数名（例：BROWSERBASE_API_KEY）を確認する。
2. 汎用の API_KEY の値を SDK が必要とする形式に変換する。再エクスポート（export BROWSERBASE_API_KEY=$API_KEY）するか、コード内で直接渡します（new Browserbase({ apiKey: process.env.API_KEY })）。

エージェントが変換方法を特定できなかった場合、それはドキュメントの品質を示すシグナルです。つまり、認証情報の命名がドキュメントで明確に説明されていませんでした。

ステップ 2.5 — 認証情報の自動検出（ユーザーが Auto-discover を選択した場合のみ）

段階的なルックアップを実行します。使用可能な候補が見つかった最初の段階で停止します。 認証情報の値をチャットに出力してはいけません — 名前とソースパスのみを出力します。ユーザーは名前で選択し、スキルは内部的に名前 → 値 → ワークスペースの .env をマッピングします。

ターゲットの URL/リポジトリからプロダクトスラッグを導出し、関連する一致に偏らせます。例: https://docs.browserbase.com → スラッグ browserbase。候補をランク付けする際は、小文字の部分文字列一致(大文字小文字を区別しない)を使用します。

段階 1 — すでにエクスポートされている環境変数(無料、副作用ゼロ):

printenv | grep -iE '^[A-Z][A-Z0-9_]*_(API_KEY|TOKEN|SECRET|KEY)=' | cut -d= -f1

これは名前のみを返します。名前にプロダクトスラッグが含まれているものがあれば、それらが最上位の候補です。

段階 2 — 絞り込んだ dotfile スキャン(ハードコードされた短いリストであり、再帰的な grep ではありません):

grep -hE '^[[:space:]]*export[[:space:]]+[A-Z][A-Z0-9_]*_(API_KEY|TOKEN|SECRET|KEY)=' \
  ~/.zshrc ~/.bashrc ~/.bash_profile ~/.zprofile ~/.env ./.env ./.envrc 2>/dev/null \
  | sed -E 's/^[[:space:]]*export[[:space:]]+([A-Z0-9_]+)=.*/\1/' \
  | sort -u

許可されるファイル: ~/.zshrc、~/.bashrc、~/.bash_profile、~/.zprofile、~/.env、./.env、./.envrc。このリストを拡張しないでください。再帰しないでください。~/Library、~/.config/、~/Documents などをスキャンしないでください。 これが許可リストの全体です。それ以外はスコープ外であり、無関係なシークレットが漏洩するリスクがあります。

一致ごとに (NAME, source_path) を記録します。値は遅延して読み取ります — ユーザーが選択を確定したときにのみ — その正確な名前で特定のソースファイルを再 grep することによって。

段階 3 — 認証情報マネージャー(op または security が PATH 上にあり、かつ段階 1〜2 で良い一致がなかった場合のみ):

• 1Password CLI: op account list が終了コード 0 で終了しない限りスキップします(つまり、ユーザーがサインインしていない)。スキル内で対話的な認証フローをトリガーしないでください。
• macOS キーチェーン: security find-generic-password -l "<expected-name>" -w — 最も可能性の高い名前(例: BROWSERBASE_API_KEY)で一度だけ試します。サイレントに失敗した場合は保存されていないことを意味します。

認証情報マネージャーがヒットを返した場合は、段階 1〜2 と同じ方法で候補としてリストします。

段階 4 — 貼り付けへのフォールバック: 上記のすべての段階で候補がゼロだった場合は、手順 2 で説明されている手動貼り付けフローにフォールスルーします。

候補をユーザーに提示する。 段階 1〜3 の後:

• 候補がちょうど 1 つで、その名前にプロダクトスラッグが含まれている場合 → それをサイレントに使用します。チャットに 1 行の確認をログ出力します: Using BROWSERBASE_API_KEY from ~/.zshrc.(名前とソースのみ — 値は決して出力しない。)
• 候補が複数ある場合は、AskUserQuestion(単一選択、ヘッダー: "Use which credential?")を最大 4 つのオプションで使用します:
  • 最上位の候補ごとに 1 つのオプションを <NAME> (from <source>) の形式で
  • さらに Paste manually instead のエスケープハッチ
  • 候補が 3 つを超える場合は、スラッグ関連性で上位 3 つを表示し、残りで再質問する Show all オプションを追加します。
• 候補がない場合 → 段階 4(貼り付け)にフォールスルーします。

値を読み取る。 ユーザーが選択を確定したら(または自動選択されたら)、値を読み取ります:

• 段階 1: printenv <NAME>(stdout をキャプチャし、エコーしない)。
• 段階 2: 特定のソースファイルを正確な export <NAME>= 行で再 grep し、右辺を解析して、周囲の引用符を除去します。
• 段階 3: op read "op://<vault>/<item>/<field>" または security find-generic-password -l <NAME> -w。

値を、貼り付けフローと同じ汎用名(API_KEY、PROJECT_ID、SECRET)を使用して、エージェントごとのワークスペース .env ファイルに書き込みます — 手順 2 を参照してください。ディスカバリ層はインジェクションの上流にあります。下流の動作(汎用名、エージェントがそれらをマッピングするためにドキュメントを読む必要がある)は変更されません。

オーケストレーターが保持する認証情報。 エージェントごとの .env ファイルを書き込んだ後、オーケストレーターは元のプロダクト固有の名前 → 値(例: BROWSERBASE_API_KEY)を、手順 6 / 6.5 / 8 の下流の検証作業のために自身で利用できるように保持します — たとえば、エージェントが報告したセッション ID が実際に解決されることを確認するために curl でプロダクトの API を呼び出したり、セッションメタデータを取得してレポートを充実させたりします。オーケストレーターは printenv でそれらを読み取ることができます(どこにも保存する必要はありません — 自動ディスカバリがそこから取得したため、親シェルはすでにそれらを持っています)。 意図的に非対称にしています。サブエージェントには汎用の API_KEY ／ PROJECT_ID ／ SECRET のみを表示するため、ドキュメント品質テストの公平性が保たれます（実際の変数名を見つけるには、ドキュメントを読む必要があります）。オーケストレーターは監査対象ではないため、検証には実際の名前を自由に使用できます。

スキルが守るべきプライバシー保証：

• 認証情報の値を、チャット出力、トレース、レポート、またはエージェントごとのワークスペース .env 以外のファイルに書き込まないでください。
• 値を製品固有の名前でサブエージェントのワークスペースに再エクスポートしないでください。サブエージェントには汎用名のみを表示します。
• 値は不透明な文字列として扱ってください。長さ、接頭辞、フィンガープリントをログに記録しないでください。
• HTML レポートには自動検出が行われたこと（および使用された名前）を記録しますが、値は記録しません。

ステップ 3 — 安全性の確認

exec_mode = "Allow Bash" の場合は、エージェントを起動する前に、チャットに簡潔な警告を表示します。「エージェントがこのマシン上で実際のシェルコマンド（npm install、curl、pip install、git clone）を実行する可能性があります。エージェントによる変更を許可できるディレクトリにいることを確認してください。5 秒後に続行します。中止するには Ctrl-C を押してください。」 — その後、続行します。

sleep は実行せず、警告を表示したらそのまま続行してください。エージェントが作業を始める前に、ユーザーは警告を確認できます。

ステップ 4 — 短いプロンプトを生成する（チェックリストなし）

N 個の各バリアントについて、(persona, language, prompt) のタプルを生成します。プロンプトは、抽象的な目標と言語を示す1 文または 2 文にします。サブチェックリストや、手順を細かく指示する記述は含めません。

テンプレート：

{persona_prefix} {product}'s getting-started guide using {language}.{persona_tail} You've completed it when you've done whatever the guide treats as the primary successful outcome.

ほとんどのペルソナでは {persona_tail} は空です。懐疑的なペルソナでは、別の文として「気になる点を指摘する」という指針を（先頭にスペースを付けて）追加し、接頭文が文法的に自然になるようにします。各ペルソナの接頭文と末尾文については、references/prompt-variants.md を参照してください。

例（プレースホルダーとして Acme を使用しています。ユーザーが指定した製品名に置き換えてください）：

• 実用重視 × TypeScript → 「Acme のスタートガイドにざっと目を通してから、TypeScript（Node.js）を使って進めてください。ガイドで最も重要な成功とされている結果を達成したら完了です。」
• 徹底重視 × Python → 「Acme のスタートガイドを読んでから、Python を使って進めてください。ガイドで最も重要な成功とされている結果を達成したら完了です。」
• 懐疑的 × Shell → 「bash/curl のみを使って Acme のスタートガイドに従ってください。進めながら、ドキュメントで誤りや不明瞭な点があれば指摘してください。ガイドで最も重要な成功とされている結果を達成したら完了です。」

サブエージェントには、成功の結果が何かを伝えません。ドキュメントを読んで判断する必要があります。それが狙いです。ドキュメントの品質が高ければ、成功の結果が明確に伝わります。品質が低ければ、エージェントは完了の判断ができません。それ自体が指摘事項になります。

ペルソナごとの接頭文ライブラリについては、references/prompt-variants.md を参照してください。ペルソナと言語を組み合わせ、N 個になるまで採用します。組み合わせが N 個に満たない場合は、接頭文の表現を少し変えて繰り返してください。

プロンプトにドキュメントの内容を貼り付けないでください。

ステップ 5 — N 個のサブエージェントを並列で起動する

references/subagent-brief.md を読んでください — これは各サブエージェントが受け取る完全なブリーフです。そこには次のことが書かれています:

• あなたは実際のタスクを行っている実際の開発者です
• 実際のツール(WebFetch、許可されていれば Bash、Write)を使用してください
• 認証情報が必要な場合は、明確な停止して質問するメッセージを通じてユーザーに尋ねてください(スキルはこれをフリクションとして記録します)
• 最後に、ツール呼び出し、エラー、所要時間の見積もり、完了ステータスを含むトレースを返してください

各バリアントについて、Agent ツールを呼び出します(サブエージェント: general-purpose)。ユーザーの選択に従って model: "opus" | "sonnet" | "haiku" を渡します。Mixed の場合、N 個のスロット全体でモデルを決定論的にローテーションし(エージェント 1 → opus、エージェント 2 → sonnet、エージェント 3 → haiku、エージェント 4 → opus、…)、割り当てられたモデルをエージェントごとのレポート行に記録します。

1 つのメッセージで N 個すべての呼び出しを行うことで、それらが並列で実行されるようにします。

サブエージェントのプロンプト = ブリーフ + その小さなタスク。ブリーフは exec_mode を通過するので、サブエージェントは Bash が利用可能かどうかを把握できます。

ステップ 6 に進む前に、N 個すべてのエージェントが戻るのを待ちます。 エージェントがバックグラウンドで実行されている場合、完了通知は 1 つずつ届くため、数を数え損ねやすくなります。戻った数と起動した数の簡単なメモリ内集計を維持し、最後のエージェントが報告してきたら、チャットに明示的なマイルストーン行を 1 行出力します: 「N 個すべてのエージェントが戻りました — トレース解析に移ります。」 この行が出力されるまでステップ 6 を開始しないでください。実行の途中でユーザーが「エージェントはまだ実行中ですか?」と尋ねてきた場合は、以前のチャット出力を数え直すのではなく、集計から現在の <returned>/<spawned> の数を答えてください。

オーケストレーターの認証情報を使用したエージェントの主張の検証。 採点の前に、ステップ 2.5 で製品固有の認証情報が保持されていた場合、オーケストレーターはそれらを使用して、サブエージェントが行った主張をスポットチェックできます(例: curl -H "X-BB-API-Key: $BROWSERBASE_API_KEY" https://api.browserbase.com/v1/sessions/<id> でセッション ID を確認する)。解決されなかった ID は、エージェントがハルシネーションを起こした可能性がある証拠として扱ってください。認証情報ヘッダーをレポートに含めないでください — 検証結果(解決済み / 未解決)のみを含めます。

ステップ 6 — 構造化トレースを解析しつつ、全文の散文も保持する

各サブエージェントは 1 つの応答で 2 つのものを返します:

1. 最後にフェンスで囲まれた JSON トレース(構造化された自己申告)。
2. その前のすべての散文 — 推論、ツール出力、そしてエージェントが実際に行ったこと。

両方を保持してください。 JSON を抽出した後に散文を捨てないでください。散文は、JSON の自己申告が見逃すものを捉える場所です。

JSON の抽出には次を使用します: /```json\s*(\{[\s\S]*?\})\s*```\s*$/。不正な形式または欠落しているものは、raw_tail を付けて errored としてマークします。50% 超がエラーの場合は、警告して再試行を提案します。

JSON から主要な数値を計算します:

• オンボーディング成功率 = onboarding_status = "completed" のエージェントの割合。
• ドキュメントの約束一致率 = docs_promise_met = true のエージェントの割合。

ステップ 6.25 — WebFetch ごとに URL の出所を注記する（トレース内にインライン表示）

サブエージェントには検索機能がありません。そのため、学習データの事前知識から URL を推測します。レポートでは、WebFetch 呼び出しごとに URL の出所を示してください。トレース内のツール入力ブロックのすぐ下に、小さく控えめな行として表示します。これをレポートの先頭に一般的な注記として置いてはいけません。読者が特定の呼び出しと照らし合わせられるインライン表示でのみ役立ちます。

各 WebFetch URL を以下の 4 つの出所カテゴリのいずれかに分類し、対応するラベルと色で表示します。

• TRAINING PRIOR（紫）— URL は学習データからの推測です（製品名と、/introduction、/quickstart、/sdk/{lang} などの一般的なドキュメントサイトの慣習に基づくもの）。最初の 1～2 回の WebFetch 呼び出しでよく見られます。
• FROM LLMS.TXT（青）— URL は、同じトレース内で以前に取得した llms.txt の出力に記載されています。
• FROM PREV PAGE（緑）— URL は、同じトレース内の以前の WebFetch または Bash ツール呼び出しの出力に記載されています。
• GUESS · 404（琥珀色）— URL を推測したものの 404 になりました。ドキュメント品質の評価において最も注目すべきカテゴリです（慣習上は存在するはずの URL が存在しません）。

分類のヒューリスティック：

1. 同じトレース内で、それ以前に成功した llms.txt の WebFetch があり、その出力にこの URL が記載されている場合 → FROM LLMS.TXT
2. それ以外で、同じトレース内のそれ以前の WebFetch／Bash 出力に、この正確な URL が記載されている場合 → FROM PREV PAGE
3. それ以外で、後続の tool_result に error: true と 404 の内容が含まれている場合 → GUESS · 404
4. それ以外 → TRAINING PRIOR

スコアの解釈：

• 成功した TRAINING PRIOR が多数ある = 製品が学習データによく含まれている（先行優位）。
• GUESS · 404 が多数ある = URL の体系が一般的な慣習から逸脱している（ドキュメントの見つけやすさに関する実質的な指摘）。
• GUESS · 404 の後に FROM LLMS.TXT が頻繁に現れる = llms.txt がドキュメントの見つけやすさを支えています。評価結果で明示的に評価してください。

ステップ 6.5 — エージェント間のナラティブレビュー（重要）

スコア付けの前に、すべてのエージェントの全文を読み直してください。JSON トレースはエージェントの自己申告です。誤ったパッケージ名を幻覚したエージェントは、その誤りを自身のトレースでも正しく説明してしまいます。真実はツールの出力とナラティブにあります。

N 件のトランスクリプト全体を確認し、以下のパターンを探してください。

1. 収束する誤り。 複数のエージェントが同じ誤った方法を試しましたか？ 誤った npm パッケージ名（例：exa と exa-js）、誤ったエンドポイント、誤った環境変数、誤った import などです。3/3 のエージェントが誤ったパッケージを使っていた場合、各エージェントがタスクを「完了」していても、それはドキュメント品質の重大な問題です。エージェントが同じ誤答を偶然に作り出すことはありません。学習データ由来の誤った事前知識が共有されているということは、ドキュメントがモデルの誤った事前知識を覆せていないということです。

2. 幻覚された成果物。 各エージェントの primary_outcome_achieved の主張を、実際のツール出力と照らし合わせてください。「タイトルを出力した」と主張しているのに、Bash 出力にタイトルを取得するツール呼び出しがない場合、作り話をしています。ドキュメントが不明瞭で、エージェントが内容を読む代わりにパターンマッチングした可能性があります。

3. 一貫しない結果。 3 人のエージェントがそれぞれ異なる「成功」の最終状態を説明している場合、ドキュメントでは成功が明確に定義されていません。

4. 表に出ない回避策。 人間ならそのままコピー＆ペーストするところを、エージェントがバグを修正していませんか（await の不足、環境変数名の誤り、文書化されていない必須パラメーターなど）。これらはナラティブでしか捉えられない、見えにくい DX 上の負担なので、指摘してください。

5. ツール出力とナラティブの矛盾。 エージェントが「動作した」と言っていても、Bash 呼び出しの stderr にはそうでない内容があり、エージェントが気づいていないことがあります。ナラティブ内のツール出力を検索し、error、404、401、deprecated、warning を確認してください。

3～5 文のナラティブレビューの要約を作成し、最終レポートで目立つように記載してください。監査全体で最も価値の高い指摘が見つかることもよくあります。

ステップ 7 — Arena の 5 つの評価軸を採点する

評価基準の詳細は references/evaluation-rubric.md を確認してください。集約したエビデンスに基づき、0〜100 点で採点します。

オンボーディング成功率は、最優先の妥当性チェック項目です。 正確な上限の段階は references/evaluation-rubric.md § 0 を参照してください。完了率が 50% 未満の場合、ほかのエビデンスにかかわらず、すべての評価軸の上限は 55 点です。

• セットアップの手間（25%） — 認証情報の入力要求、認証の再試行、インストールエラー。「セットアップ」フェーズでの失敗は大きく減点します。
• 速度（20%） — 合計実時間、動作するコードが初めて得られるまでの時間。
• 効率性（20%） — completed_subtasks / tool_calls の合計数の比率、無駄な呼び出し。
• エラーからの回復力（15%） — エラーによってオンボーディングの完了が妨げられたか、エージェントが回避策を見つけたか。
• ドキュメントの品質（20%） — ドキュメントにエージェントが必要とする情報が記載されていたか。

加重合計 → レターグレード（90 点以上は A、75 点以上は B、60 点以上は C、45 点以上は D、それ未満は F）。

ステップ 8 — 調査結果をまとめる

以下を作成します。

• エグゼクティブサマリー — 2〜3 文。最初にグレードと最大の障害要因を示します。
• うまくいった点 — 3〜5 個の箇条書き。
• うまくいかなかった点 — 3〜5 個の箇条書き。
• よく見られた摩擦パターン — 2 人以上のエージェントが遭遇した問題（優先度の高い改善点）。
• セッションのタイムライン — エージェント全体のフェーズ（調査、セットアップ、実行、検証）と、おおよその所要時間。
• ツール呼び出しの内訳 — ツール種別ごとの全エージェントの合計。
• 推奨する修正 — 優先順位を付け、それぞれに該当するドキュメントのセクションまたは SDK メソッドと、具体的な書き換え案を示します。

ステップ 9 — HTML レポートを生成する

assets/report-template.html を読み込み、プレースホルダーに値を入力します。

{{TITLE}}、{{TARGET_REF}}、{{META}}、{{GRADE_LETTER}}、{{GRADE_CLASS}}、{{OVERALL_SCORE}}、{{AGENT_COUNT}}、{{COMPLETED_COUNT}}、{{PARTIAL_COUNT}}、{{STUCK_COUNT}}、{{BLOCKED_COUNT}}、{{ERRORED_COUNT}}、{{NARRATIVE_REVIEW_SECTION}}（以下の形式を参照）、{{EXEC_SUMMARY}}、{{WENT_WELL_ITEMS}}、{{DIDNT_GO_WELL_ITEMS}}、{{TIMELINE_SECTION}}、{{TOOL_BREAKDOWN_SECTION}}、{{METRICS_GRID}}、{{PATTERNS_SECTION}}、{{FIXES_LIST}}、{{AGENT_RESULTS_TABLE}}（一覧用のサマリーテーブル。以下の形式を参照）、{{AGENT_TRACES_SECTION}}（エージェントごとの折りたたみ可能な詳細トレースカード。以下の形式を参照）。

ステータスカウンターの対応関係。 5 つのステータスカウンターは、エージェントを漏れなく重複なく分類します。各エージェントは、{{COMPLETED_COUNT}}（onboarding_status=completed）、{{PARTIAL_COUNT}}（partial）、{{STUCK_COUNT}}（stuck）、{{BLOCKED_COUNT}}（blocked-on-credentials）、{{ERRORED_COUNT}}（パーサーで失敗したトレース）のいずれか 1 つだけに含めます。5 つの小計の合計は {{AGENT_COUNT}} と一致する必要があります。

生成するレポート内のセクション順序（テンプレートで定められているため、並べ替えないでください）：

1. スコアカード + エージェントステータスの統計グリッド
2. ナラティブレビュー（{{NARRATIVE_REVIEW_SECTION}}）
3. エグゼクティブサマリー
4. 推奨する修正
5. エージェントの評価（うまくいった点／うまくいかなかった点）
6. よく見られた摩擦パターン（{{PATTERNS_SECTION}}）
7. 定量的指標
8. ツール呼び出しの内訳
9. セッションのタイムライン
10. エージェントごとの実行（結果テーブル + トレース）

この順序の理由：データより先に見解を示します。読者が指標やタイムラインを確認する前に、結論（ナラティブレビューとエグゼクティブサマリー）と、実行可能な修正案を把握できるようにします。タイムラインやツール呼び出しの内訳といった参照用のセクションは、全体像を示すためではなく、検証に使えるよう下部に配置します。

{{NARRATIVE_REVIEW_SECTION}} の形式。 <div class="narrative-review"> の中に、<div class="label">Narrative Review</div> と、ステップ 6.5 のエージェント間サマリー（3〜5 文）を含む <div class="body">…</div> を配置します。これは監査で最も価値の高い調査結果です。簡潔にまとめ、最も重要な所見を冒頭に示してください。ステップ 6.5 で特筆すべきエージェント間の所見が得られなかった場合は、次の 1 行を本文に含めてセクションを生成します：No cross-agent patterns of note — agents converged on the docs' intended path with minor individual variation. セクションを省略しないでください。 5 つの次元スコアは引き続き計算されます（これらは総合加重スコアとレターグレードに反映されます）が、次元ごとの内訳セクションはレンダリングしないでください — これは、ナラティブレビューと推奨される修正で既にカバーされている以上の実用的な内容を読者に提供することなく、視覚的な重みを増すだけです。次元スコアリングは内部に留めておいてください。

{{AGENT_RESULTS_TABLE}} の形式。 <table class="agent-results-table"> を各エージェントのカードのすぐ上にレンダリングします。エージェントごとに 1 行で、以下の列を持ちます（この順序で）:

1. # — スロットインデックス（1 始まり）、右揃え、等幅フォント。
2. ペルソナ × 言語 — 例: Standard · TypeScript。エージェントの JSON トレースから値を取得してください。
3. モデル — この列は model = Mixed の場合にのみレンダリングしてください（それ以外の場合は列全体を省略します。単一モデルはヘッダーの {{META}} 行に記載されています）。
4. ステータス — JSON の onboarding_status に対応する <span class="status-pill {{status}}">（completed、partial、stuck、blocked-on-credentials）。errored（パーサーが失敗したトレース）は独自のピルにマッピングしてください。
5. ツール呼び出し — エージェントの tool_calls[] 配列全体の count の合計。右揃え、等幅フォント。
6. 時間 — JSON の wall_time_estimate_sec を 92s の形式でフォーマットします（120 秒以上の場合は 2m 14s）。右揃え、等幅フォント。

根拠: 以下のカードは詳細ですが、それぞれを展開する必要があります。このテーブルはワンスクリーンでの比較を提供し、読者が掘り下げる前に外れ値（3 倍の時間がかかったエージェント、2 倍のツール呼び出しを発火したエージェント）を発見できるようにします。

{{AGENT_TRACES_SECTION}} の形式。 エージェントごとに 1 つの <details class="trace-card">。各カードのサマリー行には、ペルソナ/言語のチップと並んで、使用されたモデル（例: <span class="chip">opus</span>）を含める必要があります。カードを展開すると以下が表示されます:

1. イベントログ（detailed_trace から） — コンパクトな Arena スタイルでレンダリングします: 等幅フォントの行に色分けされた角括弧ラベル、最小限の装飾、ドットやタイムラインなし。各行は 1 行のテキストで、Input/Output ブロックはツール呼び出しの直下にインデントされた <pre> ブロックとして表示されます（常に表示され、クリックで展開するのではありません — ユーザーはフローをスキャンしたいのです）。

   すべてのログの最初のイベントは、そのサブエージェントに送信されたプロンプトで、タイムスタンプ [setup] のゴールドの [PROMPT] ラベルでレンダリングされます。完全なプロンプトは小さなクリックで展開するボタンの背後にあります（ストリーム内で唯一の折りたたみ可能な要素です — プロンプトは長く、ユーザーが常に必要とするわけではありません）。

   視覚的構造:

   [setup]     [PROMPT]       Task prompt sent to subagent   [▸ Show full prompt]
   [+0ms]      [MILESTONE]    agent_started
   [+100ms]    [THOUGHT]      I'll start by discovering the docs.
   [+1.2s]     [TOOL_USE #1]   WebFetch
                 Input: { "url": "...", "prompt": "..." }
   [+3.4s]     [TOOL_RESULT #1]
                 Output: # Example Product ...
   [+4.5s]     [TOOL_USE #2]   Bash
                 Input: { "command": "npm install ...", "description": "..." }
   [+9.2s]     [TOOL_RESULT #2]
                 Output: added 12 packages ...
   [+12s]      [ERROR]         install · PEP 668 blocked · recovered
   [+45s]      [RESULT ✓]      Session created, task done.
   

   CSS 規約（コンパクトな等幅フォント、明るい背景）:

   • コンテナ: .trace-timeline — 明るいグレーの背景（#fafaf9）、全体を通して等幅フォント、0.78rem のフォントサイズ、スクロール可能（最大 640px）
   • 各行: グリッドなし、インラインテキストのみ。[time]（控えめ）+ [LABEL]（色付き、太字）+ 本文コンテンツ
   • タイプごとの角括弧ラベルの色:
     • [PROMPT]: ゴールド
     • [MILESTONE]: ブルー
     • [THOUGHT]: バイオレット（本文テキストもイタリック + 控えめ）
     • [TOOL USE]: オレンジ（#ff6b35 またはレポートが使用するブランドアクセントカラー）
     • [TOOL RESULT]: グリーン（エラーの場合はレッド）
     • [ERROR]: レッド（本文もレッド）
     • [RESULT ✓]: グリーン（本文グリーン、太字）
   • ツール名: オレンジ + セミボールド
   • Input/Output: .trace-io ブロックとしてインラインで表示され、色付きの左ボーダー（input はオレンジ、output はグリーン、エラーはレッド）。<pre> ブロックはツール入力を 完全な JSON として表示します — 決して省略しないでください。特に WebFetch の場合、これは url と prompt 引数の 両方 を表示することを意味します — prompt はエージェントがページのコンテンツを何に蒸留するよう求めたかであり、エージェントの意図を理解するための重要なシグナルです。入力が大きい場合は、関連する文字列内で値（構造ではなく）を … で切り詰めてください。
   • プロンプトブロックは例外です — デフォルトで折りたたまれています（プロンプトは長いため）。そのサマリーは小さな「▸ Show full prompt」ボタンとして表示されます。
   • 決して暗い背景に戻さないでください — レポートの他の部分と衝突します。
   • グリッドなし、ドットなし、縦線なし — テキストフローを維持してください。 メインエージェントは各サブエージェントのプロンプトを保持します。 ステップ 5 でエージェントを生成する際、エージェントのインデックスをキーとしてプロンプト全文をキャッシュし、レポート用に取得できるようにしてください。未来のあなた（レンダリング担当）は、どのエージェントに何が送信されたかを参照する必要があります。

2. エージェントの最終的な散文サマリー — イベントログの下にスクロール可能な二次的なボックスとして保持します（これは自己申告であり、トレースが真実の記録です）。

3. ツール呼び出しサマリーグリッド（名前、回数、目的）— クイックリファレンス

4. エビデンス（セッション ID、stdout など）

5. 摩擦ポイント

6. エラー（ある場合）

7. ポジティブなポイント

イベントログが主役です。これにより、ユーザーは Arena のトレースビューと同じ「エージェントが何を行い、何を考えたかを正確に見られる」体験を得られます。散文サマリーは物語的な要約ですが、トレースが主要な記録です。

エージェントごとの結果テーブルには、model = Mixed の場合に Model 列を含める必要があります。これにより、モデル間の比較が一目でわかります。単一のモデルを使用した場合は、ヘッダーの {{META}} 行で一度言及するだけにしてください。

ユーザー提供のすべての文字列を HTML エスケープしてください。ドキュメントの引用は <code> または <blockquote> に入れます。

すべての URL はクリック可能でなければなりません。 レポートが以下を参照する場合:

• 相対的なドキュメントパス（例: /quickstart）→ <a class="doc-link" href="{TARGET_BASE_URL}{path}" target="_blank" rel="noopener"><code>{path}</code></a> としてラップします。ここで {TARGET_BASE_URL} は監査ターゲットのオリジンです（例: https://docs.example.com）
• セッション/リソース ID（例: f0ec58cc）→ 完全なリソース URL（例: https://app.example.com/sessions/{full-id}）にリンクし、外部リンクを示す ↗ を末尾に付けます
• 散文に現れる完全な URL → すでにリンク可能です。<code> だけでなく <a> でラップされていることを確認してください

これらのリンククラスの CSS:

a.doc-link { text-decoration: none; color: inherit; }
a.doc-link:hover code { background: #fff4ef; border-color: var(--brand); color: var(--brand); }
a.session-link { color: #166534; text-decoration: none; }
a.session-link:hover { text-decoration: underline; }

根拠: ユーザーがクリックして確認できなければ、404 の検出結果は役に立ちません。ユーザーが録画にクリックして移動できなければ、セッション ID は役に立ちません。レポート内のすべての URL らしき文字列は、検証までワンクリックで到達できるべきです。

ステップ 10 — 保存と表示

./agent-experience-<slug>-<timestamp>.html（cwd）に保存します。Slug = ターゲットのベース名を小文字にし、英数字以外を - に置換したもの。Timestamp = YYYYMMDD-HHMMSS。

チャットに出力:

• グレード、総合スコア、最も大きな修正点 1 つ。
• カウントサマリー: N エージェント、M 完了、K スタック。
• ファイルの完全なパス。

macOS で exec_mode が許可している場合は Bash: open <path> で開きます。それ以外の場合はパスを出力するだけにします。

ステップ 11 — ワークスペースのクリーンアップ

exec_mode = "Allow Bash" で、./dx-audit-tmp/（または類似の場所）の下にエージェントごとのサブディレクトリを作成した場合、レポートのレンダリング後にそのツリーを削除します:

rm -rf ./dx-audit-tmp/

根拠: エージェントは node_modules、venv、Go モジュールなどをインストールします。多くの場合、エージェントごとに数十 MB になります。それらを放置すると、ユーザーのリポジトリを汚し、ディスクを無駄にします。

例外: サブエージェントの onboarding_status が stuck である場合、またはそのトレースが errored（JSON パース失敗）とマークされている場合は、そのエージェントのサブディレクトリをそのまま残し、チャットで言及します。ユーザーが失敗状態を調査したいと思うかもしれません。削除するのは、完了したエージェントまたは認証情報でブロックされたエージェントのディレクトリのみにしてください。

exec_mode = "Draft-only" の場合、クリーンアップは不要です（レポート以外にファイルは書き込まれていません）。

参照ファイル

• references/evaluation-rubric.md — 5 次元のスコアリングルーブリック（Arena メソドロジー）。
• references/prompt-variants.md — ペルソナプレフィックスライブラリとコアタスクのヒューリスティクス。
• references/subagent-brief.md — 逐語的なブリーフ + トレース JSON スキーマ。

アセット

• assets/report-template.html — プレースホルダー付きの HTML テンプレート。最終レポートにスタンプされます。

制約事項

• 対象ドキュメントをサブエージェントのプロンプトに貼り付けないでください。それこそがこの仕組みの要点です。
• exec_mode = Draft-only は、サブエージェントへの指示において Bash の実行を無効化しなければなりません。
• ユーザーが明示的に指定していない対象をテストしないでください。
• ユーザー向けの質問には、製品名、URL、企業名を絶対に事前入力しないでください。 環境のシグナル（メールドメイン、git リモート、リポジトリ名、メモリ）は無視してください。まっさらな状態から始めてください。操作者は誰を監査しているかわかりません。
• サブエージェントが認証情報を要求した場合、それはスコア上は摩擦としてカウントされます。自動で提供して「助ける」ことはしないでください。エージェントに壁にぶつからせ、それを記録してください。
• HTML レポート以外は、cwd の外にあるファイルに書き込まないでください。