AGENTS.md最小化实践：让AI代理与项目知识随仓库自然成长

Hacker News 上有人问过一个问题有没有人试过先写一份尽量小的 AGENTS.md然后让它随着仓库一起长大我第一次认真写 AGENTS.md并不是因为看到了这个问题而是因为同一个 AI 编程代理在同一个仓库里连续三次把测试命令猜错。那是一个很小的 Python 数据仓库用 pytest 跑测试但测试环境需要先执行一个初始化脚本。代理每次都会在仓库根目录直接运行 pytest然后被一堆环境相关的失败卡住。它并不是不努力只是每次进入仓库都像第一次进来不知道项目命令的入口在哪不知道目录约定也不清楚哪些操作不应该碰。我当时的处理方式很朴素在仓库根目录写了一个 7 行的 AGENTS.md写清楚三件事这个项目是什么、测试入口在哪、有哪些规则不要违反。效果立竿见影代理的行为立刻就稳定了。但后来的事情值得警醒。团队开始往这个文件里不断补充内容从架构说明写到编码规范再从编码规范写到部署细节最后它变成一份三百多行的“项目百科全书”。代理每次执行任务都要先读一遍结果常常被一些和当前任务无关的上下文带偏行为反而不如之前稳定。这时候我才意识到AGENTS.md 的关键问题从来不是“要不要写”而是“怎么让一份文件既保持最小又能随仓库成长”。这篇文章我想聊聊这个问题的实践答案。以下内容主要来自个人工程经验不是一个官方规范也不绑定某个特定 AI 工具但它适用于大多数使用 AI 编程代理来处理仓库任务的工作流。1. AGENTS.md 解决的不是“让 AI 听话”而是“让项目知识可复用”1.1 AI 代理为什么需要在仓库里有一份“工作