Engineering

把治理寫成 build 閘門,而不是寫成規範文件

發布於

多數公司都有一份「官網文案規範」。上面寫著不要誇大、數字要有依據、 開發中的功能不要寫成已經有了。這份文件通常寫得很好,然後被存進雲端硬碟, 接著在下一次趕上線時被完整地繞過。

問題不在人不夠自律,而在於規範文件的執行時機是「有人想起來要檢查」。 那是一個沒有觸發條件的流程。

讓違規的內容無法通過建置

我們把這個網站的內容規則寫成建置期的閘門。不是 lint 警告,是會讓 npm run build 以非零結束碼中止的錯誤。四層,各自負責不同的事:

第一層在 schema。 每一種內容型別都有 Zod schema,欄位缺漏、列舉值不合法、 或違反自訂規則,在 astro build 讀取內容時就失敗。例如產品的成熟度與功能的 成熟度是兩個獨立的列舉 —— 型別上就不可能把「已上線」填進一個還在開發的產品。

第二層是跨集合檢查。 單一檔案合法,不代表整體一致。已發布的內容引用了 一個未核准的宣稱、專案缺少歸屬類型、頁面宣告了不存在的關聯 —— 這些都需要 跨檔案比對才看得出來,因此獨立成一支在 build 前執行的檢查腳本。

第三層是渲染守衛。 就算一筆未核准的宣稱進到資料裡,渲染元件也會把它排除。 這一層的存在是承認前兩層可能有漏洞:防線只有一道的時候,那一道破了就全破了。

第四層檢查產出物本身。 建置完成後掃描 dist/,確認沒有洩漏的機密、 沒有非預期的語系路由、sitemap 的每一個網址都對應到實際存在的頁面。 這一層驗證的不是原始碼的意圖,而是實際要被部署出去的東西。

為什麼值得

因為錯誤會擴散,而且擴散得比修正快。

我們自己踩過一次:公司統一編號填錯了一個字元。它不是只錯在一個地方 —— 那個值被結構化資料、頁尾、聯絡頁共用,一次錯誤同時出現在將近一百個公開位置。 發現的時候它已經被建置、被部署過。

修正只花了幾分鐘。真正的教訓是,如果當時有一道「統編必須通過檢核碼驗證」 的建置閘門,這件事根本不會發生。現在有了。

閘門要留一條需要聲明的例外路徑

只會擋、不能通融的檢查,最後都會被關掉。這幾乎是規律。

所以我們的檢查在遇到無法自動判定的情況時,不是直接放行也不是直接阻斷, 而是要求作者明確聲明。舉例來說,一篇文章的段落如果同時出現產品名稱與數字, 程式無法判斷那是「我們做到的成果」還是「產業普遍現象」—— 前者需要憑證支撐, 後者不需要。這種情況下建置會中止,並要求作者在檔案的 frontmatter 裡 明確加上一行聲明,表示這個數字已經被人看過。

差別很細微但很重要:規範文件問的是「你記得檢查了嗎」, 建置閘門問的是「你聲明你檢查過了嗎」。前者無法稽核,後者留在版本控制裡。

這不是完美的

自動檢查抓得到結構性的錯誤,抓不到語氣上的誇大。一句「我們深耕產業多年」 不會觸發任何規則,但它可能同樣不精確。

閘門處理的是「可以被機器判定的那一類錯誤」,而那一類剛好是最容易在 趕時間時發生、也最容易造成實質後果的。剩下的仍然需要人讀。 但至少人可以把注意力放在真正需要判斷的地方,而不是重複檢查一個 電腦本來就該擋下來的欄位。

回到觀點列表