【實戰指南】如何為 AI 代理準備資料？Agent Spec 設計指南 — 從 SDD 到代理規格書的完整轉化

在上兩篇文章中，我們解析了《2026 Agentic Coding Trends Report》的 8 大趨勢，也實際跑了一次雙代理流水線。但實戰中最常被問到的問題是：「我到底要準備什麼資料給 AI 代理？」

答案不是傳統的 SDD（Software Design Document）。50 頁的 Word 文件會讓代理 timeout。你需要的是一種為 AI 代理設計的輕量規格書——Agent Spec。

一、為什麼 SDD 不適合代理？

	傳統 SDD（給人看的）	Agent Spec（給 AI 看的）
長度	50+ 頁	200 行以內
包含	背景、歷史、會議記錄、UML 圖	只有「做什麼」「不做什麼」「怎樣算完成」
表達方式	文字描述 + 圖表	程式碼範例 + 簽名契約
閱讀方式	多人在不同時間反覆閱讀	一個代理在一次 context 中完整消化
設計原則	越詳細越好	越精準越好（長度是敵人）

核心差異：SDD 追求完整性，Agent Spec 追求精準性。代理不需要知道「為什麼要做這個功能」的三頁背景故事，它需要知道「輸入什麼、輸出什麼、邊界怎麼處理」。

二、Agent Spec 的五個區塊

一份文件，五個區塊，控制在 200 行以內。以下用「訂單處理功能」為例完整示範：

區塊一：WHAT — 做什麼（必要）

這是最核心的區塊。不要寫散文，直接給輸入輸出契約：

## 功能規格

### 輸入輸出契約（最重要的部分）
- 函數簽名：`def process_order(order: Order) -> Receipt`
- 輸入範例：
  {"item_id": "A001", "qty": 3, "user_id": "U100"}
- 輸出範例：
  {"receipt_id": "R001", "total": 150.0, "status": "confirmed"}
- 錯誤回傳：
  raises InsufficientStockError when qty > available
  raises DuplicateOrderError when same order within 1 second

### 行為規則
1. 庫存不足時拒絕訂單，不要部分出貨
2. 同一用戶同一秒內的重複訂單要去重
3. 金額計算精度到小數點後 2 位

為什麼這樣寫有效？因為代理最擅長的是「根據契約實作」。函數簽名 + 輸入輸出範例 + 邊界條件 = 代理需要的全部資訊。業務背景、產品需求文件、PM 的原始 ticket——這些人類需要，代理不需要。

區塊二：HOW — 技術約束（必要）

告訴代理已經有什麼可以直接用。這是最容易被忽略、但最能提升品質的資訊：

## 技術約束

### 必須使用
- 語言：Python 3.11
- 框架：FastAPI
- 資料庫：已有的 PostgreSQL，用 SQLAlchemy ORM
- 現有模組：from app.models import Order, Product（已存在，直接用）

### 現有介面（可以直接呼叫的）
- db.session.get(Product, product_id) -> 查商品
- db.session.add(receipt) -> 寫入收據
- redis_client.get(f"order:{user_id}:{hash}") -> 去重檢查
- from app.services.product_service import get_price -> 取得商品價格

### 專案結構（讓代理知道檔案放哪裡）
src/
  models/order.py       -- 資料模型（已存在）
  services/             -- 業務邏輯放這裡
  routes/orders.py      -- API 路由（要在這裡加 endpoint）

為什麼這麼重要？沒有這個區塊，代理會自己發明資料庫連接方式、自己建立 model class、自己設計專案結構——然後跟你的現有程式碼完全不相容。告訴它「已經有什麼」，它就會「用已經有的」。

區塊三：DON’T — 禁止事項（必要）

從我們的雙代理實驗中學到的最重要教訓：禁止比允許更重要。AI 的創造空間是無限的，你無法列舉所有「應該做」的事，但你可以明確劃定「絕對不能做」的紅線。

## 禁止

### 絕對不可（違反 = 程式碼作廢）
- 不可直接寫 SQL（必須用 ORM）
- 不可在 API handler 裡寫業務邏輯（必須放 service 層）
- 不可 catch 所有 Exception（必須指定具體類型）
- 不可新增資料表（只能用現有的 schema）
- 不可使用 global 變數

### 不要（違反 = 需要修改）
- 不要新增依賴套件
- 不要修改現有的 model 定義
- 不要寫 print debug（用 logging）
- 不要硬編碼設定值（用 config）

分層禁止的好處：「絕對不可」是紅線——審查代理看到這些違規應該直接判 FAIL。「不要」是黃線——可以在審查中要求修改。這種分層讓自動化審查變得可行。

區塊四：DONE — 怎樣算完成（必要）

這個區塊定義了機器可以驗證的完成標準。如果完成標準只有人能判斷（「程式碼要寫得漂亮」），那自動化流水線永遠跑不完。

## 完成標準

