如果大家都用过AI工具做开发那肯定就会知道同一个 AI在 A 项目里懂事得离谱到了 B 项目就像第一天上班。我一开始以为是自己没调好。后来发现差别不在它在项目——A 项目的根目录里躺着一个 AGENTS.mdB 项目里什么都没有。这个文件今年扩散得很快六万多个开源项目的根目录里有它OpenAI 自己的仓库里放了 88 份。Codex、Cursor、VS Code、Windsurf、Jules、Amp 这些都认Claude Code 那边叫 CLAUDE.md内容基本能照搬。它不是提示词是入职文档提示词是你每次对话时敲的那句话说完就没了。AGENTS.md 写在项目里只要在这个目录下开工它每次都先读一遍。打个比方提示词是这顿饭怎么做AGENTS.md 是我们厨房的规矩——火别开太大盐在左边第二个柜子用完的锅自己刷。新人入职要给他一份文档AI 也一样。区别在于新人会问AI 不问。你没写的部分它自己猜猜错了还特别自信。该写什么五样东西按性价比从高到低排一、项目是什么。一句话讲清楚带上技术栈。别写这是一个综合性管理平台要写运输调度平台Node MySQL前端 Vue3客户端是微信小程序。它得先知道自己在什么系统里才不会给你推荐一套别的技术栈的写法。二、常用命令。我认为这条最值。构建、启动、测试三条命令写上去它就不用每次去翻 package.json 猜。我以前最烦的是它自作聪明跑构建生产包——那是我们 CI 上用的本地跑一次就会覆盖掉本地配置。写进文件之后这种事再没发生过。三、代码约定。接口怎么返回、目录怎么分、哪些库能用。挑最容易被它违反的三四条写不用写全。四、别动什么。哪些目录在迁移中、哪些文件是生成的、哪些配置不在仓库里。这条是防它顺手帮你改一下的和给数据库账号只开只读权限是一个道理你不划边界它就按自己的理解来。五、历史遗留。项目里那些看着不合理但别碰的地方。比如某个状态字段的含义和字面完全不一样改之前先去看 migrations 目录。一份能直接抄的# 项目 运输调度平台。Node.js Express MySQL2前端 Vue3客户端是微信小程序。 # 常用命令 npm run dev # 起本地服务 npm run test # 跑单测 npm run build # 构建前端 # 约定 - 接口走 /api统一返回 { code, data, msg } - 改表必须写迁移脚本不能直接改 - 新接口在 routes/ 下注册别塞进 app.js # 别动 - /legacy 目录老调度逻辑迁移中 - 生产配置在服务器上仓库里没有这是我某个项目里的精简版。抄的时候把命令换成你自己的结构照搬就行。也别被精简两个字框住——真实项目里它可能比 README 还长。Apache Airflow 那份 AGENTS.md 有五百多行从命名规范一路写到每个脚本怎么跑。你的项目什么规模它就什么规模。两种写了等于没写的第一种写愿望。请写出高质量、可维护、符合最佳实践的代码。 注意代码规范保持风格一致。它读完不会有任何行为变化因为这些词没法执行。能执行的是具体动作“改完跑一次单测”、“接口返回统一用 { code, data, msg }”、“别用 any”。第二种把 README 复制一遍。我第一版就干了这个事项目背景、需求说明、接口清单全塞进去写了长长一大篇。结果是它每次对话都要先读这一大坨真正要遵守的那几条反而被淹掉。这个文件是给 AI 读的不是给人做汇报的。我现在控制在 30 行以内超过的部分说明放错了地方。还有一件事它会过期项目改了文件没跟着改它就开始误导。我的做法是动了构建流程或者目录结构顺手改这里和代码一起提交。不单独开一个更新文档的提交——那种提交你永远想不起来做。在你项目的根目录建一个 AGENTS.md先写三行就够这是什么项目、怎么跑起来、别动哪几个目录。剩下的等它犯错了再往上加。犯一次加一条比一开始就写满有用得多。