Hacker News 上有人問過一個問題有沒有人試過先寫一份盡量小的 AGENTS.md然后讓它隨著倉庫一起長大我第一次認真寫 AGENTS.md并不是因為看到了這個問題而是因為同一個 AI 編程代理在同一個倉庫里連續三次把測試命令猜錯。那是一個很小的 Python 數據倉庫用 pytest 跑測試但測試環境需要先執行一個初始化腳本。代理每次都會在倉庫根目錄直接運行 pytest然后被一堆環境相關的失敗卡住。它并不是不努力只是每次進入倉庫都像第一次進來不知道項目命令的入口在哪不知道目錄約定也不清楚哪些操作不應該碰。我當時的處理方式很樸素在倉庫根目錄寫了一個 7 行的 AGENTS.md寫清楚三件事這個項目是什么、測試入口在哪、有哪些規則不要違反。效果立竿見影代理的行為立刻就穩定了。但后來的事情值得警醒。團隊開始往這個文件里不斷補充內容從架構說明寫到編碼規范再從編碼規范寫到部署細節最后它變成一份三百多行的“項目百科全書”。代理每次執行任務都要先讀一遍結果常常被一些和當前任務無關的上下文帶偏行為反而不如之前穩定。這時候我才意識到AGENTS.md 的關鍵問題從來不是“要不要寫”而是“怎么讓一份文件既保持最小又能隨倉庫成長”。這篇文章我想聊聊這個問題的實踐答案。以下內容主要來自個人工程經驗不是一個官方規范也不綁定某個特定 AI 工具但它適用于大多數使用 AI 編程代理來處理倉庫任務的工作流。1. AGENTS.md 解決的不是“讓 AI 聽話”而是“讓項目知識可復用”1.1 AI 代理為什么需要在倉庫里有一份“工作