前言：改個 badge 而已，能有什麼風險？

「不過是把 README 裡一個徽章的圖示網址換掉，這種瑣事直接交給 AI 處理就好了吧？」

昨天走完一個到現在還沒解答的真實 bug（issue #430），今天要換一種完全不同的維護工作：寫文件。乍聽之下，改 README、修 badge 這類事情風險最低——不會影響程式邏輯、不會讓使用者的專案跑不起來。但 PHPUnit & Pest Test Explorer 這個專案裡剛好有一組真實紀錄，正好說明「文件維護」這件事沒有表面看起來那麼無害。

今日目標

• 看兩個真實的文件修復 PR，理解「文件」這個詞底下其實藏著好幾份不同用途的檔案
• 認識「改對了地方」跟「改到了實際生效的地方」是兩件不同的事
• 學會判斷一份文件改動的「實際生效範圍」，而不是只看檔名像不像
• 建立「看起來多餘的資源，動手刪之前先查證用途」的習慣

真實案例：兩次才修好的一個 badge 問題

PHPUnit & Pest Test Explorer 這個專案在 PR #422 裡處理了一個問題：shields.io 這個徽章服務把 vscode-marketplace 這個徽章分類下架了，導致 README 上原本顯示版本號、安裝次數的徽章，全部變成一個通用的「已停用」佔位圖，不再顯示真實資料。解法是把徽章來源換成社群維護的替代服務 vsmarketplacebadges.dev。

這個 PR 改完，README 上的徽章確實恢復正常了——但只改對了根目錄的 README。一個半小時後補上的 PR #425 才發現：這個專案真正發布到 VS Code Marketplace 上、使用者在商店頁面實際看到的那份 README，其實放在 packages/extension/README.md 這個子目錄裡，而且還有一份繁體中文版本——這兩份檔案當時完全沒被 PR #422 動到，一樣還在顯示已停用的徽章。

為什麼「文件」不是單一檔案這麼簡單

問題不是 PR #422 改錯了地方，而是它只改了「看起來合理」的地方——根目錄的 README 通常是專案首頁，直覺上就是「這個專案的文件」。但一個實際會發佈上架的 VS Code 擴充套件，可能同時存在好幾份 README：給 GitHub 首頁看的、給套件市集看的、給不同語系使用者看的，各自的用途、各自實際被誰讀到，完全不一樣。

用一組對照來看這個差異：

❌ 只改「看起來是文件」的那一份：
「README.md 修好了，徽章顯示正常，這個問題解決了。」
→ 沒有先確認這個專案有幾份 README、
  哪一份是實際發布到市集、使用者真正會看到的那份

✅ 先確認文件的實際生效範圍：
「這個專案裡搜尋所有 README.md，確認一共有幾份、
 各自服務什麼場景（GitHub 首頁 / Marketplace 上架頁 / 多語系版本），
 逐一檢查是不是都需要同步修改。」
→ 修改前先確認「這份文件實際上會被誰看到」，
  而不是只改了看起來最直覺的那一份

這正是這個系列反覆講的同一個模式的另一種樣貌：AI 對著「README 修好了」這句話給出的信心，其實只涵蓋了它改過的那一份檔案，沒有涵蓋這個專案裡所有名叫或扮演 README 角色的檔案。「文件改完了」跟「所有使用者實際會看到的文件都改完了」中間，一樣隔著一段查證範圍的落差。

順手一提：一個「看起來多餘」但不能刪的檔案

PR #425 的說明裡還留了一個值得記住的細節：這個專案的根目錄有一個 img/icon.png，乍看像是跟其他地方重複的資源檔案，但 PR 描述裡特別註明——這個檔案不是該清掉的重複檔案，因為 PestPHP 官方文件的編輯器設定頁面，寫死引用了這個檔案在 GitHub 上的原始網址。如果把它刪掉或搬到別的位置，會直接讓一個外部網站上顯示的圖示壞掉。

這跟前面幾天講過的「沒被引用不等於死碼，刪之前先問」是同一件事，只是這次的「引用」不在程式碼裡，而在一個外部網站的原始碼裡——AI 光看這個專案自己的程式碼庫，完全看不出這層依賴關係。

AI 適合做這類瑣事的哪個部分

回到今天的主題：讓 AI 處理 README/badge 這類文件維護，效益是真實的——這類改動機械、重複、容易做但也容易漏，AI 可以快速找出「這個專案裡有哪些檔案符合 README 的樣式」「這個徽章連結目前指向哪個服務」這類窮舉性的查核工作。但風險也同樣真實：AI 容易把「找到了一份看起來相關的檔案並改好它」，當成「這個問題解決了」，而不會主動去確認「這個專案裡是不是還有其他份扮演同樣角色的文件」。

具體的做法是：交給 AI 處理文件維護時，明確要求它先列出「這個專案裡有幾份 README/文件會被外部看到、各自的用途是什麼」，再逐一確認要不要修改，而不是找到第一份符合條件的檔案就直接動手改完回報完成。

今日思考題

回想你維護過的專案：有沒有超過一份的 README、文件、或設定檔，各自服務不同的場景（GitHub、套件市集、CI、不同語系）？如果現在要改一個顯示相關的設定，你有把握一次就想到所有需要同步修改的地方嗎？

今日重點回顧

• PHPUnit & Pest Test Explorer 的徽章修復分兩次 PR 才完成：第一次只改了根目錄 README，約一個半小時後才發現真正發布上架的那份 README 在子目錄裡、完全沒被動到
• 「文件改好了」的信心，容易只涵蓋改動者實際碰過的那一份檔案，不涵蓋這個專案裡所有扮演同樣角色的文件
• 一個看起來多餘的圖示檔案，其實被外部網站寫死引用——刪之前先查證用途，不能只看這個專案自己的程式碼庫
• 讓 AI 處理文件瑣事時，先要求它列出「有幾份文件會被外部看到」，再逐一確認，而不是改完第一份就回報完成

明日預告

明天用另一個角度看文件維護的風險：AI 修文件時，怎麼「順手」把不該碰的地方也一起改壞了。