Agent DX は何をしますか？
AIエージェントが開発者であるサーフェス（SDK、ツール、構造化出力、エラーエンベロープ、テレメトリー）の開発者体験。エージェントが構築するため、または行動するために消費するものです。原本は skill.json にあります。このファイルはランタイムルーティングのみを扱います。
生成物: change-plan.md（DO）、audit-report.md と発見台帳＋ワークフロー状態（REVIEW、追跡あり）、または design-doc.md / refactor-runbook.md / explanation.md（DESIGN）。
基本原則
エージェントは、単独で、機械的な速度で、ツールチップに頼らずにサーフェスを消費します。 したがって、SDK、ツール、エラー、スパンの基準は、確率的な消費者がそれを解析でき、そこから回復でき、害を受けないかどうかです。すなわち、散文よりも型付きコントラクト、期待ではなく設計された回復、デフォルトで閉じた信頼境界です。これは、dx-audit / dx-design が所有するHTTPクライアントフロアの上に位置し、決してそれを置き換えるものではありません。
アクティベーション
- ベア呼び出し（
"use agent-dx"、"start"）: コンパクトなメニューを表示します。モード選択（ガイド付き / オートパイロット / グリルミー?）とルーターからの番号付きインテント。待機します。ファイル検査、ネットワーク呼び出し、書き込みは行いません。 - 具体的な呼び出し（インテントとサーフェスが推測可能）: ステップ3にスキップします。
- 曖昧な呼び出し: 1つ質問します。例：「SDK、ツールスキーマ、構造化出力エンベロープ、テレメトリーサーフェスのいずれを監査しますか？」または「これはコントラクト/リカバリーレビューですか、それとも信頼境界監査ですか？」
ワークフロー
- インテントを選択する。
references/intent-router.csvを読み込み、do、review、designにマッチさせる。 曖昧な場合 → 1回質問する。 - サーフェスを選択する。
references/intents/<intent>.csvを読み込み、sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetryの1つ以上、またはREVIEWファンアウトの場合はallにマッチさせる。 曖昧な場合 → メニューで1回質問する。 - グラウンディングコンテキストを読み込む。 選択した行の
playbookとそのcore_refsのみを読み込む。他のプレイブックは読み込まない（review/all行にはプレイブックはありません。各サーフェスエージェントが独自のものを読み込みます。ステップ6を参照）。 - ターゲットペルソナを特定する。
references/core/personas.mdから。 - 次にプロジェクト規模に合わせてキャリブレーションする（REVIEW / DESIGN）
references/calibration.mdに従う。ロードベアリング未満の場合は、スコープを狭め、同じメカニズムのギャップを1つの体系的な発見にまとめ、「今すぐ」と「後で（成長に応じて）」を分割する。ティアは重要度ではなく出力に影響を与える。 - レンズを並行してディスパッチする（許可されている場合のREVIEWのデフォルト）:
allの場合はサーフェスごとに1エージェント、それ以外は以下の3つのレンズ。委任プリミティブがない場合は順次フォールバックする。 - プレイブックを適用する。 インテントにタグ付けされたヒューリスティックを使用する。REVIEWの場合は、各サーフェスを0〜10でスコアリングする（
references/core/score-rubric.md）。レンズの発見を統合し、意見の相違は未解決の質問として保持する。重要度と安定したAGENT-DX-<surface>-NNNID（references/core/severity-rubric.md）を適用する:AGENT-DX-SDK、AGENT-DX-TOOL、AGENT-DX-OUT、AGENT-DX-ERR、AGENT-DX-TEL。 - 出力する。 DO →
templates/change-plan.md。REVIEW →templates/audit-report.md。DESIGN →templates/design-doc.md（形状）、templates/refactor-runbook.md（ハードニングのシーケンス）、またはtemplates/explanation.md（原則の説明）。 - トラッキング状態を作成、再開、またはクローズする（REVIEW）。7件以上の発見、重要度3〜4、または保存/追跡/クローズアウトリクエストがある監査の場合、
references/trackable-findings.mdを読み込む。リクエストが既存の台帳、ワークフロー状態、PR、またはAGENT-DX-*IDを指定している場合は、まず保存された状態を読み取り、各検証ルールに合格した後にのみステータスを更新する。それ以外の場合は、docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.mdに台帳を、docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.jsonにワークフロー状態を書き込む（docs/audits/に書き込めない場合はaudit-artifacts/agent-dx-...にフォールバックする）。両方のパスを報告する。ロードマップ、イシュー、非トラッキング編集はオプトインに保つ。
方向性が間違っている場合？ ユーザーがこれが意図したものではないと言った場合、ステップ1（インテントの選択）に戻る — 間違った方向性にパッチを当てない。修正した理解を言い直し、再計画する。
モード
ガイド付きドラフト（デフォルト）、オートパイロット、グリルミー — references/modes.md を参照。ベア呼び出し時に提供する。具体的な呼び出しではガイド付きドラフトをデフォルトにする。
出力要件
すべての出力は、インテント、サーフェス、ペルソナ、適用されたプレイブック、skill.json からのグラウンディングソースを明記する。REVIEWでは、発見ごとの重要度＋検証とプロジェクトティアを追加する。追加している保証だけでなく、意図的に追加していない（YAGNI）エージェント消費可能性保証の名前も挙げる。
サブエージェントディスパッチ
委任が許可されている場合のREVIEWのデフォルト。小規模または機密性の高い作業はスキップする。3つのレンズを並行して起動する — コントラクトとスキーマ（コードからの型付きスキーマ、安定したエラーエンベロープ、検証済み出力）、エージェントリカバリー（停止＋検証、リトライ形状のエラー、セマンティックリトライ、有界ループ）、信頼と分離（ツールメタデータ注入、ガードレールチェックポイント、クレデンシャルウォール、コンテンツ編集） — references/subagent-dispatch.md に従い、その後統合し、重要度順に並べる。
参照マップ
references/intent-router.csv+references/intents/<intent>.csv— 2つのルーティング層。references/playbooks/<surface>.md— sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry。references/subagent-dispatch.md— 3レンズのプロンプトと統合。references/core/*.md— 重要度、スコア、ペルソナ、用語集。references/{calibration,trackable-findings,modes}.md— 共有（シンボリックリンク）。templates/*.md— change-plan、audit-report、design-doc、refactor-runbook、explanation、および共有トラッキングアーティファクト。evals/、skill.json— ゲートと原本。