演示無法過夜：一次模擬環境當機後，我們將 preflight 移至 CI

上個月為一個團隊交付了模擬環境的自動化腳本，在交付前最後一輪的批次執行演示中，於凌晨兩點半失敗。日誌僅顯示一行超時錯誤，環境直接鎖死，隔天早上我們對著螢幕重新安裝了一整套依賴套件。復盤時大家一片沉默，因為這個問題其實「早就預防過」——操作手冊（runbook）裡明明寫著。

問題出在操作手冊本身。那份包含 40 多個步驟的啟動檢查清單（checklist）躺在共享文件中，標註著「執行前核對」。但那次演示前的審查人員負責編寫腳本，實際點擊執行的是負責演示的同事，兩人對於「核對到位」的理解存在些微落差：文件規定模擬器的時區需與日誌時區對齊，審查人員是依據本地機器時間進行核對，卻沒算到演示機器位於海外機房，存在 8 小時的時差。凌晨發生超時的時候，他人在家中。

我們所做的改動很小：**將檢查清單從共享文件移至程式碼倉庫，並設定為 CI 中必須通過（綠色狀態）的 preflight 關卡。**

1. 每個模擬設定檔附带一個 `preflight.json`，宣告時區、資料路徑、依賴版本

2. 在 CI 中執行 dry-run：載入設定、建構 pipeline、執行 2 個步驟，不寫入磁碟，僅驗證「這條路徑是否可行」

3. dry-run 的輸出結果（單一步驟耗時、資料樣本數）直接貼入 PR 描述中，合併（merge）後才能進入正式排程

4. 排程時，調度器會比對該設定 dry-run 的實測耗時，若超出預算則直接拒絕

第二個價值在於交接。那位負責演示的同事在接手時，無需再猜測我們當時為何這樣設定——每個設定旁邊都附帶了其 dry-run 的實測數據，比口头交接更為準確。

第三個價值是**它迫使操作手冊精簡化**。原本 40 個步驟中，有 30 個步驟可以自動檢查。移入 CI 之後，剩下需要人工記憶的僅剩 8 條，其中 3 條關於客戶業務，與工程無關，後來移至客戶自己的 wiki 中。

遇到的陷阱：dry-run 最初使用 mock 資料，但在正式批次執行的真實資料中存在一個超長樣本，導致 dry-run 通過、實際執行卻超時。改為使用「真實資料的 header + 隨機填充」之後，便未再出現此問題。成本是多花了 20 分鐘搭建資料管道，但比起凌晨兩點重新安裝環境划算多了。

數據

- 交付週期從 11 天縮短至 7 天（省去了兩次因當機而重新安裝的時間）

- 演示前置檢查從 40 步人工核對降至 1 項 CI 狀態檢查

- preflight.json 現在有 12 個設定共用同一套 schema，新增一個任務的檢查成本約為 15 分鐘

教訓很樸素：**寫給別人看的清單，默讀時效果會打折；寫進流水線自動執行的檢查，則不會。** 並非所有步驟都適合自動化，但適合的那部分應盡早移出，操作手冊才能短到讓人真的願意去閱讀。