# 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"`、`"review our MCP tool surface"`、`"start"`）：`references/intent-router.csv` を読み込み、インテントメニューを表示し、モードを提示します。待機します。ファイルの検査、ネットワーク呼び出し、書き込みは行いません。
- **具体的な起動**（インテントとサーフェスが推論可能）：ステップ3にスキップします。
- **スコープがあいまいな場合**：候補となるインテントまたはサーフェスを指定する1つのブロッカー質問をします。プライベートシステムを最初に検査しないでください。
## ワークフロー
1. **インテントを選ぶ。** `references/intent-router.csv` を読み込み、`do`、`review`、`design` のいずれかにマッチさせます。あいまいな場合は一度だけ質問します。
2. **サーフェスを選ぶ。** `references/intents/<intent>.csv` を読み込み、`sdk-design`、`tools-and-mcp`、`structured-output`、`errors-and-retry`、`sdk-telemetry` のいずれか、またはREVIEWのファンアウト用に `all` にマッチさせます。あいまいな場合はメニューとともに一度だけ質問します。
3. **根拠のあるコンテキストを読み込む。** 選択した行の `playbook` とその `core_refs` のみを読み込みます。他のplaybookは読み込みません（`review`/`all` 行は何も持たず、各サーフェスエージェントが自身のものを読み込みます。ステップ6を参照）。
4. **対象ペルソナを特定する。** `references/core/personas.md` から。
5. **次にプロジェクト規模に合わせて調整する（REVIEW / DESIGN）。** `references/calibration.md` に従い：負荷に耐える規模未満の場合はスコープを狭め、同じメカニズムのギャップを1つのシステム的発見事項にまとめ、「今」と「後で（規模が拡大したとき）」を分割します。階層は重大度ではなく出力を決定します。
6. **レンズを並行してディスパッチする（REVIEWのデフォルト、許可されている場合）。** `all` の場合はサーフェスごとに1エージェント。それ以外は以下の3つのレンズ。委任プリミティブがない場合は順次フォールバック。
7. **プレイブックを適用する。** インテントにタグ付けされたヒューリスティックを使用します。REVIEWの場合は、各サーフェスを0～10でスコアリングし（`references/core/score-rubric.md`）、レンズの所見を統合し、不一致は未解決の質問として保持します。重大度と安定した `AGENT-DX-<surface>-NNN` 形式のIDを適用します（`references/core/severity-rubric.md`）：`AGENT-DX-SDK`、`AGENT-DX-TOOL`、`AGENT-DX-OUT`、`AGENT-DX-ERR`、`AGENT-DX-TEL`。
8. **出力する。** DO → `templates/change-plan.md`。REVIEW → `templates/audit-report.md`。DESIGN → `templates/design-doc.md`（形状）、`templates/refactor-runbook.md`（堅牢化の手順）、または `templates/explanation.md`（原則の説明）。
9. **追跡状態を作成、再開、またはクローズする（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-...` にフォールバック）。両方のパスを報告し、ロードマップ、課題、追跡外の編集はオプトインとします。
## モード
ガイド付きドラフト（デフォルト）、オートパイロット、私を試す — `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/{severity-rubric,score-rubric,personas,glossary}.md` — 尺度、対象読者、用語。
- `references/{calibration,trackable-findings,modes}.md` — 共有（シンボリックリンク）。
- `templates/*.md` — change-plan、audit-report、design-doc、refactor-runbook、explanation、および共有追跡アーティファクト。
- `evals/`、`skill.json` — ゲートとプロデュース元。