前言：文件漂移，能不能靠自動化偵測？

Day 04 講過 README 沒跟上程式碼，Day 17 講過徽章沒跟上實際 CI。今天討論一個更根本的問題：這種文件漂移能不能靠自動化偵測，而不是永遠靠人（或 AI）想起來才回頭補？

今日目標

• 想清楚「文件漂移」這件事，有哪一部分是可以被自動化檢查抓到的
• 用一個具體構想示範：怎麼檢查 README 提到的付款方式，是否涵蓋所有測試裡出現過的情境
• 理解這種自動化檢查的侷限——它能抓「漏講了什麼」，抓不到「講錯了什麼」
• 誠實面對：這是一個構想層級的討論，不是這個系列已經做出來的工具

一個具體構想：拿測試案例反查 README

Day 04 提過，tests/Message/PurchaseRequestTest.php 裡的測試方法名稱（testGetData、testATMGetData、testBNPLGetData、testFlexibleInstallmentGetData）其實比 README 更準確地反映了這個套件支援的付款方式。這代表一件事：測試程式碼裡，實際上藏著一份「目前支援哪些情境」的清單，只是沒有人把它抽取出來跟 README 對照。

一個可行的自動化檢查構想：

1. 掃描測試檔案裡出現過的 ChoosePayment 賦值（例如 'Credit'、'ATM'、'BNPL'）
2. 掃描 README 裡有沒有提到對應的付款方式名稱
3. 如果測試裡出現了 README 沒提到的付款方式，讓 CI 印出一則警告（不一定要讓建置失敗，先讓它「被看見」）

這不需要多複雜的工具，一個幾十行的 shell script 或小型 PHP script 就能做到「掃描 + 比對 + 印警告」這三個步驟。

❌ vs ✅：兩種發現文件漂移的方式

❌ 現況：靠人類（或 AI）自己想起來要去對照
新增 BNPL 功能的 commit 裡,程式碼跟測試都補齊了,
但沒有人想到要回頭看一眼 README 是不是也該更新
→ 漂移持續累積，直到某天有人抱怨「文件跟實際不符」

✅ 構想：CI 裡加一個自動比對步驟
每次 push,自動掃描測試裡出現的 ChoosePayment 值,
跟 README 裡提到的付款方式清單做比對,
不一致就在 CI log 裡印出警告

→ 漂移在下一次 push 就會「被看見」,不用等別人抱怨

正例不保證漂移會被立刻修正——畢竟只是印警告，沒有人規定看到警告一定要處理。但至少把「被看見」這件事從『靠運氣、靠有心人回頭檢查』,變成『每次 push 都自動發生』，這是自動化檢查真正能提供的價值：不是取代人的判斷,是確保漏掉的東西至少有機會被看到。

這種自動化檢查抓得到什麼、抓不到什麼

抓得到：「測試裡有,但 README 沒提到」這種明確的缺漏——因為這是結構化的比對，兩邊的資料都能被程式解析。

抓不到：README 裡某段描述「講得不夠清楚」或「講錯了」——例如 Day 04 提到的骨架範本提示語沒被換掉,這種問題沒有一個明確的「正確答案」可以拿來自動比對,只能靠人去讀、去判斷寫得好不好。自動化檢查能解決的是『有沒有』的問題，解決不了『好不好』的問題——這也是為什麼即使做了這個構想,還是不能完全取代人（或請 AI 幫忙）定期通讀一次 README 的必要性。

今日思考題

如果你的專案也有類似的文件（README、CHANGELOG、API 文件），有沒有哪一種漂移是可以用「掃描程式碼/測試 + 自動比對」的方式抓到的？哪一種只能靠人定期通讀才抓得到？

今日重點回顧

• 測試程式碼裡往往藏著一份「目前實際支援什麼」的清單，可以拿來反查 README 有沒有漏講
• 自動化檢查的價值不是取代人的判斷，是讓漏掉的東西不用靠運氣才被看見
• 這種檢查抓得到「有沒有」的缺漏，抓不到「好不好」的表達問題
• 這是一個構想層級的討論，這個系列裡沒有真的把它做成工具

明日預告

明天回頭看 Day 19 那份在暫存複本上跑出來的 PHPStan 結果——如果真的把它常態化跑起來（例如接進 CI 的非阻斷步驟），日後會持續冒出什麼類型的新警告？