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