AI Team 已驗證
此流程已在多個專案中實踐，包含 Apidog 整合與 OpenAPI 規格產生。
API 設計流程
API 設計遵循 API-First 方法，規格先於實作，AI 代理從高階需求結合設計原則產生 API 規格。
API-First 原則
API-First 設計流程
流程步驟
- 高階規格 - 業務需求和使用者故事定義 API 需要達成的目標
- API 設計原則 - 組織指南確保跨 API 的一致性
- AI 代理產生 - 代理根據輸入草擬 OpenAPI 規格
- 人工審查 - 工程師審查正確性、安全性和對齊
- Mock 伺服器 - 產生 mock 伺服器以便早期消費者驗證
- 消費者驗證 - 消費者對 mock 測試，提供回饋
- 實作 - 後端依據核准的規格實作
- 契約測試 - 自動化測試驗證實作符合規格
- 文件 - 為消費者發布 API 文件
API 規格平台
POC 狀態
此為概念驗證實作，正式採用前需另外投入資源進行調研或開發。
代理在 API 設計中的角色
| 階段 | 代理貢獻 |
|---|---|
| 規格草擬 | 從高階規格 + API 原則產生 OpenAPI |
| 一致性檢查 | 對照組織 API 指南驗證 |
| Mock 產生 | 從 OpenAPI 規格建立 mock 伺服器 |
| 測試產生 | 從情境產生契約測試 |
| 整合分析 | 從文件識別平台約束 |
| 適配器產生 | 從 integration.md 產生適配器介面 |
API 設計原則 (ADP)
組織應維護一份 API 設計原則 (API Design Principles, ADP) 文件，將 API 標準編纂成文。此文件作為 AI 代理讀取高階規格產生 API 規格時的指導性原則，避免 API 規格不對齊等污染脈絡問題。
參考： 組織 ADP 提案可參閱 API Design Principle。
ADP 文件結構
markdown
# API 設計原則 (ADP)
## 命名慣例
- 資源命名：複數名詞、kebab-case
- 查詢參數：camelCase
- Header：X-Custom-Header 格式
## 版本策略
- URL 路徑版本：/api/v1/resources
- 破壞性變更定義
- 棄用時程（最少 6 個月）
## 認證與授權
- 標準認證機制（OAuth 2.0、API keys）
- Token 格式和生命週期
- Scope 命名慣例
## 錯誤回應格式
- 標準錯誤 Schema
- 錯誤碼分類
- 本地化需求
## 分頁與過濾
- Cursor vs Offset 分頁
- 過濾參數模式
- 排序參數格式
## 速率限制
- 速率限制 Header
- 配額政策
- Retry-After 行為AI 代理如何使用 ADP
ADP 文件應該：
- 在 CLAUDE.md 中引用 - 讓 AI 代理總是考慮它
- 版本控制 - 變更被追蹤和審查
- 透過 Linting 強制執行 - 對 OpenAPI 規格自動驗證
核心原則
- API-First - 規格先於實作；AI 產生草稿，人類核准
- 消費者驅動 - 從消費者角度設計，與消費者驗證
- 向後相容 - 破壞性變更需要棄用流程
- 一致慣例 - 遵循組織 ADP 文件
- 可測試契約 - 每個端點都有從規格衍生的契約測試
- 平台透明 - 在 integration.md 記錄外部平台約束
反模式
| 反模式 | 問題 | 正確方法 |
|---|---|---|
| 實作優先 | API 設計受現有程式碼約束 | 規格定義契約，實作跟隨 |
| 未記錄的破壞性變更 | 消費者靜默破壞 | 正式棄用並提供版本遷移 |
| 不一致的慣例 | 難以學習，整合易錯 | 遵循組織 API 樣式指南 |
| 缺少錯誤規格 | 消費者無法正確處理失敗 | 在規格中定義所有錯誤回應 |
| 無消費者驗證 | API 不符合實際需求 | 實作前用 mock 伺服器測試 |
相關： 工作流程框架概覽