唯讀優先：第一次執行目標系統前先做唯讀驗證

具體情境

你要為新環境部署設定變更，或是在執行緒中讓 AI 修改生產環境設定。你寫了一個改動，一發布上去整個服務就掛了，底下的人在罵你。經典情境：

1. 你寫了一段設定改動，發布後服務掛掉
2. 你在程式碼中修改了一個 API，QA 發現它把其他三個 API 的回傳值都改了
3. 你在生產環境進行了一次環境探測，結果把健康檢查的狀態旗標搞亂了

問題不在你的技術水準，而在於你跳過了一步。先做唯讀驗證。

什麼是唯讀驗證

唯讀驗證 = 在完成之前，先跑一遍目標系統的唯讀模式。 意思是你不改變任何東西，只檢查你的改動會在哪些層面遇到副作用。

一次唯讀驗證包含三個子步驟：

子步驟	你要回答的問題	典型操作
依賴檢查	我的改動會觸及哪些模組？哪些是唯讀的？	靜態分析 / Lint / 文件搜尋
影響評估	同層的其他程式碼會不會被波及？	執行緒追蹤 / 流量追蹤 / 日誌搜尋
狀態確認	我看的資料是不是當前狀態？會不會被併發修改？	CHECKSUM / 時間戳記 / 狀態旗標比對

什麼時候用它

• 進入新環境做第一次改動
• 改動涉及共享資源（API、資料庫、設定）
• 你不清楚完整架構圖，只能看到其中一部分
• 有併發修改風險（多人同時修改，或者有排程任務在跑）
• 你在讓 AI 或自動化系統修改程式碼，你無法人工審查所有改動

什麼時候可以略過

• 你很清楚架構，改動範圍單點明確
• 你已經做了很多次同類改動（不是第一次）
• 有現實可行的自動化回歸測試當後盾
• 改動不涉及共享狀態（例如修改自己的文件）

怎麼操作（3 步走）

步驟 1：依賴圖邊界檢查

這一步你可能已經做過很多次依賴梳理，但在做的時候經常漏掉一類：唯讀判斷。

正確做法：

1. 列出所有要改動的模組
2. 對每個模組，找出所有可能從那裡讀取資料的位置
3. 對每個讀取位置，確認它是唯讀的，還是會在讀取的同時修改狀態
4. 將非唯讀的位置標註出來

# 範例：修改 config.yaml
-grep -r "config.yaml" --include "*.py"
# 發現：
#   main.py:5  read_config()       # 唯讀 → 安全
#   cache.py:12 load_config()      # 唯讀 → 安全
#   health.py:8 check_config()     # 讀取後更新狀態旗標 → 非唯讀 → 標註

步驟 2：影響面追蹤

這一步最費工，但也最值得。你要回答：同版本的其他程式碼會不會受到影響？

具體操作：

1. 找出呼叫同一個 API 端點的所有呼叫方
2. 對每個呼叫方，確認它處理回傳值的方式是否為唯讀
3. 對涉及資料庫的部分，找出所有讀取該資料表的位置，確認它們是否會在讀取同時進行寫入操作
4. 對涉及共享狀態的部分，找出所有讀取該狀態的位置，確認是否有併發修改

檢查清單：

• 哪些 API 端點從這個模組回傳資料？
• 哪些程式碼直接讀取這個資料表的欄位？
• 哪些模組共享這個狀態旗標／快取鍵值？
• 是否有排程任務或 webhook 會修改我觸及的狀態？

步驟 3：狀態確認（CHECKSUM 比對）

這一步是為了確認你現在看到的資料沒有被其他人改掉。

具體操作：

1. 在你開始檢查之前，先為關鍵資料建立指紋
2. 檢查過程中，如果遇到非唯讀操作，停下來，重新建立指紋
3. 最後，比對指紋，確認資料沒有被中間步驟篡改

# 方式一：直接檔案指紋
md5sum config.yaml > /tmp/config-before.md5
# ... 你的檢查和抖動 ...
md5sum config.yaml > /tmp/config-after.md5
diff /tmp/config-before.md5 /tmp/config-after.md5

# 方式二：時間戳記比對
stat -c "%Y %n" config.yaml  # Linux
stat -f "%m %N" config.yaml  # macOS

常見陷阱

1. 只做靜態檢查，不做動態追蹤 — 靜態分析只能看到程式碼裡寫了什麼，看不到執行時實際會觸發什麼
2. 漏掉非同步/webhook/排程任務 — 這些不在主呼叫鏈上，你最容易漏掉
3. 指紋建立的時間點不對 — 你在檢查的過程中建立指紋，但看起來是檢查完之後的資料，實際上你漏掉了中間那次修改
4. 把唯讀和「不改檔案」混為一談 — 讀取可能修改快取、健康檢查旗標、session 狀態，這不是「改动檔案」，但確實是非唯讀操作
5. 用唯讀驗證代替回歸測試 — 唯讀驗證確認你的檢查時機正確，但不能確認你的改動正確。兩者都不能省

最小可用檢查清單

開始檢查之前：

• 列出所有我要觸及的模組
• 對每個讀取位置判斷唯讀／非唯讀
• 找出同層的上游呼叫者
• 確認是否有排程任務/webhook 觸及我關注的資料
• 建立資料指紋

檢查過程中：

• 每次發現非唯讀操作就停下
• 重新建立指紋，確認時間軸

檢查完成後：

• 指紋比對一致
• 已標註所有非唯讀位置
• 你的判斷和你看到的架構一致，沒有遺漏

檢查後與開發流程的關係

唯讀驗證是開發規劃前的第一道關卡。它不告訴你的改動對不對，它只告訴你你的認知和你的目標系統是否一致。

這就是為什麼它很重要：在 AI 撰寫程式碼的範式裡，你對架構的了解能從「你記得多少」變成「你查到了多少」。唯讀驗證就是「你查到了多少」的檢查清單。