跳至主要内容

ADR-001: AI 協助規格撰寫策略

ADR 編號: 001 狀態: 已接受 (Accepted) 決策日期: 2026-02-06 決策者: AppFuse Team 範圍: docs-methodology（開發方法論）

摘要​

採用「蘇格拉底式閉環」模式，讓 AI 作為思考夥伴協助規格撰寫，而非讓 AI 直接產生規格文檔。

背景 (Context)​

問題陳述​

AppFuse 的規格撰寫流程（Roadmap → Epic → User Story → SBE）目前完全手動。隨著 AI 編碼助手的成熟（Claude Code、GitHub Copilot），團隊需要決定 AI 在規格撰寫流程中的角色與介入程度。

GitHub 於 2025 年 9 月開源了 Spec Kit，提出 Spec-Driven Development 方法，其中 /clarify（規格澄清）和 /analyze（跨文件一致性分析）兩個概念值得參考。

限制條件​

  • 規格品質直接影響實作品質，不容許「看起來完整但缺乏深度」的文檔
  • 團隊成員需要在撰寫過程中思考與發現問題，這個過程本身有價值
  • 不同層級的規格文檔（Roadmap vs SBE）對 AI 的依賴程度應有差異

假設前提​

  • AI 在結構化展開（如 US → SBE）的可靠度高於創造性決策（如 Roadmap 規劃）
  • 團隊成員具備領域知識，AI 無法替代
  • AI 的最大價值在於確保完整性，而非產生內容

考量的方案 (Options Considered)​

方案 A: 全人工撰寫（現狀）​

說明: 維持現有流程，所有規格文檔由人工撰寫，不使用 AI 輔助。

優點:

  • ✅ 每個決定都經過人的深思熟慮
  • ✅ 不需要學習新工具或調整流程

缺點:

  • ❌ 撰寫速度慢，容易遺漏區段
  • ❌ 無法利用 AI 的結構化分析能力
  • ❌ 不同作者的文檔風格不一致

評分: 2/5

方案 B: AI 產生草稿、人審查（Spec Kit 模式）​

說明: 採用 GitHub Spec Kit 的方法，AI 根據簡短描述產生完整規格草稿，人審查後修改。

優點:

  • ✅ 產出速度最快
  • ✅ 格式一致性高

缺點:

  • ❌ 人容易直接接受 AI 草稿，跳過深度思考
  • ❌ AI 產生的上游文檔（Roadmap、Epic）容易泛泛而談
  • ❌ 團隊失去在撰寫過程中發現問題的機會

評分: 3/5

方案 C: 蘇格拉底式閉環（人決策 + AI 澄清）​

說明: AI 作為思考夥伴，透過提問、分析、搜集整理來協助人做決策。閉環流程：

人提出想法 → AI 澄清與分析 → AI 搜集整理 → 人做決策 → 循環 → 人決定完成

不同層級採用不同的 AI 介入程度。

優點:

  • ✅ 每個決定都由人做出，保留思考過程
  • ✅ AI 確保完整性（分類法掃描、一致性檢查）
  • ✅ 下游文檔（SBE）可高度自動化，上游文檔保留人的主導權
  • ✅ 借鑑 Spec Kit 的 clarify/analyze 概念，但避免其風險

缺點:

  • ❌ 比方案 B 慢（需要多輪對話）
  • ❌ 需要設計對話式 Skill（比一次性生成 Skill 複雜）

評分: 5/5

決策 (Decision)​

選擇方案: C — 蘇格拉底式閉環

核心理由:

  1. 上游規格（Roadmap/Epic/US）的價值在於思考過程，AI 化會削弱這個價值
  2. 下游規格（SBE/API Spec）是結構化展開，AI 可靠度高
  3. 閉環模式兼顧效率（AI 提供結構）與品質（人做決策）

權衡分析 (Trade-offs)​

我們獲得什麼 (Gains)​

  • ✅ 規格完整性提升（AI 的分類法掃描避免遺漏）
  • ✅ 文檔風格一致（AI 參考既有範例產出）
  • ✅ 保留團隊的領域知識與判斷力
  • ✅ 漸進式採用，降低導入風險

