一个文件让 AI Coding 效率翻倍：AGENTS.md 实践指南
一个文件让 AI Coding 效率翻倍：AGENTS.md 实践指南
来源类型： 微信公众号文章
日期： 2026-06-02
标签： AI, 办公效率, 网络安全, 编程, 大模型
原文链接： https://mp.weixin.qq.com/s/fBBBSfQajYjYtngZAitZCA
摘要
阿里妹导读 文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。 前言 本文主要围绕一个具体的问题展开：怎么写好一份 AGENTS.md？ 「在代码仓库中放一份上下文文件，告诉 AI 工具这个项目是什么、怎么构建、有什么规矩」——这个做法现在已经有了一个统一的名字：AGENTS.md。在展开实践之前，先花一点篇幅介绍它的前世今生，已经了解的同学可以跳过。 AGENTS.md 是什么？ AGENTS.md 是一个简单的开放格式，用于指导 AI Coding Agent 在你的项目中工作。你可以把它理解为给 AI 看的 README——README.md 是给...
核心内容
阿里妹导读
文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。
前言
本文主要围绕一个具体的问题展开：怎么写好一份 AGENTS.md？
「在代码仓库中放一份上下文文件，告诉 AI 工具这个项目是什么、怎么构建、有什么规矩」——这个做法现在已经有了一个统一的名字：AGENTS.md。在展开实践之前，先花一点篇幅介绍它的前世今生，已经了解的同学可以跳过。
AGENTS.md 是什么？
AGENTS.md 是一个简单的开放格式，用于指导 AI Coding Agent 在你的项目中工作。你可以把它理解为给 AI 看的 README——README.md 是给人类看的项目说明，AGENTS.md 则是给 AI Agent 看的项目指令，包含构建命令、编码规范、测试要求、安全注意事项等 AI 需要知道的上下文。
官方建议的使用方式很简单：
- 在仓库根目录创建一个 AGENTS.md 文件
- 写上对 Agent 有用的内容：项目概述、构建测试命令、代码风格、安全注意事项
- 补充额外指引：commit 规范、部署步骤、安全陷阱——任何你会告诉项目新成员的东西
- 大型 monorepo 可以在子目录放嵌套的 AGENTS.md，Agent 会读最近的那个（OpenAI 自己的仓库有 88 个 AGENTS.md）
格式上没有任何强制要求，就是标准的 Markdown，用什么标题、写什么内容完全自由。
前世今生
这个概念最早由 Anthropic 通过 Claude Code 的 CLAUDE.md 普及。Claude Code 运行时会自动加载当前目录下的 CLAUDE.md，把内容注入到发给模型的请求中。这个设计简单而有效——维护好一份上下文文件，Agent 的表现就会变好；表现变好了，你就更愿意用它，进而更愿意维护这份文件，形成正向循环。
随后各家 AI Coding 工具跟进了自己的版本，一度各自为政：
工具上下文文件Claude CodeCLAUDE.mdCursor.cursorrules / .cursor/rulesCopilot.github/copilot-instructions.mdGemini CLIGEMINI.mdCline.clinerulesAMP (Sourcegraph)AGENT.md（单数）OpenAI CodexAGENTS.md（复数）
这种碎片化意味着团队需要为不同工具维护多份内容相同的配置文件，改一次规则要同步好几个地方。
2025 年 5 月，Sourcegraph 旗下的 AMP 率先提议统一标准，建议用 AGENT.md（单数），并注册了 agent.md 域名。随后 OpenAI 宣布买下了 agents.md 域名，提议用 AGENTS.md（复数），理由是多个 Agent 会共用同一份配置。AMP 随即主动让步对齐，将 agent.md 重定向到 agents.md。
最终 AGENTS.md 成为事实标准，由 Linux Foundation 下属的 Agentic AI Foundation 托管。截至 2026 年初，GitHub 上已有超过 6 万个开源项目使用这个格式。Cursor、Kiro、灵码、Qoder、Copilot 等主流工具均已支持。Claude Code 虽然仍用 CLAUDE.md，但内容完全通用，一个软链接即可兼容：ln -s AGENTS.md CLAUDE.md。
过去半年里，我为手头的多个项目都维护了 AGENTS.md——有管控系统、有内核引擎代码、有产品基线、也有文档系统。不同项目的技术栈、仓库结构、团队规模各不相同，但在 AGENTS.md 的实践上逐渐收敛到了一套相似的方法论。这篇文章我挑了其中投入最多、也最通用的一个场景——管控系统（Spring Boot + React 的前后端分离项目）来展开介绍，希望对正在写或者想写 AGENTS.md 的同学有参考价值。
没有 AGENTS.md 的日子
在聊怎么写之前，先说说为什么要写。
管控系统项目最初引入 AI Coding 工具时，我的体感是：有了 AI，但效率提升远没有预期那么大。问题不在工具本身，而在于项目对 AI 不友好。回头看，痛点集中在以下几个方面：
前后端上下文割裂
最初后端和前端分属不同的 Git 仓库。AI Coding 时只能打开一个仓库，改一个涉及前后端联动的功能——比如后端新增一个接口，前端加一个对应的页面——需要在两个窗口之间来回切换。切换的过程中 AI 丢失上下文，你得重新描述一遍背景，效率很低。
后来我把前端仓库直接放到了后端仓库的子目录下，再后来干脆重构成了 monorepo。配合 AGENTS.md 中维护的项目结构说明，AI 在同一个窗口中就能看到 Controller 定义和对应的前端 API 调用。效果立竿见影——团队现在已经不区分前后端了，大家就是在一个仓库里提交代码，AI 也是在一个上下文里全栈编码。
AI 不认识私域组件
项目前端大量使用了私域组件库（ProTable、ProForm、ProAction 等），这些组件是闭源的，AI 工具的训练数据里没有，也查不到公开文档。最初我维护了一些私域组件的使用文档给 AI 参考，但文档总是滞后于实现，AI 写出来的代码经常用错 prop 或者漏掉必要的配置。
后来我直接把私域组件库的源码放到了参考项目中。AI 不会写私域组件的代码时，可以直接读源码里的 TypeScript 定义和实现——源码永远不会过时，它就是最准确的文档。这个改变之后，AI 写前端代码的质量有了质的提升。
AI 不知道项目的规矩
每个项目都有自己的编码规约——异常必须通过统一的 BusinessException 抛出而不是直接抛 RuntimeException、响应体由框架统一包装禁止手动构造、分层架构禁止跨层依赖。这些规矩在团队成员脑子里，但 AI 不知道。
结果就是 AI 写出来的代码风格五花八门：有时候直接
throw new RuntimeException()，有时候用项目约定的 BusinessException；有时候手动 new Response(code, data) 包装返回值，有时候又不包；Controller 里直接注入 Repository 跳过 Service 层的情况也时有发生。每次都要人工纠正，纠正完下次还犯。
AI 不会启动项目、不会自测
AI 改完代码之后，它不知道怎么构建、怎么启动、怎么验证。每个人的本地环境配置方式不统一，启动命令散落在各种文档和聊天记录里。AI 只能把代码改完就停下来，等人手动验证。
这意味着 AI 的工作闭环是断裂的——它只能完成「改代码」这一步，「构建 → 启动 → 验证 → 修复」这个循环全靠人来驱动。夜间让 Agent 自主执行？不可能，因为它连项目都启动不了。
痛点总结
归纳一下，这些痛点的共同根源是：**项目的知识和规范存在于人的脑子里，而不是存在于
...(内容截断，完整内容请查看原文)
本页由自动化脚本生成，待人工审核补充