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