我們放棄什麼 (Losses)​

  • ❌ 無法享受「AI 一鍵產生完整規格」的速度
  • ❌ 對話式 Skill 的開發與維護成本較高

風險與緩解措施 (Risks & Mitigations)​

風險嚴重性機率緩解措施
澄清循環過長，效率低於預期中中限制每輪問題數（≤3）、提供「跳過」和「完成」出口
AI 提問品質不穩定中低使用 8 類分類法結構化引導、參考既有範例
團隊不適應對話式工作流低中先在 /us 試行，收集回饋後調整

影響 (Consequences)​

正面影響​

  • ➕ 建立了 /roadmap、/feature-list、/epic、/us、/checklist、/sbe、/api-spec 七個 Skill，涵蓋完整的規格撰寫鏈
  • ➕ 形成完整的 Skill 鏈：/roadmap → /feature-list → /epic → /us → /checklist → /sbe → /api-spec
  • ➕ /feature-list 的自適應模式解決了客戶委託專案（無 Roadmap）的替代路徑問題

負面影響​

  • ➖ 需要維護 Skill 定義（SKILL.md），隨團隊實踐演進

中性影響​

  • 🔸 不同層級的 AI 介入程度需要持續調校

實作指南 (Implementation Guidelines)​

AI 介入程度分層​

文檔層級AI 角色Skill狀態
Roadmap思考夥伴（對話式）/roadmap✅ 已建立
Feature List自適應（一次性/對話式）/feature-list✅ 已建立
Epic思考夥伴（對話式）/epic✅ 已建立
User Story思考夥伴（對話式）/us✅ 已建立
SBE展開者（一次性生成）/sbe✅ 已建立
Checklist品質檢核器（唯讀）/checklist✅ 已建立
API Spec提取者（一次性生成）/api-spec✅ 已建立
分析報告一致性檢查器（唯讀）/analyze✅ 已建立

漸進式推進策略​

Phase 1            Phase 2              Phase 3
━━━━━━━━━━━━━━   ━━━━━━━━━━━━━━━━   ━━━━━━━━━━━━━━━━
✅ /sbe 已建立    ✅ /epic 已建立       收集回饋、調整流程
✅ /us 已建立     ✅ /roadmap 已建立    ✅ /analyze 已建立

必須遵守的規則​

  1. AI 不替人決策：所有規格內容的最終決定權在人
  2. AI 不自行添加額外想法：所有輸出都源自人的指示，AI 只負責結構化整理
  3. AI 推斷需標記：AI 自動補充的內容必須加 <!-- TODO --> 標記
  4. Three Amigos 審查不可省略：AI 產生的草稿仍需團隊審查
  5. 漸進式導入：先在下游（SBE）驗證，再往上游推進

相關文檔 (References)​

內部文檔​

  • AI 協助規格撰寫指南
  • 規格撰寫指南
  • 開發流程指南
  • /roadmap Skill 定義：.claude/skills/roadmap/SKILL.md
  • /feature-list Skill 定義：.claude/skills/feature-list/SKILL.md
  • /epic Skill 定義：.claude/skills/epic/SKILL.md
  • /us Skill 定義：.claude/skills/us/SKILL.md
  • /sbe Skill 定義：.claude/skills/sbe/SKILL.md
  • /checklist Skill 定義：.claude/skills/checklist/SKILL.md
  • /analyze Skill 定義：.claude/skills/analyze/SKILL.md

外部資源​

變更歷史 (Change Log)​

日期變更內容變更者
2026-02-06初版AppFuse Team + AI Assistant
2026-02-06新增 /checklist Skill（借鑑 Spec Kit Checklist）AppFuse Team + AI Assistant
2026-02-12新增 /feature-list Skill（自適應模式），解決客戶委託專案替代路徑AppFuse Team + AI Assistant

文檔維護者: AppFuse Team + AI Assistant 最後審閱: 2026-02-12