前言：改 README 應該是最安全的任務吧？

「這個 issue 只是要求把 README 裡的預設值寫錯的地方改一下，交給 AI 處理應該零風險吧？」

Day 11 講過，文件維護是 AI 很適合的機械性工作——語法檢查、連結有效性、範例格式一致，這些事 AI 做得又快又準。但今天要講一個容易被忽略的陷阱：「文件」跟「程式碼」在 legacy 或半自動化的專案裡，常常不是兩份互相獨立的東西，而是共用同一份「事實來源」——只是這份事實來源用了兩種形式存在。AI 只改了看得到的那一種形式，另一種悄悄脫節了。

今日目標

• 理解為什麼「只是改文件」有時候風險比看起來高
• 認識「文件跟程式碼共用事實來源」這種依賴關係的具體樣貌
• 看一個以真實專案設定為基礎、去識別化改寫的示範情境
• 建立「改文件前先問：這份內容還有沒有第二個副本」的習慣

案例（示範情境，非真實發生過的事）：一段設定範例的兩個副本

先說明清楚：以下情境是我根據 PHPUnit & Pest Test Explorer 這個專案真實的 README 結構設計的示範案例，用來說明一類真實會發生的風險，不是這個專案實際踩過的事故——查了這個專案近期的文件相關 PR（例如修正 marketplace 徽章顯示異常的那幾支），都是維護者本人處理、範圍單純，沒有找到「文件改動意外波及程式碼」的真實紀錄，所以誠實用示範情境呈現，而不是硬套一個不存在的案例。

這個專案的 README 裡，有一段說明使用者怎麼在 .vscode/settings.json 設定自訂執行指令的範例，裡面列出了像 ${workspaceFolder}、${cwd} 這類可用的變數，並附帶說明每個變數代表什麼路徑。這份說明不是憑空寫的——它對應到原始碼裡一段實際負責解析這些變數的邏輯，兩者理論上該永遠同步。

假設有一個 issue 說「README 裡 ${cwd} 變數的說明寫得不清楚，容易誤會」，AI 被要求去把這段描述改得更清楚。AI 讀懂了 issue、改好了 README 的文字敘述，PR 也順利通過（畢竟只是文字，沒有測試在盯著文件本身）。但它沒有意識到：原始碼裡那段解析邏輯的行內註解，用的是舊版的描述方式，兩邊原本應該保持一致的說法，現在不一致了——不是程式壞了，是「文件說的」跟「程式碼自己記錄的說明」開始各說各話。

❌ 只改看得見的那一份：
「README 裡這段變數說明寫得不清楚，已經改好了。」
→ 只查證了 README 這一份文字，沒有搜尋這份說明
  是不是還有其他地方（原始碼註解、測試案例的說明字串）
  重複描述了同一件事

✅ 先確認事實來源的副本數量：
「這段變數說明在 README 裡，也在
 packages/extension/src/... 的行內註解裡重複出現，
 已經一併同步更新兩處，並確認兩邊敘述用詞一致。」
→ 先搜尋「這句話」還有沒有第二個副本，
  再決定要不要一起改

這正是這個系列反覆出現的模式的另一種樣貌：AI 對「我改的這個地方」很有信心，但它從來沒有查證過「這件事還有沒有第二個副本、我漏掉的那一份現在跟我改的這份還一不一致」。 文件因為看起來「不會壞掉」（不會讓 CI 燒紅），這種脫節特別容易被放過——沒有一個自動化機制會在文件跟程式碼的敘述不一致時發出警告，只有下一個讀者對照兩邊時才會發現。

怎麼降低這種風險

具體做法不複雜：改動任何一段敘述性內容前，先用關鍵字搜尋整個程式碼庫（不只是 README 本身），確認這段內容是不是有其他副本——原始碼註解、其他語言版本的 README、測試案例裡的說明字串，都算。如果找到多個副本，要嘛一次全部同步，要嘛在 PR 描述裡明確標注「這裡還有 N 處類似敘述，這次只改了其中一處，原因是 X」，讓 review 的人知道這是刻意的取捨，不是漏掉。

今日思考題

回想你維護的專案裡：有沒有一段說明文字，同時存在於 README、程式碼註解、甚至測試案例的描述字串裡？如果現在要修正其中一份，你有把握能一次找齊所有副本嗎？

今日重點回顧

• 文件維護的風險不在「文件本身會不會壞」，而在「文件是不是某個事實來源的其中一份副本」
• AI 改文件時容易只查證看得見的那一處，沒有搜尋是否還有其他副本
• 沒有自動化機制會在文件跟程式碼敘述不一致時發出警告，脫節只能靠人工比對發現
• 具體做法：改動敘述性內容前先搜尋整個程式碼庫確認副本數量，找到多處要嘛一起改、要嘛在 PR 裡明講取捨

明日預告

明天要換一種維護工作：依賴升級。讓 AI 處理 dependency bump 這件事聽起來很適合自動化，但背後藏著什麼具體流程跟風險，明天講清楚。