AI Agent Spec 的核心價值，是把模糊需求改寫成一份可執行的工作契約。 一個完整模板包含 What、Done、Constraints、Context、失敗處理、產出形式、緊急程度與備註八欄；時間有限時，至少填妥目標、完成標準與約束。這三欄能直接減少 agent 猜測、返工與無效 token。
Prompt 技巧只能加分，工作契約才決定成敗
「幫我研究企業 AI 導入」看似簡潔，agent 卻必須自行決定受眾、範圍、證據標準、篇幅、格式、禁止事項與失敗策略。每一個未寫明的決策，都可能把輸出帶向錯誤方向。
OpenAI 對 Codex 的官方建議也指向相同原則：提供來源材料、限制、審查期待與目的格式，並讓目標可以驗證。GitHub 的 agentic workflow 指南同樣要求 issue 包含問題陳述、acceptance criteria 與相關檔案。Spec 的作用，就是把這些條件集中成穩定介面。
八欄完整模板
以下區塊保留原始模板，可直接複製使用：
## Spec · [一句话任务名]
### 1. 目标(What)——给谁看 / 做什么
- **受众**:__(岗位 / 角色 / 场景)__
- **输出类型**:__(报告 / 文章 / 表格 / 代码 / 推文)__
- **必含项**(至少 3 个,缺一不可):
- [ ] __
- [ ] __
- [ ] __
- **不准出现**:__
### 2. 完成标准(Done)——什么算"做完了"
满足以下所有条件,才算完成(可验证,不是"差不多就行"):
- [ ] __可机器验证__
- [ ] __可人眼验证__
- [ ] __可截图验证__
### 3. 约束(Constraints)——不能踩的红线
- **风格**:__(简洁 / 详细 / 案例驱动)__
- **长度**:__(≤ N 字 / N 段)__
- **不准做的事**:__
### 4. 上下文(Context)——只放必要的
- **背景**:__(1-2 句)__
- **已知输入**:__(文件路径 / 链接)__
- **已完成**:__(前几步已做)__
### 5. 失败处理——歧义时怎么办
- [ ] **直接假设并继续**(默认)
- [ ] **停下来问我**
- [ ] **报错退出**
### 6. 产出形式
- **存到**:__
- **回我**:__(完整内容 / 路径 / 截图)__
### 7. 紧急程度
- [ ] 高 / [ ] 中 / [ ] 低
### 8. 备注
__(可选:历史经验、相关工具)__
填完後會長什麼樣子
原始範例把受眾、產出、數量與紅線都寫進同一份 Spec：
## Spec · AI 企业落地案例汇总表格
1. 目标:
- 受众:部门负责人(40-55 岁,企业中高层)
- 输出类型:案例表格 + 1 封面 + 3 配图
- 必含:① 央企 AI 落地真实数据 ② 3 个岗位案例 ③ 一句话锋利判断
- 不准:百度百科开头 / "AI 是大势所趋"
2. 完成标准:
- [ ] 表格中有一列摘要 每个案例 100字的案例摘要 内容有冲突 + 锋利判断
- [ ] 至少 3 个具体工作场景
- [ ] 每个案例配 1 张图
- [ ] 末尾问 1 个管理者能直接问的问题
3. 约束:
- 风格:case-first(先案例再机制)
- 数量:150-300 个案例，每个一行
- 不准:emoji / 黄色文字
4. 上下文:第 3 篇,前两篇已发
5. 失败处理:直接假设并继续(我有判断力)
6. 产出:到我workspace文件夹 + 路径给我
7. 紧急:中
這份範例仍有可改善之處。150 至 300 個案例與每個案例配圖，會大幅增加成本；「真實資料」也需要明確定義來源門檻。好的 Spec 要讓成本、範圍與驗證方法彼此一致，不必刻意塞滿所有欄位。
Done 必須可驗證
「內容品質高」無法讓 agent 判斷是否完成。有效的 Done 應包含機器可驗證、人眼可驗證與畫面可驗證條件，例如測試退出碼為 0、全文至少 800 字、指定頁面在 1440×810 畫面沒有溢位。
若要派給 sub-agent，原始模板把回傳格式與 off-limits 範圍一起帶入：
delegate_task(
goal="[1-sentence goal]",
context="""
## Spec
- 目标:__
- 完成标准: [ ] __, [ ] __, [ ] __
- 约束:__
- 失败处理:__
- 工具/环境:__
- 必交付物:__(路径 + 格式)__
- 回主 agent 的格式:__(JSON / Markdown / 截图)__
## 关键约束
- 不要重新发明__
- 必须用__ skill
- 不要触碰__ (off-limits)
""",
)
三張速查表
| 必填项 | 不填的后果 |
|---|---|
| 目标(What) | agent 猜 4-5 个决策 |
| 完成标准(Done) | agent 永远不会停 |
| 约束(Constraints) | agent 跑偏到风格/长度红线 |
| 反例 | 正例 |
|---|---|
| "差不多就行" | "输出 JSON 含 verified: true 字段" |
| "内容质量高" | "不少于 800 字 + 表格清晰可读" |
| "风格符合预期" | "case-first(先案例再机制) + 不准 emoji" |
| 选项 | 适用场景 |
|---|---|
| 直接假设并继续 | 你判断力 OK,想快 |
| 停下来问我 | 歧义很大,跑错代价高 |
| 报错退出 | 硬性歧义(eg: 文件不存在) |
失敗策略尤其重要。低風險、可逆的歧義可採合理假設；會改變目標或產生外部影響的歧義應停下詢問；必要檔案不存在時，直接報錯比製造看似完整的結果更安全。
自測數字只能當起點
原始模板附有一組自測結果，但沒有公開任務集、原始紀錄與統計方法，因此應視為個人案例，不能當成通用 benchmark：
| 输入方式 | 平均 token | 平均返工 | 一次完成率 |
|---|---|---|---|
| 一句话需求 | 18,500 | 3.2 次 | 12% |
| 填 3 项 Spec | 9,200 | 1.4 次 | 51% |
| 填全 8 项 Spec | 5,400 | 0.3 次 | 87% |
團隊可以用自己的三個真實任務做 A/B 比較，記錄總 token、人工介入次數、完成時間與驗收通過率。這會比套用別人的百分比更有決策價值。
附錄版八欄模板
## Spec · [一句话任务名]
### 1. 目标(What)——给谁看 / 做什么
- **受众**:__
- **输出类型**:__
- **必含项**(至少 3 个):
- [ ] __
- [ ] __
- [ ] __
- **不准出现**:__
### 2. 完成标准(Done)
- [ ] __
- [ ] __
- [ ] __
### 3. 约束(Constraints)
- **风格**:__
- **长度**:__
- **不准做的事**:__
### 4. 上下文(Context)
- **背景**:__
- **已知输入**:__
- **已完成**:__
### 5. 失败处理
- [ ] 直接假设 / [ ] 停下来问 / [ ] 报错退出
### 6. 产出形式
- **存到**:__
- **回我**:__
### 7. 紧急程度
- [ ] 高 / [ ] 中 / [ ] 低
### 8. 备注:__
最少一定要填哪三欄？
目標、完成標準與約束。它們分別回答要做什麼、何時算完成，以及哪些邊界不能跨越。
Spec 會不會讓簡單任務變慢？
簡單、低風險任務可以只用三欄版。任務越長、越昂貴、越不可逆，越值得補齊 Context、失敗處理與產出位置。
Done 要寫幾條才夠？
沒有固定數量。每一條都應能用測試、檔案、數值、畫面或人工審查直接判斷通過與否。
可以讓 agent 自己補 Spec 嗎？
可以。先提供三個核心欄位，再要求 agent 列出其餘假設。涉及預算、外部發布或不可逆操作時，仍應由人確認。
權威來源
- OpenAI：Give Codex goals it can verify
- OpenAI：How to use Codex for everyday work
- OpenAI：Introducing Codex
- GitHub：From idea to PR
Author Insight
我把 Spec 視為人與 agent 之間的 API。欄位名稱不是重點，輸入、邊界、錯誤處理與驗收能否被雙方一致理解，才決定工作能否重複。當同類任務開始反覆出現，就把有效 Spec 寫進範本或 repository instructions，讓好做法成為系統預設。
如果你想把 AI agent 放進團隊的固定流程，Tenten 能協助把模糊職責拆成可驗證的 Spec、測試與交付契約。與我們討論。