### 代理自檢清單
- [ ] 所有公開函數都有 type hint 和 docstring
- [ ] 沒有用到禁止清單中的任何項目
- [ ] 能處理：正常訂單、庫存不足、重複訂單、無效商品 ID

### 測試要求
- [ ] pytest 測試覆蓋率 > 85%
- [ ] 包含正常路徑、邊界條件、錯誤處理測試
- [ ] 併發測試（至少 5 個 thread 同時下單）

### 驗證指令（代理或流水線可以直接執行的）
  pytest tests/ -v --tb=short
  flake8 src/ --max-line-length=120
  mypy src/ --strict

關鍵：給出可以直接跑的驗證指令。這讓流水線可以自動驗證——不需要人來判斷「完成了沒有」，直接跑指令看 return code。

區塊五：CONTEXT — 最小必要上下文（選用）

只有當代理需要理解「這個功能在系統中的位置」時才加這個區塊。注意：只放代理需要知道的，不放背景故事。

## 上下文

### 相關檔案（給路徑，不要描述內容）
- 資料模型：src/models/order.py
- 現有服務層：src/services/product_service.py（參考這個的寫法）
- API 路由：src/routes/orders.py（要在這裡加 endpoint）

### 資料流
用戶 -> POST /orders -> OrderService.process() -> DB write -> return Receipt

### 注意事項
- 這個功能是 v2 重構，舊的 process_order_legacy() 已廢棄但還在程式碼中
- 資料庫連線用 app.db.get_session()，不要自己建連線

三、不同任務複雜度對應的準備量

任務複雜度	範例	需要的區塊	Spec 行數	代理配置
簡單	加一個 API endpoint	WHAT + DON’T	~50 行	單代理
中等	實作一個演算法模組	WHAT + HOW + DON’T + DONE	~100 行	雙代理（寫+審）
複雜	跨模組的功能開發	全部五個區塊	~150 行	三代理（寫+審+測）
大型	多服務協作的功能	拆成多份子任務 Spec	每份 ~80 行	Agent Team + Orchestrator

大型任務的關鍵：不是寫一份更大的 Spec，而是拆成多份小 Spec。

四、Agent Team 的致命問題：為什麼會卡死？

在我們的雙代理實驗中，跑了 5 次才成功。多代理場景下問題更嚴重。以下是常見的卡死模式和解法：

卡死模式 1：連鎖 Timeout

# 串聯 3 個代理，每個 300s timeout = 最壞 900s
Orchestrator -> Agent A (300s) -> Agent B (300s) -> Agent C (300s)

# 如果 Agent A timeout 了，B 和 C 都在空等

解法：每個代理獨立 timeout + 能平行的就平行

# 架構代理串行（後面都依賴它）
design = call_agent("architect", spec, timeout=120)

# 實作和測試平行（互不依賴）
with ThreadPoolExecutor(max_workers=2) as pool:
    impl = pool.submit(call_agent, "implementer", design, timeout=120)
    test = pool.submit(call_agent, "tester", design, timeout=120)

卡死模式 2：髒輸出污染下游

# Agent A 輸出中文說明而非程式碼
# Agent B 拿到垃圾 -> 產出垃圾 -> Agent C 也跟著壞
Agent A: "我建議三種方案..." -> Agent B: "這不是程式碼？" -> Agent C: timeout

解法：每個代理之間加「驗證閘門」

# 不要直接傳遞
output_b = call_agent(agent_b, output_a)  # 危險！

# 加驗證閘門
code = extract_code(output_a)
if not code:
    raise PipelineError("Agent A did not produce valid code")
if not code.startswith(("import ", "from ", "class ", "def ")):
    raise PipelineError("Agent A output is not valid Python")
output_b = call_agent(agent_b, code)  # 只傳驗證過的內容

卡死模式 3：Spec 太長導致代理失焦

# 500 行的大 Spec -> 代理只看前 100 行，後面的禁止事項被忽略
call_agent(agent, massive_500_line_spec)  # -> 產出違規程式碼

解法：拆分子任務，每份 Spec 控制在 50-100 行

# 拆成多份獨立的小 Spec
subtasks = [
    {"agent": "backend",  "spec": order_service_spec},    # 50 行
    {"agent": "backend",  "spec": order_endpoint_spec},    # 30 行
    {"agent": "tester",   "spec": order_test_spec},        # 40 行
]

# 逐個執行，每個都有獨立的驗證
for task in subtasks:
    output = call_agent(task["agent"], task["spec"], timeout=120)
    validate(output)

五、正確的擴展路徑

不要一步跳到 5 個代理的複雜系統。正確的路徑是：

Level 0 -> Level 1：加一個 Reviewer

# 你現在就可以做的最小改變
code = call_agent("implementer", spec)
review = call_agent("reviewer", code)  # 就這一步
if "FAIL" in review:
    code = call_agent("implementer", f"Fix:\n{review}\n\n{code}")

Level 1 -> Level 2：加自動測試

# 在審查後加 Tester + 實際執行
tests = call_agent("tester", code)
result = run_pytest(code, tests)  # 機器驗證，不靠 AI 判斷

