如果一個檔案會改變 agent 怎麼讀你的 repo、怎麼下手改 code、怎麼判斷任務完成，這個檔案就已經不是提示詞備忘錄了。
它是基礎設施。
這件事一開始很容易被低估。很多人看到 AGENTS.md、CLAUDE.md 或各種 agent rules，第一個反應是：「喔，這是給 AI 看的 prompt。」於是內容就寫成個人筆記：請用 TypeScript、請保持簡潔、請先跑測試、不要亂改。
這些句子本身沒錯。
問題是，當 coding agent 開始真的讀 repo、改 repo、送 PR，這些句子就不是「讓 AI 聽話」的技巧而已。它們會影響團隊開發流程。誰可以改？改了要不要 review？過期了誰負責？跟 CI、lint、測試命令衝突時，以誰為準？
如果這些問題沒有答案，AGENTS.md 只是看起來很現代的團隊迷信。
個人 prompt 很自由。你今天想叫 agent 用什麼口氣回覆、先解釋還是先改檔、要不要多問問題，都可以臨場調整。這對單人使用很舒服。
團隊 repo 不一樣。
團隊 repo 裡的規則，一旦被 agent 讀到，就會變成可重複執行的行為偏好。它可能決定 agent 優先看哪個目錄，哪些檔案不能碰，遇到測試失敗要重試幾次，提交前要留下什麼證據。
這已經不是聊天技巧。
這比較接近 package.json script、CI workflow、lint config、CODEOWNERS，或開發環境設定。它不一定會直接編譯 code，但它會影響 code 怎麼被修改。
所以我會用一個很粗暴的判斷標準。
只要某份 agent instructions 會影響多人協作結果，它就應該進 repo governance，而不是留在個人 prompt 資料夾。
一份好的 AGENTS.md 不應該是願望清單。
它應該回答幾個工程問題。
第一，agent 進 repo 後要先看哪裡。是 README？是架構文件？是特定模組的 design note？還是先找最近相關測試？
第二，這個專案有哪些不能靠直覺猜的慣例。例如錯誤處理方式、API contract、資料庫 migration 規則、UI component 的使用界線、測試命名習慣。
第三，哪些地方預設不能碰。付款、權限、資料刪除、schema migration、加密、部署設定，這些不該因為 agent 覺得「順手修一下」就被包進同一個 diff。
第四，完成的定義是什麼。只是改完檔案不算完成。需要跑哪些命令？需要補測試嗎？如果測試環境壞掉，要留下什麼訊息？如果超出範圍，要不要停下來？
第五，reviewer 要看到什麼證據。Agent PR 最糟的狀況不是 code 明顯壞掉，而是它看起來很合理，卻不知道中間採用了哪些假設。
這些內容寫清楚，agent 才比較像在接工作單，而不是在讀一份禮貌提醒。
我最擔心的不是 repo 沒有 AGENTS.md。
更麻煩的是 repo 有一份，但沒有人把它當真的。
一開始大家很興奮，寫了十幾條規則。三個月後，測試命令改了，目錄拆了，部署流程換了，某個舊模組已經不該再碰，但 agent rules 還停在舊版本。新人以為這份檔案代表團隊共識，agent 也照著讀，最後只是把過期慣例自動化。
這比沒有規則還危險一點。
沒有規則時，你至少知道 agent 在猜。有一份過期規則時，你會誤以為它有脈絡。這才麻煩。
工程裡很多事故不是來自「完全沒有流程」，而是來自「大家以為流程還有效」。Agent config 也會遇到同樣的問題。
比較務實的做法，是把 AGENTS.md 當成 repo 內的一種基礎設施檔案。
不用搞得很官僚，但至少要有幾個底線。
先指定 owner。不是說只有 owner 能改，而是有人要對它是否過期負責。小團隊可以是 tech lead，大一點的團隊可以讓各模組 owner 維護自己的段落。
修改要走 PR。因為改 agent rules 不是改文件排版，它可能影響之後每一次 agent 任務。尤其是新增允許範圍、修改測試命令、放寬停止條件，都值得被看一眼。
內容要小步調整。不要一次寫成一篇團隊憲法。先把最常用、最容易出事、最能驗證的規則放進去。像是「這個 repo 的主要驗證命令」、「哪些路徑只能讀不能改」、「遇到跨模組影響時要停止回報」。
也要把失敗回填。某次 agent PR 因為沒有跑 migration test 出事，那就不要只罵工具。把規則補進去。某次 agent 碰了權限邏輯，那就把禁止範圍寫清楚。AGENTS.md 最有價值的部分，常常不是一開始想出來的，而是從真實失敗裡長出來的。
還有一點很容易被忽略：讓它跟 CI 和文件一起演進。Agent rules 說要跑 pnpm test，但 repo 實際上已經拆成 pnpm test:unit 和 pnpm test:e2e，這不是小事。Agent 會照著舊命令浪費時間，reviewer 也會看到一份看似完整、其實沒有對上風險的驗證報告。
有人會覺得這太像大公司治理。
我反而覺得小團隊、接案團隊、維護很多 side project 的工程師更需要。
大公司至少有流程、有 owner、有 reviewer，也有一堆會讓人煩但會擋事故的制度。小團隊常常靠默契活著。某個 helper 為什麼不能改，某個 API 為什麼不能順手整理，某段測試為什麼只跑單元測試不夠，這些都在人的腦袋裡。
Agent 最不會讀的，就是腦袋裡的默契。
把這些默契整理成 repo 內的 agent contract，不是為了追流行。是因為你遲早會把某些工作交給 agent，而 agent 不會自動知道這個專案多年累積下來的坑。
你可以把 AGENTS.md 寫得很短。
但它最好是活的、有人管的、能被 review 的。
我越來越不相信「提示詞模板大全」會是 coding agent 團隊化使用的核心。
模板有用，但它太個人、太臨場、太難驗證。真正會留下來的，是那些能放進 repo、能版本控制、能跟 CI 和 review 流程接起來的東西。
以後判斷一個團隊會不會用 coding agent，我不會只看它有沒有買最強模型，也不會看它收藏了多少 prompt。
我會看它有沒有把 agent 行為變成可以共同維護的 repo 契約。
因為一旦 agent 開始改你的 codebase，問題就不再是「它聽不聽話」。
真正的問題是：這個團隊有沒有把「它該怎麼工作」變成工程系統的一部分。
AGENTS.md 如果只是提示詞備忘錄，價值很有限。
但如果它被 owner 維護、被 PR review、跟測試命令一起更新、從失敗案例裡修正，它就會變成一個很普通、也很重要的東西。
普通到像 lint config。
重要到你不該讓它隨便過期。
ryanvale
iThome鐵人賽
看影片追技術