代理開發者體驗 (Agent DX)
一個以 AI 代理爲開發者的表面層開發者體驗——代理用於建構或行動的 SDK、工具、結構化輸出、錯誤封套或遙測。原始資料位於 skill.json；此檔案僅供執行時期路由之用。
產出： change-plan.md (DO)、audit-report.md 加上發現清單與工作流程狀態 (REVIEW)，或 design-doc.md / refactor-runbook.md / explanation.md (DESIGN)。
核心原則
代理獨自、以機器速度、在沒有任何提示輔助的情況下消費表面層。 因此，任何 SDK、工具、錯誤或跨度（span）的標準在於一個隨機消費者能否解析它、從中恢復，並且不受其傷害：類型化合約優於散文；恢復是設計進去的，而不是寄望於僥倖；信任邊界預設是封閉的。它立於 dx-audit / dx-design 所擁有的 HTTP 客戶端基礎之上，但絕不取代它。
啓動 (Activation)
- 裸調用 (
"use agent-dx","review our MCP tool surface","start")：載入references/intent-router.csv，顯示意圖選單，提供模式選擇。等待。不執行檔案檢查、網路呼叫或寫入。 - 帶有意圖與可推斷表面層的具體調用：跳至步驟 3。
- 模糊範圍：提出一個阻礙性問題，指明候選意圖或表面層；不應先檢查私有系統。
工作流程 (Workflow)
- 選擇意圖。 載入
references/intent-router.csv；比對至do、review或design。模糊→問一次。 - 選擇表面層。 載入
references/intents/<intent>.csv；比對一個或多個sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry——或all（用於 REVIEW 扇形展開）。模糊→透過選單問一次。 - 載入紮根上下文。 僅載入所選列的
playbook及其core_refs。不載入其他 playbook（review/all列不攜帶任何 playbook——每個表面代理會載入自己的；參見步驟 6）。 - 識別目標角色 來自
references/core/personas.md。 - 然後根據專案規模校準（REVIEW / DESIGN），依據
references/calibration.md：低於承重規模時，縮小範圍，將相同機制的間隙合併爲一個系統性發現，並分爲現在與稍後（隨規模成長時）。等級影響發佈，從不影響嚴重性。 - 平行調度鏡頭（預設 REVIEW 且允許時）：爲
all使用一個表面層一個代理；否則使用以下三個鏡頭。若無委派機制則序列回退。 - 應用 playbook。 使用標記爲該意圖的啟發法。對於 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-...）。回報兩個路徑；保持路線圖、問題和非追蹤編輯爲選擇加入。
模式 (Modes)
引導草稿（預設）、自動駕駛、釘問我——參見 references/modes.md。在裸調用時提供；具體調用時預設爲引導草稿。
輸出要求
每個輸出需指明意圖、表面層、角色、應用的 playbook 以及 skill.json 中的紮根來源；REVIEW 模式需爲每個發現添加嚴重性、驗證方式以及專案等級。請列出您刻意不增加的代理可消費性保證（YAGNI），而不僅僅是您已增加的。
子代理調度 (Subagent dispatch)
REVIEW 模式的預設行爲（當允許委派時）；跳過小型或涉密工作。平行產生三個鏡頭——合約與模式（源自程式碼的類型化模式、穩定的錯誤封套、經過驗證的輸出）、代理恢復（停止並驗證、重試型錯誤、語義重試、有界迴圈）、信任與隔離（工具元資料注入、護欄檢查點、憑證牆、內容編輯）——依據 references/subagent-dispatch.md，然後綜合，依嚴重性排序。
參考映射 (Reference map)
references/intent-router.csv+references/intents/<intent>.csv——兩個路由層。references/playbooks/<surface>.md——sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry。references/subagent-dispatch.md——三個鏡頭的提示與綜合。references/core/{severity-rubric,score-rubric,personas,glossary}.md——分級、受眾、術語。references/{calibration,trackable-findings,modes}.md——共享（符號連結）。templates/*.md——變更計畫、審計報告、設計文件、重構操作手冊、解釋，以及共享的追蹤成品。evals/、skill.json——門控與原始資料。