AI 協助規格撰寫指南
決策記錄: ADR-001: AI 協助規格撰寫策略
本指南說明 AppFuse 如何運用 AI 助手（Claude Code）協助規格撰寫，採用蘇格拉底式閉環模式，讓人做決策、AI 確保完整性。
核心原則
人提供方向與決策，AI 提供結構與完整性。
AI 在規格撰寫中的角色是思考夥伴，而非作者：
- AI 提問，不替人回答
- AI 分析缺口，不替人填充
- AI 整理結構，不替人創造
- AI 不自行添加額外想法，所有輸出都源自人的指示
- 人決定完成，AI 不催促
閉環模型
┌─────────────────────────────────────────────┐
│ │
▼ │
┌──────────┐ ┌──────────────┐ ┌─────────┐ │
│ 人提出想法 │───→│ AI 澄清與分析 │───→│ AI 搜集 │ │
│ (方向) │ │ (提問/挑戰) │ │ 整理資料 │ │
└──────────┘ └──────────────┘ └────┬────┘ │
│ │
▼ │
┌──────────┐ │
│ 人做決策 │──┘
│ (形成新想法)│
└─────┬────┘
│
完成？──→ 產出文檔
每次循環中：
- 人提出想法 — 功能方向、業務需求、技術偏好
- AI 澄清與分析 — 用分類法掃描找出模糊或遺漏的面向，提出結構化問題
- AI 搜集整理 — 讀取 Epic 脈絡、參考同類文檔、整理為結構化選項
- 人做決策 — 從選項中選擇或提出新想法，循環繼續
- 人決定完成 — 人隨時可以結束循環，AI 根據累積的決策產出文檔
AI 介入程度分層
不同層級的規格文檔，AI 的介入程度不同。越上游越需要人的判斷力，越下游越適合 AI 自動化。
人的判斷力重要性 AI 可靠度
Roadmap ████████████ ██
Domain Mdl ███████████ ███
Epic ██████████ ████
US ████████ ██████
SBE ████ █████████
API Spec ██ ████████████
| 文檔層級 | AI 介入模式 | 說明 |
|---|---|---|
| Roadmap | Level 2 — 對話式 | AI 作為思考夥伴，透過澄清循環協助人撰寫 |
| Domain Model | Level 2 — 對話式 | AI 作為思考夥伴，透過澄清循環協助人建立領域模型 |
| Feature List | 自適應 | 有 Roadmap 時 Level 3（一次性生成），無 Roadmap 時 Level 2（對話式） |
| Epic | Level 2 — 對話式 | AI 作為思考夥伴，透過澄清循環協助人撰寫 |
| User Story | Level 2 — 對話式 | AI 作為思考夥伴，透過澄清循環協助人撰寫 |
| SBE | Level 3 — 一次性生成 | AI 從 US 展開場景草稿，人審查 |
| API Spec | Level 3 — 一次性生成 | AI 從 US/SBE 正向設計或從程式碼反向萃取規格 |
為什麼 Roadmap 適合對話式？
- Roadmap 回答「做什麼」和「為什麼」— 需要市場洞察、競爭分析、利害關係人談判
- 這些決策完全由人主導，AI 不自行添加額外想法
- AI 的價值在於：搜集整理人的想法、確保結構完整（角色定義、權限矩陣、非功能需求等面向不遺漏）
- 對話式模式確保每一項輸出都有對應的人類指示，AI 只是整理與結構化
為什麼 Domain Model 適合對話式？
- Domain Model 定義業務實體、關聯關係與統一語言 — 這是概念層級的建模，需要人的領域知識
- 上游（Roadmap、Epic）已有角色定義和資料結構段落可供 AI 萃取候選實體
- 但「哪些是核心實體」、「關聯是一對多還是多對多」、「術語的正確定義」等決策完全由人主導
- AI 的 6 類分類法（核心實體、屬性與約束、關聯關係、生命週期、業務規則、統一語言）能有效確保建模完整性
- Domain Model 作為靜態模型（Static Model），與 Epic/US/SBE 的動態模型（Dynamic Model）互補
為什麼 Feature List 採用自適應模式？
- 有 Roadmap 時（Level 3 一次性生成）：功能已在 Roadmap 的戰略主題和 Epic 解構中識別完畢，AI 只需重新組織為使用者視角，不涉及新的決策
- 無 Roadmap 時（Level 2 對話式）：功能範圍尚未定義，需要透過澄清循環協助人識別功能領域、使用者能力、角色與權限
- 修訂既有 Feature List 時（Level 2 對話式）：需要討論新增/移除/調整哪些功能
/feature-list是第一個自適應介入模式的 Skill — 偵測上游文檔狀態，自動選擇模式
為什麼 Epic 適合對話式？
- Epic 定義功能範圍和 US 拆分 — 這是架構決策，不是文書工作
- 但上游（Roadmap）已有人工撰寫的戰略脈絡可供 AI 參考
- AI 的分類法掃描能有效識別遺漏的面向（業務價值、技術依賴、多租戶考量等）
- 對話式讓人主導決策，AI 確保完整性 — 兼顧深度思考與結構化產出
- 下游（
/us）已有工具銜接，可端到端驗證
為什麼 User Story 適合對話式？
- US 結構高度標準化（驗收標準、業務規則、技術規格等區段）
- 上游（Epic）已有人工撰寫的脈絡可供 AI 參考
- 下游（
/sbe）已有工具銜接，可端到端驗證 - AI 的分類法掃描能有效識別遺漏的面向
為什麼 SBE 適合一次性生成？
- SBE 是將 US 驗收標準「展開為具體數據」— 規則明確、格式固定
- 所有決策已在 US 中完成，SBE 只是結構化呈現
- AI 可參考 40+ 個既有 SBE 範例保持風格一致
可用工具
Skill 鏈
/roadmap → 產出 Roadmap + Feature List
↓
/domain-model → 對話式建立領域模型（實體、關聯、術語）
↓
/feature-list → 獨立建立或修訂 Feature List（自適應模式）
↓
/epic → 產出 Epic 文檔
↓
/us → 產出 US 文檔
↓
/checklist → 品質檢核（唯讀）
↓
/sbe → 產出 SBE 場景
├→ /e2e → 產出 E2E 自動化測試（Playwright）
├→ /test-plan → 產出手動測試指南
└→ /sprint → 規劃 Sprint Backlog + 更新 Feature List 狀態
↓
/api-spec → 產出 API 規格（正向設計或反向萃取）
↕ 任何階段皆可執行
/analyze → 跨文件一致性分析（唯讀）
客戶委託替代路徑：無 Roadmap 的專案可從
/feature-list（對話式）開始，取代/roadmap作為最上游文檔。
| Skill | 類型 | 用途 |
|---|---|---|
/roadmap | 對話式（澄清循環） | 協助撰寫 Roadmap，完成時附帶產出 Feature List |
/domain-model | 對話式（澄清循環） | 對話式建立領域模型，定義業務實體、關聯與統一語言 |
/feature-list | 自適應（一次性/對話式） | 獨立建立或修訂功能清單 |
/epic | 對話式（澄清循環） | 協助撰寫 Epic |
/us | 對話式（澄清循環） | 協助撰寫 User Story |
/sbe | 一次性生成 | 從 US 產生 SBE 場景草稿 |
/checklist | 一次性生成（唯讀） | US 需求品質檢核，產出品質檢核清單 |
/api-spec | 一次性生成 | 從 US/SBE 正向設計或從 Controller 反向萃取 API 規格 |
/analyze | 一次性生成（唯讀） | 跨文件一致性分析，產出分析報告 |
/e2e | 一次性生成 | 從 SBE 產生 Playwright E2E 測試 |
/test-plan | 一次性生成 | 從 US+SBE 產生手動測試指南 |
/sprint | 混合式（2-3 輪） | 盤點 US 庫存規劃 Sprint Backlog，更新 Feature List 狀態 |
本指南聚焦於規格撰寫的閉環模型與分類法。
/e2e、/test-plan、/sprint的詳細說明請見 Claude Code Skills 總覽。
/roadmap — Roadmap 對話式撰寫
使用方式：
/roadmap # 建立新 Roadmap 或改寫既有 Roadmap
/roadmap 花店管理系統 # 以產品名稱開始
工作流程：
- 偵測文檔專案、檢查既有 Roadmap
- 萃取既有脈絡（若為修訂模式）
- 展示初始種子、確認方向
- 進入澄清循環（6-12 輪）— 使用 8 類分類法逐步深入
- 人決定完成後，產生 Roadmap 文檔
- 建立 Epic 目錄結構、輸出彙總報告
澄清分類法（8 類）：
| 分類 | 探索方向 |
|---|---|
| 產品願景 | 為什麼做、解決什麼問題、市場定位 |
| 目標客群 | 服務誰、客戶區隔、痛點 |
| 戰略主題 | 主要業務目標、產品方向 |
| 用戶角色 | 角色定義、權限設計、使用場景 |
| 功能規劃 | Epic 拆分、各 Epic 範疇 |
| 優先排序 | Now/Next/Later、MVP 範圍 |
| 技術架構 | 多租戶策略、資料隔離、技術約束 |
| 非功能需求 | 效能、安全、擴展、可用性 |
/feature-list — 功能清單管理（自適應模式）
使用方式：
/feature-list # 自動偵測模式（建立或修訂）
/feature-list 花店管理系統 # 以產品名稱開始
自適應模式：
| 條件 | 模式 | 介入等級 |
|---|---|---|
有 roadmap.md + 無 feature-list.md | 一次性生成 | Level 3 — 從 Roadmap 提取功能，重新組織為使用者視角 |
無 roadmap.md + 無 feature-list.md | 對話式建立 | Level 2 — 透過 6 類澄清分類法協助定義功能範圍 |
feature-list.md 已存在 | 對話式修訂 | Level 2 — 討論新增/移除/調整功能 |
對話式模式的澄清分類法（6 類）：
| 分類 | 探索方向 |
|---|---|
| 功能領域 | 系統有哪些主要功能區塊 |
| 使用者能力 | 每個領域中使用者能做什麼 |
| 角色與權限 | 哪些角色使用哪些功能 |
| 優先排序 | Now/Next/Later 階段劃分 |
| 範圍界定 | 什麼在範圍內、什麼排除 |
| Epic 映射 | 功能與開發 Epic 的對應關係 |
/domain-model — 領域模型對話式撰寫
使用方式：
/domain-model # 自動偵測模式（建立或修訂）
/domain-model 花店管理系統 # 以產品名稱開始
自適應模式（始終 Level 2 對話式，但種子來源不同）：
| 條件 | 路徑 | 種子來源 |
|---|---|---|
有 Roadmap/Epic + 無 domain-model.md | 對話式建立（有上游） | 從 Epic 功能範疇的資料結構段落、Roadmap 角色定義萃取候選實體 |
無上游文檔 + 無 domain-model.md | 對話式建立（無上游） | 從 research/ 或使用者描述推導 |
domain-model.md 已存在 | 對話式修訂 | 讀取既有模型，詢問修訂方向 |
澄清分類法（6 類）：
| 分類 | 探索方向 |
|---|---|
| 核心實體 | 業務中有哪些關鍵物件 |
| 屬性與約束 | 關鍵屬性、驗證規則 |
| 關聯關係 | 實體間如何關聯（1:1, 1:N, M:N） |
| 生命週期 | 實體狀態與轉換 |
| 業務規則 | 跨實體的領域不變量 |
| 統一語言 | 術語定義、易混淆術語 |
/epic — Epic 對話式撰寫
使用方式：
/epic 4 # 建立或改寫 Epic 4
/epic epic-4 # 同上
/epic 支付管理 # 以描述搜尋或建立新 Epic
工作流程：
- 偵測文檔專案、定位 Roadmap
- 萃取 Roadmap 上游脈絡
- 展示初始種子、確認方向
- 進入澄清循環（4-8 輪）— 使用 8 類分類法逐步深入
- 人決定完成後，產生 Epic 文檔
- 更新 Epics README 連結、輸出彙總報告
澄清分類法（8 類）：
| 分類 | 探索方向 |
|---|---|
| 業務價值 | 為什麼做、解決什麼問題、目標客群 |
| 功能範圍 | 核心功能、進階功能、排除項 |
| 用戶角色 | 主要使用者、角色權限差異 |
| US 拆分 | User Stories 列表、優先級分組 |
| 技術依賴 | 跨 Epic 關係、外部系統 |
| 資料模型 | 關鍵 Entity、欄位、關聯 |
| 多租戶與安全 | 數據隔離、編號格式、權限控制 |
| 非功能需求 | 效能、擴展性、可用性 |
/us — User Story 對話式撰寫
使用方式：
/us US-401 # 從 Epic 的 US 列表中定位待建條目
/us --epic=4 營收報表查看 # 指定 Epic + 描述
/us 營收報表查看 # 只有描述，需詢問 Epic
工作流程：
- 偵測文檔專案、定位 Epic
- 萃取 Epic 上游脈絡
- 展示初始種子、確認方向
- 進入澄清循環（4-8 輪）— 使用 8 類分類法逐步深入
- 人決定完成後，產生 US 文檔
- 更新 Epic 連結、輸出彙總報告
澄清分類法（8 類）：
| 分類 | 探索方向 |
|---|---|
| 功能行為 | 主要用戶流程、步驟、成功路徑 |
| 角色與權限 | 誰能操作、權限等級差異 |
| 業務規則 | 計算邏輯、驗證規則、業務約束 |
| 邊界案例 | 錯誤場景、空狀態、極端值 |
| UI/UX | 頁面佈局、互動行為、響應式設計 |
| API 設計 | 端點、Payload、狀態碼 |
| 資料模型 | 欄位、關聯、既有表 |
| 非功能需求 | 效能、分頁、快取 |
/checklist — US 需求品質檢核
使用方式：
/checklist US-201 # 以 US 編號定位
工作流程：讀取 US + Epic 脈絡 → 執行 7 維度品質檢核 → 產生品質檢核報告
7 大品質維度（借鑑 Spec Kit）：
| 維度 | 說明 |
|---|---|
| Completeness | 所有必要需求是否已記錄 |
| Clarity | 需求是否明確無歧義 |
| Consistency | 需求之間是否對齊且無衝突 |
| Measurability | 成功標準是否可客觀驗證 |
| Coverage | 所有場景/邊界案例是否已涵蓋 |
| Edge Case | 邊界條件和故障模式是否已定義 |
| Non-Functional | 效能、安全、無障礙的規格 |
注意：/checklist 是唯讀的，絕不修改原始 US 文檔。報告中的建議行動會連結到具體的 Skill 指令（如 /us），由人決定是否執行。
/sbe — SBE 場景生成
使用方式：
/sbe US-301 # 以 US 編號定位
工作流程：讀取 US → 選擇場景 → 產生 SBE 場景檔 → 更新 US 的 SBE 區段
/analyze — 跨文件一致性分析
使用方式：
/analyze # 全專案分析
/analyze epic-2 # 分析 Epic 2 及其下游文件
/analyze US-201 # 分析特定 US 及其 SBE
工作流程：偵測文檔專案 → 收集文件清單 → 執行 5 通道分析 → 產出分析報告
5 個分析通道：
| 通道 | 檢查內容 |
|---|---|
| 結構完整性 | Roadmap → Epic → US → SBE 的文檔是否存在、連結是否有效 |
| 覆蓋率 | US 驗收標準是否被 SBE 場景覆蓋 |
| 一致性 | 跨文件的 API 路徑、Payload 欄位、角色權限是否一致 |
| 術語一致性 | 角色名稱、實體名稱跨文件是否統一 |
| 規格品質 | US/SBE 是否缺少必要區段、是否有 TODO 標記 |
注意：/analyze 是唯讀的，絕不修改原始檔案。報告中的建議行動會連結到具體的 Skill 指令（如 /us、/sbe），由人決定是否執行。
借鑑來源：GitHub Spec Kit
AppFuse 的 AI 協助方法借鑑了 GitHub Spec Kit 的兩個核心概念：
Clarify（澄清）
Spec Kit 的 /speckit.clarify 用 10 大分類法掃描 spec 的完整度，每個分類標記為 Clear / Partial / Missing，以 Impact × Uncertainty 排序問題優先級，逐一提問後直接回寫 spec。
Spec Kit 的 10 大分類：Functional Scope & Behavior、Domain & Data Model、Interaction & UX Flow、Non-Functional Quality Attributes、Integration & External Dependencies、Edge Cases & Failure Handling、Constraints & Tradeoffs、Terminology & Consistency、Completion Signals、Misc/Placeholders。
AppFuse 已借鑑的部分：/us、/epic、/roadmap 的澄清循環採用類似的 8 類分類法掃描，但不讓 AI 直接回寫，而是整理為選項讓人決策。
AppFuse 尚可改善的部分（優先級：低）：
| Spec Kit 有、AppFuse 缺 | 價值 | 建議行動 |
|---|---|---|
| Terminology & Consistency（術語一致性） | 跨文檔使用不同術語是常見問題（如「訂單」vs「工單」） | 可在對話式 Skill 的分類法中增加此維度 |
| Completion Signals（完成訊號） | 確保每個驗收標準是可測試的、每個指標是可量測的 | 可在澄清循環中加入此檢查 |
✅ 已實作 — /us、/epic、/roadmap 的彙總報告已包含「分類法覆蓋摘要」區段 |
不採用的部分：Spec Kit 讓 AI 直接回寫 spec，AppFuse 維持「人決策、AI 整理」的閉環模式不變。
已解決的情境：
| 情境 | 說明 | 解決方案 |
|---|---|---|
| 客戶委託的專案，上游需求來自客戶的 RFP/SOW，團隊可能直接從 Epic 開始，無需自行撰寫 Roadmap | ✅ 已透過 /feature-list 的對話式模式解決。客戶委託路徑：/feature-list（對話式）→ /epic → /us → /sbe。Feature List 作為最上游文檔，提供功能範圍、角色定義、優先排序等脈絡，供下游 /epic 和 /analyze 讀取 |
Analyze（分析）
Spec Kit 的 /speckit.analyze 做跨文件一致性檢查（spec ↔ plan ↔ tasks），使用六通道分析（Duplication、Ambiguity、Underspecification、Constitution Alignment、Coverage Gaps、Inconsistency），產出唯讀分析報告。
AppFuse 的借鑑：/analyze 將此概念適配到 AppFuse 的文檔鏈（Roadmap → Epic → US → SBE），使用五通道分析（結構完整性、覆蓋率、一致性、術語一致性、規格品質），檢查跨層級的對齊度。與 Spec Kit 相同，/analyze 是唯讀的，絕不修改原始檔案；不同之處在於建議行動會連結到具體的 Skill 指令（如 /us US-207、/sbe US-201），讓人直接執行修正。
Checklist（檢核表）
Spec Kit 的 /speckit.checklist 產生需求品質檢核表，核心理念是**「英文的單元測試」（unit tests for English）**— 測試的是需求撰寫品質，而非實作是否正確。
正確寫法（測試需求品質）：
- [ ] CHK001 - 導航需求是否對所有可點擊的品牌元素都有明確定義？ [Clarity, Spec §FR-010]
- [ ] CHK002 - 「合理時間內」是否已量化為具體的秒數？ [Measurability, US-201 §非功能需求]
錯誤寫法（測試實作）：
- [ ] 驗證按鈕點擊後導航到首頁
- [ ] 確認載入時間在 2 秒內
Spec Kit Checklist 的 7 大品質維度
| 維度 | 說明 | 範例問題 |
|---|---|---|
| Completeness | 所有必要需求是否已記錄 | 「所有 API 故障模式的錯誤處理需求是否已定義？」 |
| Clarity | 需求是否明確無歧義 | 「『快速載入』是否已量化為具體的時間閾值？」 |
| Consistency | 需求之間是否對齊且無衝突 | 「導航需求在所有頁面之間是否一致？」 |
| Measurability | 成功標準是否可客觀驗證 | 「『平衡的視覺重量』能否被客觀量測？」 |
| Coverage | 所有場景/邊界案例是否已涵蓋 | 「零狀態場景的需求是否已定義？」 |
| Edge Case | 邊界條件和故障模式是否已定義 | 「圖片載入失敗時的降級行為是否已規定？」 |
| Non-Functional | 效能、安全、無障礙的規格 | 「所有互動元素的無障礙需求是否已規定？」 |
Spec Kit Checklist 的工作流程
- 動態產生最多 3 個情境問題（釐清焦點領域，如 security、UX、API）
- 結合答案衍生檢核表主題
- 讀取 spec.md（+ 選用 plan.md、tasks.md）
- 產生檢核表檔案至
checklists/目錄（如ux.md、api.md、security.md） - 每個項目格式：
- [ ] CHK### - [問句]? [品質維度, 可追溯性引用] - 可追溯性要求：至少 80% 的項目包含
[Spec §X.Y]引用 - 項目軟性上限：40 個
AppFuse 的實作：
/checklist 已實作為獨立 Skill，定位於 /us 產出後、/sbe 產出前的品質閘門。
| 面向 | 說明 |
|---|---|
| 位置 | /us → /checklist → /sbe |
| 輸入 | US 文檔（+ Epic 脈絡） |
| 輸出 | 品質檢核清單（獨立 Markdown 檔案，不修改原始 US） |
與 /analyze 的區別 | /analyze 做跨文件一致性檢查（結構性），/checklist 做單一文件品質檢核（語意性） |
| 品質維度 | 參考 Spec Kit 的 7 維度（Completeness、Clarity、Consistency、Measurability、Coverage、Edge Case、Non-Functional） |
| Skill 定義 | .claude/skills/checklist/SKILL.md |
花店訂單 US 的品質檢核範例：
## Requirement Completeness
- [ ] CHK001 - 訂單金額的計算規則是否明確定義（小計、稅金、運費、折扣）？
[Completeness, US-201 §業務規則]
- [ ] CHK002 - 所有訂單狀態轉換的觸發條件是否已定義？
[Completeness, US-201 §驗收標準]
## Requirement Clarity
- [ ] CHK003 - 「合理時間內」是否已量化為具體的秒數或百分位數？
[Measurability, US-201 §非功能需求]
## Edge Case Coverage
- [ ] CHK004 - 配送日期額滿時是否定義了替代方案（如推薦下一個可用日期）？
[Edge Case, US-201 §Scenario 2]
## Consistency
- [ ] CHK005 - 「客戶」與「消費者」是否指同一角色？跨 US 使用是否一致？
[Consistency]
與 Spec Kit 的關鍵差異
| Spec Kit | AppFuse | |
|---|---|---|
| 文檔作者 | AI 產生，人審查 | 人決策，AI 整理 |
| AI 角色 | 草稿撰寫者 | 思考夥伴 |
| 風險 | 人可能直接接受 AI 草稿 | 每個決定都經過人的判斷 |
| 適用場景 | 快速原型 | 正式產品規格 |
| 一致性分析 | spec ↔ plan ↔ tasks | Roadmap → Epic → US → SBE 完整鏈 |
| 分析報告 | 可回寫 spec | 僅產出獨立報告，絕不修改 |
使用注意事項
AI 推斷內容需標記
當 AI 根據脈絡推斷未經人確認的內容時，會加上標記：
<!-- TODO: 此項由 AI 推斷，待確認 -->
產出文檔後，團隊應搜尋 <!-- TODO 標記，逐一確認或修正。
Three Amigos 審查不可省略
無論 AI 介入程度如何，Three Amigos 審查仍是必要的品質閘門：
- 產品經理 — 確認業務價值與驗收標準
- 開發人員 — 確認技術規格與可行性
- 測試人員 — 確認 SBE 場景與邊界條件
漸進式導入
建議的推進順序：
| 階段 | 行動 | 目的 |
|---|---|---|
| Phase 1 | 使用 /sbe 產生 SBE | 驗證 AI 產出品質 |
| Phase 2 | 使用 /us 撰寫 US | 驗證對話式模式 |
| Phase 3 | 收集回饋、調整流程 | 持續改善 |
參考資源
- GitHub Spec Kit
- Spec-driven development with AI — GitHub Blog
- Specification by Example — Gojko Adzic
最後更新: 2026-03-02