【菜鳥 PM 學習日記 】EP 10｜如何兼顧人類與 AI：關於 Spec 的三大改革！

Designed by Lina

前言：針對 spec 本身的三個重大改革

如上一篇文章所述，這次 PM 團隊的 AI Workflow 專案，短期著眼於讓 spec 的撰寫流程更加自動化，但在遙遠的未來，我們期待公司內部所有團隊能全部串連起來：

PM 團隊產出 spec 後，直接交由開發團隊的 AI agent 進行開發、測試團隊的 AI agent 也能同步撰寫測試案例，最後由人類確認產出是否如預期即可。

點我看上一篇文章：【菜鳥 PM 學習日記 】EP 09｜快被 AI 取代了？！參與 AI Workflow 專案的焦慮與反思

因此，我們要做的不只是「讓 AI 能寫出符合產品脈絡、既定格式的 spec」，也要「確保 spec 能被 AI 完全理解、以便維持穩定的產出品質」，未來才能與開發與測試團隊的 AI workflow 順利接上。

Photo by Toa Heftiba on Unsplash

團隊內部討論後認為，若要達成後者，目前的 spec 撰寫格式、迭代方式、管理工具都得一起改革，主要原因如下：

撰寫格式

• 格式不穩定：過去 spec 可能由不同 PM 撰寫，每個人的慣用結構、細節程度、命名方式、描述習慣都不同。對人類來說，只要有經驗或願意追問，要理解通常不是問題，但格式不穩定會讓 AI 讀取與產出結果變得不穩定。
• 結構較零散：我們團隊內的 spec 寫法偏向敘事說明、較少用表格或邏輯寫法呈現，人類容易閱讀，但不一定方便 AI 解析。

改革方向：改為統一且更有結構性的格式，並考量 AI 的理解邏輯，從最高層級的產品目標、使用者故事（User Story）、驗收標準（Acceptance Criteria），寫到最細節的顯示邏輯、互動機制、錯誤碼（Error Code）等。

Photo by Corinne Kutz on Unsplash

迭代方式

過去每次有新功能、新調整就新增一份 spec，只描述與過往 spec 有差異的部分，不斷疊加上去。短期來看很方便，因為每份文件的內容都對應某次需求，大家可以只專注在這次的改動上；但長期累積下來，同一個頁面的功能描述會散落在多份文件裡，造成以下問題：

• 想理解目前功能時，需要翻很多份 spec
• 舊文件不一定標示是否已過期，不確定是否為最新版本
• 新 PM 或 AI 很難判斷哪份才是可參考的資料來源

改革方向：建立一份 living spec 並不斷迭代，理想上隨時查看內容，都會與目前實作的現況是一致的。

Photo by Artur Opala on Unsplash

管理工具

Notion 很適合人類閱讀、共編，也有資料庫能整理文件，但歷史紀錄查找不易，難以確認過去是誰改了哪些內容；因此，若 spec 未來要成為 AI 的輸入來源，可能就需要更明確的版本控制與變更紀錄，甚至直接以 Markdown 格式撰寫、讓 AI 可以更快速方便地去讀取所有資訊。

改革方向：把 spec 從 Notion 搬到 GitLab，連同 i18n key 清單也一起放在 GitLab 管理。

1. 撰寫格式：如何兼顧人類與 AI 閱讀體驗

起初我們曾考慮把 spec 改成 BDD（Behavior-Driven Development）格式，因為 Given / When / Then 的結構非常清楚，理論上很適合讓 AI 解析，也很適合延伸成測試案例。

BDD 格式範例

但實際測試後發現，如果整份 spec 都用 BDD 來寫，文件很容易變得冗長，對人類讀者來說過於零碎，反而難以快速掌握整體脈絡。於是我決定採取折衷方式，保留 BDD 格式的核心概念「明確寫出情境、條件與預期結果」，但改成雙層格式：

• 上層先用「使用者故事（User Story）」和列點直述句的「驗收標準（Acceptance Criteria）」讓讀者快速理解這個頁面的目標與標準。

User Story + AC 格式範例

• 下層再用表格拆解細節、對應 AC，例如欄位顯示邏輯（包含不同使用者權限的差異）、互動行為、錯誤狀態、i18n key、Error Code 等。

互動行為（TCR）表格範例

跟許多任職於軟體業的朋友交流後，才發現不同團隊人數多寡、人員配置、協作模式、產品階段等都差異極大，因此大家的 spec 格式都不盡相同！某些團隊只有一位 PM、產品需要快速迭代，所以只寫了 User Story + AC，其餘細節都讓工程師（或 AI）自由發揮；某些團隊的 PM 甚至太忙而沒寫 spec，只給幾張示意圖和簡短文字，詳細 spec 都是由不同工程師自己寫、各自存在本地端讓 agent 照著開發！

我們團隊算是 PM 需要想得很深入、寫得很細節的，所以才發展出上述那樣的文件格式，但因還沒實際用在真的需求上，不確定對於人類和 AI 讀者來說，是否真能達到兼顧閱讀體驗與產出品質的效果，只能等未來再邊嘗試邊優化了。

