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