規格書撰寫 - WHERE 寫在哪？

決定「寫什麼」與「怎麼寫」之後，下一個常被忽略卻會反覆造成痛點的問題是：規格書要放在哪裡？

載體的選擇看似只是工具偏好，實際上會直接影響規格的可信度、同步成本與長期維護性。一份永遠對得上程式碼的規格，比一份寫得漂亮但已經過期的規格有用得多。

選擇載體的核心原則

在比較工具之前，先建立三個判準：

1. Single Source of Truth（SSoT）：同一份資訊不應該有兩個版本。如果規格散落在 Notion、Slack 截圖、Slack 評論裡，沒人知道哪一份是對的。
2. 版本控制：規格會隨產品演化。沒有版本控制的規格，等於沒辦法回答「上次發布時這個欄位的定義是什麼？」這類問題。
3. 離程式碼的距離：規格離程式碼越遠，兩者越容易脫鉤。AI 協作時代尤其明顯——AI Agent 讀不到的規格，等於不存在的規格。

母性原則的延伸：規格是程式碼、測試、文件的母體。母體若放在難以同步、難以版本化的地方，所有由它衍生的產出物都會被連鎖污染。

常見載體比較

Notion

• 優點：
  • 使用者友善，容易上手，適合非技術人員協作。
  • 富文本、嵌入、資料庫關聯齊全，做產品提案、會議記錄、知識庫都很順手。
  • 權限管理細緻，適合跨部門共享。
• 缺點：
  • 不利於版本控制：歷史紀錄有，但無法像 git 那樣 diff、blame、branch。
  • SSoT 破裂風險高：從 Notion 落地到專案的文件需要額外的轉換，可能會因為修改造成兩邊不同步。
  • 轉換成本：從 Notion 轉換到專案文件，格式可能會跑掉，造成文件不易閱讀。
  • AI 誤譯放大效應：若透過 AI 協助轉譯到 Markdown，可能會有誤譯。這會引發後續嚴重的連鎖反應，如同母性原則一樣，原始文件轉譯錯誤，後續的文件、程式碼、測試都是由 AI Agent 產出，錯誤會不斷被放大。
  • 離線不可用、搜尋速度受限於網路。

GitHub Markdown 原始文件

• 優點：
  • 可以直接進行版本控制：git diff、blame、PR review 完整可用。
  • 可直接在專案中使用：避免轉換造成的格式跑掉或誤譯問題。
  • 與程式碼同生共死：規格、程式碼、測試在同一個 PR 中一起被審查、一起被合併。
  • AI 友善：Claude Code、Copilot 這類 AI Agent 可以直接讀取 repo 中的 Markdown，作為生成程式碼的依據。
  • 支援 MDX 後可嵌入互動元件、流程圖、Mermaid 圖。
• 缺點：
  • 對非技術人員相對不友善，有一點學習成本(Markdown 語法、git 操作)。
  • 純文字編輯體驗不如 Notion 流暢，大型表格、複雜排版較費工。
  • 圖片管理需要額外規範(放 docs/assets/、用 git-lfs 等)。

撰寫實務建議

1. 不要為了工具而選工具，先想清楚這份文件的生命週期:會被實作嗎？會回頭檢視嗎？三年後還需要嗎？
2. 越接近程式碼的規格，越要靠近程式碼存放:功能規格 → 放在原始碼資料夾；產品願景 → 可以留在 Notion。
3. 同一份資訊只在一個地方維護:其他地方一律放連結，不要複製貼上。

小結

載體的選擇本質上是在問:「這份規格的讀者是誰？生命週期多長？會被誰消費？」

• 給人看、討論中、跨部門 → Notion / Google Docs
• 給程式碼與 AI 看、要長期維護、要被審查 → GitHub Markdown

但有一個方向:規格的家應該離程式碼越近越好。離得越近，SSoT 越穩固，母性原則的污染風險越低，AI 協作時代的規格才能真正成為產品的母體。

常見載體一覽

載體	版本控制	對非技術人員	與程式碼距離	AI 可讀性	適合放
Notion	弱	友善	遠	低	草稿、會議記錄、跨部門知識庫
GitHub Markdown	強	有門檻	近	高	正式規格、AC、技術設計

推薦組合：草稿 Notion / Google Docs ➜ 定稿 GitHub Markdown ➜ 追蹤 Jira / Linear