## 🛠️ 專業框架與方法論

### DX 成熟度模型（AI-DXMM v1）

| 等級 | 特徵 | 典型 TTFC |
|------|------|-----------|
| L0 Ad-hoc | 無統一文件、僅 internal demo | > 2 小時 |
| L1 Functional | 有基本 API docs + API key | 30-120 分鐘 |
| L2 Guided | Quickstart + 官方 SDK + 錯誤碼文件 | 10-30 分鐘 |
| L3 Productized | Portal + Playground + 狀態頁 + changelog | 5-15 分鐘 |
| L4 Delightful | 互動教學 + CLI + IDE 外掛 + 社群生態 | < 5 分鐘 |

**診斷方式**：請使用者描述現有資產，對照上表評級並指出晉級至下一級的最小投資路徑。

### API 設計檢核表（AI-Native APIs）

- [ ] **Streaming 一等公民**：SSE/WebSocket 文件與 SDK 範例對等於 sync 端點
- [ ] **Token/Usage 透明**：回應 header 或 metadata 暴露用量資訊
- [ ] **Structured Output**：JSON mode / schema validation 有明確 contract
- [ ] **Idempotency**：非安全重試場景支援 idempotency key
- [ ] **Error Taxonomy**：機器可讀 error code + 人類可讀 message + 修復建議連結
- [ ] **Rate Limit Headers**：`X-RateLimit-*` 或等價機制
- [ ] **Pagination 一致性**：cursor-based 優先於 offset（大量生成內容場景）
- [ ] **Webhook 簽章**：HMAC 驗證範例與 replay 防護
- [ ] **Versioning**：URL path 或 header 策略明文化

### 文件架構框架：Diátaxis for AI

```
docs/
├── tutorials/          # 學習導向：端到端情境
├── how-to/             # 任務導向：解決特定問題
├── reference/          # 資訊導向：API/SDK 完整規格
└── explanation/        # 理解導向：概念、架構、限制說明
```

**AI 產品加成**：
- `recipes/` — 可複製的整合模式（RAG、Agent、Tool Use）
- `migrations/` — 版本升級與 breaking change
- `limits/` — 模型能力邊界、latency、cost 估算

### SDK 策略矩陣

| 因素 | Hand-written SDK | Generated (OpenAPI) | Hybrid |
|------|------------------|---------------------|--------|
| API 穩定度低 | ❌ | ✅ | ✅ |
| 需要慣用語 API | ✅ | ❌ | ✅ |
| 多語言覆蓋 | 慢 | 快 | 推薦 |
| 長期維護成本 | 高 | 低 | 中 |

### 開發者旅程地圖（AI Platform）

```
1. Discover     → SEO docs、比較頁、Sandbox 免 API key 試用
2. Evaluate     → 免費額度、latency benchmark、eval 透明度
3. Integrate    → Quickstart、framework 整合（LangChain/LlamaIndex/Vercel AI SDK）
4. Scale        → 批量 API、企業 SSO、SLA、專屬支援通道
5. Advocate     → 案例研究、SDK 貢獻、Plugin marketplace
```

### KPI 儀表板建議

**北極星指標**：Time-to-First-Successful-Integration (TTFSI)

**支援指標**：
- Docs → Signup 轉換率
- Quickstart 完成率（telemetry）
- API 4xx/5xx 比率（按 error code 分桶）
- Median time from signup to first paid usage
- GitHub Issues 解決時間 / 重複問題率
- Developer NPS（季度調查）

### 工具鏈評估維度

- **CLI**：`auth login`、`init`、`deploy`、`logs tail` 是否直覺
- **Playground**：能否匯出為 code snippet / share link
- **Local Dev**：mock server、record/replay、offline token
- **CI 整合**：GitHub Action 官方模板、secret 管理指引

### 常見反模式（Anti-Patterns）

1. **Documentation Debt Spiral**：只寫 reference 不寫 tutorial
2. **SDK Lag**：API 已 GA 三個月 SDK 仍 beta
3. **Mystery Errors**：`{ "error": "something went wrong" }`
4. **Playground Toy**：與 production API 行為不一致
5. **Breaking Change Friday**：週五發布無 migration guide 的變更
6. **Support as Documentation**：重複回答的問題未沉澱為 docs

### 參考資源（原則萃取，非 endorsement）

- Stripe API Design / Twilio Docs IA / OpenAI Platform Docs
- Google Cloud API Design Guide / Microsoft REST API Guidelines
- Diátaxis Framework / Jobs-to-be-Done for Developers
- DX Metrics（Developer Experience Metrics research）