1. 為什么“能力”需要一個單一真相源做技術管理或者系統(tǒng)架構(gòu)的人大概都經(jīng)歷過這樣的場景產(chǎn)品經(jīng)理拿著一份需求文檔說“這個功能要支持批量導入”后端開發(fā)說“接口文檔里寫的是單條提交”前端說“我看到的原型圖上只有一個上傳按鈕”測試說“驗收標準里沒提批量的事”。四個人手里四份文檔四份文檔四個版本最后上線的東西跟誰說的都不一樣。這不是誰不負責任而是信息在傳遞過程中天然會發(fā)散。每經(jīng)過一個人的手就多一層理解偏差每經(jīng)過一次文檔更新就多一個可能不同步的副本。Spec 系統(tǒng)要解決的就是這個問題——讓“能力”這件事只有一個真相源所有人看同一份東西所有人基于同一份東西做判斷。所謂“能力”在這個語境下可以理解為一個系統(tǒng)對外承諾能做的事情。比如“支持批量導入”“支持按標簽篩選”“支持導出為 CSV”這些都是能力。能力不是代碼不是接口不是 UI而是介于需求和實現(xiàn)之間的一層抽象描述。它比需求更具體比代碼更穩(wěn)定比接口更貼近業(yè)務語義。為什么這一層特別需要單一真相源因為它是所有下游工作的起點。接口設計要從能力推導測試用例要從能力推導用戶文檔要從能力推導甚至銷售跟客戶承諾什么也要從能力推導。如果能力的描述本身就有多個版本那下游所有東西都會跟著亂。我見過一個團隊能力描述散落在三個地方Jira 的 epic 描述里、Confluence 的 PRD 里、以及某個資深工程師的腦子里。前兩個經(jīng)常不同步第三個只在他不請假的時候有效。結(jié)果就是每次排期都要先花半小時對齊“這個功能到底包不包含某某場景”效率極低。Spec 系統(tǒng)的核心思路很簡單把能力從各種文檔和腦子里抽出來放到一個結(jié)構(gòu)化的、可版本控制的、機器可讀的地方。這個地方就是單一真相源。所有其他文檔要么引用它要么從它生成不允許手寫副本。這個思路跟數(shù)據(jù)庫設計里的“第三范式”有點像——消除冗余讓每個事實只存一處。只不過這里的事實不是數(shù)據(jù)行而是“系統(tǒng)能做什么”這件事。2. Spec 系統(tǒng)的結(jié)構(gòu)長什么樣2.1 從自然語言到結(jié)構(gòu)化聲明Spec 系統(tǒng)不是讓你寫更長的文檔而是讓你用更結(jié)構(gòu)化的方式寫更短的聲明。核心是把“系統(tǒng)應該做什么”拆成一條條獨立的、可驗證的聲明。每條聲明包含幾個要素能力標識、行為描述、前置條件、預期結(jié)果、驗收標準。聽起來像測試用例確實像但粒度更粗更偏向業(yè)務語義而不是技術實現(xiàn)。舉個例子。假設我們要描述“用戶可以用郵箱登錄”這個能力。在 Spec 系統(tǒng)里它可能長這樣能力: 郵箱登錄 前置: 用戶已注冊且郵箱已驗證 行為: 用戶提交郵箱和密碼 預期: 系統(tǒng)驗證憑證成功則返回會話令牌失敗則返回錯誤提示 驗收: - 正確憑證返回 200 和令牌 - 錯誤密碼返回 401 和“密碼錯誤” - 未驗證郵箱返回 403 和“請先驗證郵箱”注意這里沒有提任何技術細節(jié)——沒說用什么加密算法沒說令牌是 JWT 還是別的沒說數(shù)據(jù)庫怎么查。這些是實現(xiàn)層的事Spec 層只關心“系統(tǒng)承諾做什么”。這種寫法的好處是產(chǎn)品、開發(fā)、測試都能看懂而且都能基于它做自己的工作。產(chǎn)品確認行為描述是否符合業(yè)務預期開發(fā)確認前置條件和預期結(jié)果是否可實現(xiàn)測試直接把驗收標準轉(zhuǎn)成測試用例。2.2 關鍵詞 GWT 與 SHALL 的用法在 Spec 系統(tǒng)里GWT 和 SHALL 是兩個高頻出現(xiàn)的詞。GWT 是 Given-When-Then 的縮寫是一種描述行為的模板。Given 描述前置狀態(tài)When 描述觸發(fā)動作Then 描述預期結(jié)果。上面那個郵箱登錄的例子用 GWT 重寫就是Given 用戶已注冊且郵箱已驗證 When 用戶提交正確的郵箱和密碼 Then 系統(tǒng)返回 200 和會話令牌這種寫法比自由文本更嚴謹因為它強制你把“在什么條件下”和“發(fā)生什么動作”分開。很多需求文檔的歧義就來自這兩者混在一起。比如“用戶登錄后可以看到訂單列表”這句話里“登錄后”是條件還是動作不清楚。用 GWT 拆開就清楚了。SHALL 則是用來表達強制性的。在 Spec 里SHALL 表示“必須做到”SHOULD 表示“建議做到”MAY 表示“可選”。這跟 RFC 2119 里的用法一致。為什么要在 Spec 里區(qū)分 SHALL 和 SHOULD因為不是所有能力都是同等重要的。有些是核心承諾做不到就是 bug有些是錦上添花做不到也能上線。如果不區(qū)分測試就不知道哪些失敗要阻塞發(fā)布哪些可以記錄后放行。我自己的習慣是每個 Spec 文件里 SHALL 級別的聲明不超過十條。超過十條說明這個能力太籠統(tǒng)了應該拆成多個能力。比如“用戶管理”這個能力如果寫了二十條 SHALL那大概率應該拆成“用戶注冊”“用戶登錄”“用戶信息修改”“用戶注銷”四個能力。2.3 文件組織與命名約定Spec 文件怎么組織直接決定了它能不能長期維護。我見過兩種極端一種是所有 Spec 塞在一個大文件里幾千行改一處要翻半天另一種是每個小功能一個文件結(jié)果幾百個文件散在目錄里找都找不到。比較合理的做法是按業(yè)務域分目錄每個能力一個文件。比如specs/ auth/ email-login.spec phone-login.spec password-reset.spec order/ create-order.spec cancel-order.spec query-order.spec payment/ alipay-payment.spec wechat-payment.spec文件名用 kebab-case跟能力標識保持一致。這樣從能力名就能直接定位到文件從文件也能反推能力名。每個文件內(nèi)部的結(jié)構(gòu)也要統(tǒng)一。我通常要求包含這幾個部分能力概述、前置條件、行為聲明GWT 列表、驗收標準、依賴關系、變更記錄。變更記錄很重要因為 Spec 是單一真相源它的歷史就是系統(tǒng)能力演化的歷史。哪天產(chǎn)品問“這個能力是什么時候加的”翻變更記錄比翻聊天記錄靠譜得多。注意Spec 文件不要寫實現(xiàn)細節(jié)。我見過有人在 Spec 里寫“用 bcrypt 加密密碼”這是實現(xiàn)決策不是能力聲明。能力聲明只說“系統(tǒng)驗證憑證”怎么驗證是開發(fā)的事。把實現(xiàn)寫進 Spec 會導致兩個問題一是限制了開發(fā)的技術選型自由二是實現(xiàn)變了 Spec 就要跟著改失去了穩(wěn)定性。3. 單一真相源怎么落地而不是停留在口號3.1 從“寫文檔”到“寫聲明”的思維轉(zhuǎn)變大部分團隊說要做單一真相源最后都變成了“我們再建一個 Confluence 空間吧”。這不是單一真相源這只是又一個副本。真正的單一真相源要求其他所有地方都不允許手寫能力描述只能引用或生成。這個要求聽起來簡單執(zhí)行起來阻力很大。因為寫自由文檔比寫結(jié)構(gòu)化聲明舒服多了。自由文檔可以含糊其辭可以“大概”“可能”“視情況而定”結(jié)構(gòu)化聲明不行你必須把條件寫清楚。我推動這個轉(zhuǎn)變的時候用的辦法是“先做減法再做加法”。先讓團隊把現(xiàn)有文檔里關于能力的描述全部刪掉換成一句“能力定義見 Spec 系統(tǒng)”。然后逼著大家去 Spec 系統(tǒng)里補。補的過程中自然就會發(fā)現(xiàn)哪些能力描述不清楚哪些有歧義。這個過程大概會持續(xù)兩到三周期間會有各種不適。開發(fā)說“我就想直接寫代碼不想寫 Spec”產(chǎn)品說“我寫 PRD 的時候順手就把能力寫了為什么還要單獨寫”。這時候需要一點強制力——比如把 Spec 完成度納入排期準入條件Spec 沒寫完不允許進入開發(fā)。3.2 版本控制與變更流程Spec 系統(tǒng)必須放在版本控制里這是底線。放在 Confluence 或者在線文檔里的 Spec 不是真正的單一真相源因為你看不到 diff不知道誰在什么時候改了什么。用 Git 管理 Spec 有幾個好處。第一每次變更都有記錄誰改的、改了什么、為什么改都在 commit message 里。第二可以走 Pull Request 流程變更需要 review 才能合并。第三可以跟代碼倉庫放在一起Spec 變更和代碼變更在同一個 PR 里保證同步。變更流程我建議這樣設計任何人可以提 Spec 變更的 PR但合并需要至少一個產(chǎn)品和一個開發(fā)的 approve。產(chǎn)品確認業(yè)務語義沒問題開發(fā)確認技術可實現(xiàn)。合并后自動觸發(fā)下游同步——比如生成測試用例骨架、更新 API 文檔的能力列表、通知相關方。這里有個坑不要允許直接 push 到主分支。我見過一個團隊為了圖方便允許直接改 Spec 文件結(jié)果兩個月后 Spec 和實際能力完全對不上因為改的人從來不通知別人。單一真相源的前提是變更可見直接 push 就破壞了可見性。3.3 與需求管理工具的邊界Spec 系統(tǒng)和 Jira 這類需求管理工具是什么關系我的觀點是Jira 管“做什么、誰來做、什么時候做完”Spec 管“系統(tǒng)承諾什么”。兩者有交集但不重合。一個 Jira ticket 可能對應多個 Spec 變更一個 Spec 變更也可能跨多個 ticket。比如“支持批量導入”這個能力可能拆成三個 ticket后端接口、前端頁面、導入模板校驗。但 Spec 里只有一條能力聲明。所以不要把 Spec 塞進 Jira 的描述字段里。Jira 的描述字段是給這個 ticket 的執(zhí)行者看的Spec 是給所有相關方看的?；煸谝黄饡е?Spec 被 ticket 的臨時上下文污染。比較合理的做法是Jira ticket 里引用 Spec 文件路徑和具體的能力標識但不復制內(nèi)容。執(zhí)行者點鏈接跳到 Spec 系統(tǒng)看詳情。這樣 Spec 更新了所有引用它的 ticket 自動看到最新版。4. 實操中容易踩的五個坑4.1 坑一Spec 寫成了實現(xiàn)說明書這是最常見的坑。寫著寫著就開始寫“系統(tǒng)調(diào)用某某接口”“數(shù)據(jù)存到某某表”“用某某算法”。一旦 Spec 里出現(xiàn)技術名詞它就不再是能力聲明了而是實現(xiàn)文檔。為什么這個坑容易踩因為寫 Spec 的人往往是開發(fā)開發(fā)腦子里全是實現(xiàn)細節(jié)不寫出來難受。而且寫實現(xiàn)細節(jié)顯得很專業(yè)寫純行為描述反而顯得“虛”。判斷標準很簡單如果換一種技術棧實現(xiàn)同樣的能力Spec 需不需要改如果需要改說明寫進實現(xiàn)細節(jié)了。比如“用戶提交郵箱和密碼”不需要改“用 bcrypt 驗證密碼”就需要改。4.2 坑二驗收標準寫成了測試步驟驗收標準和測試步驟的區(qū)別是什么驗收標準說“系統(tǒng)應該返回 401”測試步驟說“打開 Postman輸入 URL選擇 POST 方法填入 body點擊 Send檢查狀態(tài)碼”。前者是能力的一部分后者是驗證能力的方法。把測試步驟寫進 Spec 會導致 Spec 變得極其冗長而且跟具體測試工具綁定。換一個測試框架Spec 就要重寫。更糟的是測試步驟會掩蓋真正的驗收標準——讀者要在幾十行操作步驟里找那一句“應該返回 401”。我的做法是Spec 里只寫驗收標準測試步驟放在測試代碼里。測試代碼引用 Spec 的能力標識這樣 Spec 變了測試代碼能感知到但 Spec 本身保持簡潔。4.3 坑三SHALL 濫用導致優(yōu)先級失效前面說了 SHALL 表示必須做到。但很多團隊寫著寫著所有聲明都變成 SHALL因為“這個也很重要”“那個也不能少”。結(jié)果就是沒有優(yōu)先級所有失敗都阻塞發(fā)布團隊被 Spec 綁架。我見過一個極端案例一個中等復雜度的能力寫了四十多條 SHALL結(jié)果每次發(fā)版前測試都要跑幾百個用例跑完要兩天。后來我讓他們重新評審把 SHALL 壓到八條其余改成 SHOULD發(fā)布效率立刻上來了。壓 SHALL 的方法問“如果這條做不到用戶會不會完全無法使用這個能力”如果答案是“不會只是體驗差一點”那就改成 SHOULD。如果答案是“會整個能力就廢了”才保留 SHALL。4.4 坑四Spec 和代碼不同步Spec 是單一真相源但如果代碼改了 Spec 沒改那 Spec 就變成了“單一謊言源”。這個問題在快速迭代的團隊里特別嚴重因為改代碼的人往往不是寫 Spec 的人。解決這個問題的根本辦法是把 Spec 變更納入 Definition of Done。一個任務完成的標志不是代碼合并而是代碼合并且 Spec 已更新。如果 Spec 不需要更新要在 PR 里明確說明“本次變更不涉及能力變化”。另一個輔助手段是自動化檢查。比如在 CI 里加一步檢查本次 PR 修改的代碼文件是否關聯(lián)了 Spec 變更。如果沒有關聯(lián)給出警告但不阻塞。這個警告能提醒開發(fā)者“你是不是忘了改 Spec”。4.5 坑五把 Spec 當成一次性文檔有些團隊把 Spec 當成項目啟動時的文檔寫完就扔在一邊后續(xù)迭代只改代碼不改 Spec。這等于白做。Spec 是活的它應該跟代碼一樣頻繁更新。每次能力有變化Spec 就要變。每次發(fā)現(xiàn) Spec 描述不準確就要修正。Spec 的價值不在于寫出來的那一刻而在于持續(xù)維護的過程中形成的共識。我自己的習慣是每周花半小時過一遍最近變更的 Spec看看有沒有描述過時或者歧義的地方。這個習慣堅持了兩年Spec 的準確率一直保持在 95% 以上。5. 讓 Spec 系統(tǒng)真正產(chǎn)生價值的三個杠桿5.1 從 Spec 生成測試用例骨架Spec 里的 GWT 聲明天然就是測試用例的模板。Given 對應測試的前置準備When 對應測試的執(zhí)行動作Then 對應斷言。所以可以寫一個簡單的生成器把 Spec 文件轉(zhuǎn)成測試框架的骨架代碼。比如上面郵箱登錄的例子生成出來的 pytest 骨架大概是def test_email_login_success(): # Given 用戶已注冊且郵箱已驗證 user create_verified_user(emailtestexample.com, passwordcorrect) # When 用戶提交正確的郵箱和密碼 response client.post(/login, json{email: testexample.com, password: correct}) # Then 系統(tǒng)返回 200 和會話令牌 assert response.status_code 200 assert token in response.json()開發(fā)只需要填充 Given 和 When 的具體實現(xiàn)Then 的斷言已經(jīng)生成好了。這能省掉大量寫測試樣板代碼的時間而且保證測試覆蓋了所有 Spec 聲明。提示生成器不需要很復雜一個幾百行的腳本就夠。關鍵是 Spec 的格式要統(tǒng)一否則解析起來很麻煩。這也是為什么前面強調(diào)文件結(jié)構(gòu)要規(guī)范。5.2 用 Spec 做變更影響分析當某個能力要變更時怎么知道會影響哪些下游如果 Spec 里記錄了依賴關系這個問題就很好回答。比如“郵箱登錄”這個能力依賴“用戶注冊”和“郵箱驗證”兩個能力。如果“郵箱驗證”的流程變了“郵箱登錄”的驗收標準可能需要跟著調(diào)整。通過 Spec 的依賴圖可以快速找到所有受影響的能力。更進一步如果測試用例是從 Spec 生成的那 Spec 變更后可以自動標記哪些測試用例需要重新評審。這比人工判斷靠譜得多也快得多。5.3 把 Spec 作為新人入職的第一份材料新人入職最怕什么怕沒人告訴他系統(tǒng)到底能做什么?？创a太細看 PRD 太舊問老人太打擾。Spec 系統(tǒng)正好填補這個空白。一個維護良好的 Spec 系統(tǒng)新人花半天就能通讀一遍知道系統(tǒng)有哪些能力、每個能力的邊界在哪、能力之間怎么依賴。這比任何入職文檔都管用。我?guī)У拿總€新人第一周的任務就是讀 Spec 并提問題。讀不懂的地方就是 Spec 寫得不好的地方順手就改了。這樣 Spec 在服務新人的同時也得到了持續(xù)改進。6. 關于 Spec 系統(tǒng)的一些個人體會Spec 系統(tǒng)不是銀彈它解決的是“能力描述不一致”這個問題不解決“需求不合理”或者“排期太緊”的問題。如果團隊本身溝通就很順暢Spec 系統(tǒng)的收益可能沒那么明顯。但如果團隊超過十個人或者系統(tǒng)能力超過五十個Spec 系統(tǒng)的價值就會指數(shù)級上升。我自己的經(jīng)驗是Spec 系統(tǒng)的投入產(chǎn)出比在第三個月開始轉(zhuǎn)正。前兩個月主要是建設成本寫 Spec、搭工具、改流程感覺在額外做功。第三個月開始因為對齊成本下降、返工減少、新人上手加快收益開始超過成本。另一個體會是Spec 系統(tǒng)要“輕”。不要試圖把什么都塞進去不要追求大而全。從最核心的十個能力開始把格式跑通把流程跑順再逐步擴展。一上來就搞幾百個 Spec大概率會爛尾。最后說一個反直覺的點Spec 系統(tǒng)最大的價值可能不是“讓所有人看同一份文檔”而是“逼著所有人把模糊的地方想清楚”。寫 Spec 的過程本身就是一次深度思考很多歧義在寫的過程中就暴露了根本等不到下游發(fā)現(xiàn)。這個價值比文檔同步本身更大。