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

具體情境

你要為新環境部署設定變更，或是在執行緒中讓 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 撰寫程式碼的範式裡，你對架構的了解能從「你記得多少」變成「你查到了多少」。唯讀驗證就是「你查到了多少」的檢查清單。