Photo by Girl with red hat on Unsplash

2. 迭代方式：如何拆分 spec 文件單位

過去的 spec 只描述新版本改動的部分，因此一份 spec 的單位切分較為單純且隨性，有時以 user flow（使用者流程）為單位，有時以頁面為單位、所有小改動都寫在同一份；新版統一的 Living spec 聽起來很美好，但在建立過程中最困擾我的就是：

一份 spec 的邊界到底該怎麼切？

切得太粗（如：以模組為單位），可能導致檔案極為冗長；切得太細（如：以流程為單位），又可能造成資訊過於分散、比對與維護不易的問題。

• 以「功能」為單位：確實接近傳統需求文件，也容易對應特定開發範圍，但發生在同一個頁面的行為就會被拆散，需要讀很多份檔案才能拼湊出一個頁面的完整現況。
• 以「頁面」為單位，更接近使用者實際看到的產品狀態，或許更適合作為 living spec，但如果頁面具備很多功能、文件變得很長，不一定能精準對應單次開發範圍，AI 也可能不小心花了很多力氣讀取不需要的資訊。

Photo by lan deng on Unsplash

後來我們決定先採用「以 URL 為單位」的拆分方式，因為產品內的分頁（tab）、側邊欄（side panel）都有自己的 URL，這樣的拆分標準不僅相對穩定、明確，也多少能避免同一個頁面很多子分頁、文件過於冗長的問題。當團隊成員或 AI 想查看某個頁面的特定功能時，可以直接根據 URL 找到對應的 spec，不必在一堆文件裡透過標題判斷哪份才包含相關內容。

這不一定是最完美的方法，但以目前的產品功能與需求來說，應該是最能兼顧維護成本與產出品質的。

3. 管理工具：如何用 GitLab 功能設計對應流程

對一個幾乎不寫程式、過去也很少實際使用 Git 的菜鳥 PM 來說，要先理解 Git / GitLab 原本的運作邏輯，再轉譯成 PM 團隊可以實際採用的 spec 管理流程，其實比想像中困難得多。

起初我以為自己只要搞懂一些基本名詞就好：Commit 是修改紀錄、Branch 是分支、Merge 是合併、MR (Merge Request) 是請別人 review。但真正開始設計流程時，我發覺更難的是如何靈活運用這些功能及概念，達成每個節點想要達成的目的。例如：

• 如果我們希望 living spec 永遠反映已上線的產品現況，那哪一個 branch 才應該代表正式版本？
• 開發中的 spec 要放在哪裡？
• 需求還在討論、spec 還修修改改時要不要開 branch？spec 改到什麼程度需要 commit？
• 什麼時候需要發 MR、由誰 review？
• 什麼情況下才能將開發中的 spec merge 回正式版本？

Photo by Viktor Talashuk on Unsplash

更可怕的是，一旦變成多人協作就變得複雜許多。如果多個負責不同需求的 PM，同時在自己的 branch 修改了同一份 spec 的同一個段落，就會產生衝突（conflict），但在希望流程盡可能自動化的前提下，解衝突其實是很耗力費時的。於是問題接踵而至：

• 我們可以怎麼減少衝突產生？靠協作規則來降低重疊修改？
• 如果真的衝突，該由誰處理？
• 每一位 PM 是否需要自己解，還是該由現階段較熟悉 Git 的成員協助？

圖片來源：GitLab

我也花了點時間與工程師朋友、經常使用 GitLab 的專案經理交流，了解這些功能對他們而言的意義，以及平時在開發時的使用情境。

這讓我重新理解 Git 的價值，它不只是工程師用來管理程式碼的工具，也是一套嚴謹的協作邏輯：如何讓多人同時開工、修改同一份檔案，卻仍能保留歷史、看見差異、進行 review，最後合併成正式版本、確保意外發生時都能補救。

寫了這麼多，必須說光是 spec 本身改動的部分就讓我傷透腦筋。

起初我以為，只要調整模板、統一格式、讓內容結構化一點，然後把文件改成 Markdown 放在 GitLab 上，就能滿足未來「讓 AI 開發」的需求。

但實際設計才發現，spec 是整個產品開發流程裡的重要節點，一切環環相扣：spec 格式的改變不只影響 PM 怎麼寫，更牽扯到工程師怎麼讀、AI 怎麼解析，而這些角色需要的、適合的都不同；換了 spec 的管理工具，也必須重新設計 spec review 等協作機制。

Photo by Fredrick Suwandi on Unsplash

整個專案過程中就是無止盡的取捨：

怎麼兼顧產出品質、維護成本、閱讀體驗、人力成本，甚至還有使用 AI 的 token 成本！

目前這套格式與流程，還沒有真正經過大量需求的驗證，未來肯定得花不少成本在嘗試、調整、優化。期待未來嘗試出了一點心得，能再繼續與大家分享成果與調整方式！

如果你喜歡我的文章，歡迎替我拍手 👏 或分享給身邊可能感興趣的人！ （小提醒：長按拍手按鈕可以拍 50 下唷）