Level 2 -> Level 3：平行化

# 找出可以平行的步驟
# 實作和測試可以同時進行（都只依賴 spec，不互相依賴）
impl_future = pool.submit(call_agent, "implementer", spec)
test_future = pool.submit(call_agent, "tester", spec)

Level 3 -> Level 4：Agent Team

# 用 Python Orchestrator（不是 AI）管理流程
# AI 做思考，Python 做控制
class Orchestrator:
    def run(self, spec):
        design = self.call_agent("architect", spec)
        self.validate(design)           # 驗證閘門

        impl, tests = self.parallel(    # 平行執行
            ("implementer", design),
            ("tester", design)
        )
        self.validate(impl)             # 驗證閘門

        review = self.call_agent("reviewer", impl)
        if "FAIL" in review:
            impl = self.call_agent("implementer", fix_prompt)

        self.run_tests(impl, tests)     # 機器驗證

六、Agent Spec 模板（直接複用）

以下是可以直接複製使用的模板，填入你的內容即可：

# Agent Spec: [功能名稱]

## WHAT - 做什麼
### 輸入輸出契約
- 函數/API 簽名：
- 輸入範例：
- 輸出範例：
- 錯誤情況：

### 行為規則
1. ...
2. ...

## HOW - 技術約束
### 必須使用
- 語言/框架：
- 現有模組（直接 import）：

### 現有介面（可以直接呼叫的）
- ...

## DON'T - 禁止
### 絕對不可
- ...

### 不要
- ...

## DONE - 完成標準
### 自檢清單
- [ ] ...

### 驗證指令
  pytest ...
  lint ...

## CONTEXT - 上下文（選用）
### 相關檔案
- ...

### 資料流
A -> B -> C -> D

七、一句話總結

SDD 是給人在不同時間反覆閱讀的。
Agent Spec 是給 AI 在一次 context 中完整消化的。
精準 > 詳細，200 行 > 2000 行。

本文是《2026 Agentic Coding Trends Report》深度解析系列的第三篇。系列文章：

第一篇：8 大趨勢的架構師視角解析
第二篇：雙代理流水線完整實作
第三篇：Agent Spec 設計指南（本文）

【實戰指南】如何為 AI 代理準備資料？Agent Spec 設計指南 — 從 SDD 到代理規格書的完整轉化

一、為什麼 SDD 不適合代理？

二、Agent Spec 的五個區塊

區塊一：WHAT — 做什麼（必要）

區塊二：HOW — 技術約束（必要）

區塊三：DON’T — 禁止事項（必要）

區塊四：DONE — 怎樣算完成（必要）

區塊五：CONTEXT — 最小必要上下文（選用）

三、不同任務複雜度對應的準備量

四、Agent Team 的致命問題：為什麼會卡死？

卡死模式 1：連鎖 Timeout

卡死模式 2：髒輸出污染下游

卡死模式 3：Spec 太長導致代理失焦

五、正確的擴展路徑

Level 0 -> Level 1：加一個 Reviewer

Level 1 -> Level 2：加自動測試

Level 2 -> Level 3：平行化

Level 3 -> Level 4：Agent Team

六、Agent Spec 模板（直接複用）

七、一句話總結

留言

發佈留言取消回覆

更多文章

Hacker News 每日精選 – 2026-03-26

為什麼 Claude 不遵守 Superpowers 的鐵律？理論與實務的落差分析

Claude Code Superpowers 隱藏規則：4 個你不知道的坑與避開方法

Agent Team 穩定的關鍵：spawn 之前先建好兩份文件

【實戰指南】如何為 AI 代理準備資料？Agent Spec 設計指南 — 從 SDD 到代理規格書的完整轉化

一、為什麼 SDD 不適合代理？

二、Agent Spec 的五個區塊

區塊一：WHAT — 做什麼（必要）

區塊二：HOW — 技術約束（必要）

區塊三：DON’T — 禁止事項（必要）

區塊四：DONE — 怎樣算完成（必要）

區塊五：CONTEXT — 最小必要上下文（選用）

三、不同任務複雜度對應的準備量

四、Agent Team 的致命問題：為什麼會卡死？

卡死模式 1：連鎖 Timeout

卡死模式 2：髒輸出污染下游

卡死模式 3：Spec 太長導致代理失焦

五、正確的擴展路徑

Level 0 -> Level 1：加一個 Reviewer

Level 1 -> Level 2：加自動測試

Level 2 -> Level 3：平行化

Level 3 -> Level 4：Agent Team

六、Agent Spec 模板（直接複用）

七、一句話總結

留言

發佈留言 取消回覆

更多文章

Hacker News 每日精選 – 2026-03-26

為什麼 Claude 不遵守 Superpowers 的鐵律？理論與實務的落差分析

Claude Code Superpowers 隱藏規則：4 個你不知道的坑與避開方法

Agent Team 穩定的關鍵：spawn 之前先建好兩份文件

發佈留言取消回覆