AGENTS.md 完整指南3步快速创建一份 AI 编码代理配置文件【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md 为什么 AI 改的代码总不守你项目的规矩让 AI 代理修一个 bug它为了验证改动顺手跑了一次npm run build——生产构建覆盖了开发产物热更新直接失效开发服务器状态全乱你只能重启重来。这类事其实可以提前拦下AGENTS.md 是一个简单、开放的 AI 编码代理引导格式相当于给 AI 写的 README把项目规矩放在一个固定位置适合任何在用 AI 工具协作开发的程序员。 它解决什么问题指令分散构建命令在 README、测试说明在 CI 文档、PR 规范只在团队聊天里代理只能靠碰运气找到README 是写给人看的把代理需要的详细步骤全塞进去README 会变得又长又难读各家工具各有各的配置文件换一个工具就要重新配置一遍AGENTS.md 是一个被众多主流代理识别的单一文件这个格式目前已被 6 万多个开源项目采用。 核心机制给 AI 发一本新人入职手册设计思路一句话概括在仓库里放一个没有必填字段、完全开放的 Markdown 文件代理开工时会自动读取它。这就好比实习生入职你不需要让他自己猜团队习惯而是第一天发一本手册写清楚环境怎么起、测试在哪跑、哪些坑别踩。AGENTS.md 就是这本手册只是读者是 AI 代理。标题结构完全由你定代理按你写的文本解析执行。✍️ 3步创建 AGENTS.md建文件在仓库根目录新建 AGENTS.md。想省事的话可以直接让 AI 工具扫一遍项目帮你生成初稿写重点没有必填字段建议覆盖项目概览、构建与测试命令、代码风格、测试说明、安全注意事项提交并用起来大多数代理会自动读取个别工具需要显式声明比如 Aider 在.aider.conf.yml里加一行read: AGENTS.mdGemini CLI 则在.gemini/settings.json里把AGENTS.md设为上下文文件 进阶单文件不够用时怎么扩展单仓多用嵌套 AGENTS.md在每个子包里再放一份 AGENTS.md代理会自动读取目录树中最近的那个文件最近的优先——每个子项目都能有自己的专属规则。OpenAI 的主仓库里就有 88 个 AGENTS.md 文件。让代理自己跑测试把测试命令写进 AGENTS.md 后代理会在收尾前主动执行相关检查失败时先修复再交付。迁移已有文件如果你之前写的是 AGENT.md 之类的文件可以重命名后留一个软链接保持兼容ln -s AGENTS.md AGENT.md。⚠️ 常见踩坑点与规避方法让代理在会话里跑生产构建这个仓库自己的 AGENTS.md 就把这条列为第一条规矩——build会禁用热更新并让开发服务器处于不一致状态迭代时只用 dev server生产构建放到普通终端里做改了依赖没同步锁文件代理新增依赖后要更新pnpm-lock.yaml这类锁文件并重启 dev server把这条写进 AGENTS.md代理每次都会照做文件写旧了把 AGENTS.md 当活文档维护改命令或改约定时同一个提交里更新它否则代理会继续按过期指令办事一份 Markdown 文件就能让任何代理都拿到这个项目怎么干活的说明书。README.md 里有一份最小示例可以照着改官方站点 agents.md 上还能看到更多真实案例和兼容工具清单。【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考