腾讯二面：你用了那么多的编程agent竟然不知道AGENTS.md，建议你回去好好复习一下

最近这段时间呢你要是有在用 Cursor、Claude Code、Codex 这些 AI 编程工具的话大概率应该见过一个新面孔。就是项目根目录下面多了一个叫 AGENTS.md 的文件。这个文件是干嘛用的呢它该怎么去写跟 Claude Code 专属的 CLAUDE.md 又是个什么关系别着急这篇文章咱们一次把它给讲清楚。一、AGENTS.md 到底是什么东西用一句话来概括的话呢AGENTS.md 就是写给 AI 编程智能体看的一份项目说明书。你看啊我们平时写的 README.md 是给人看的对不对。告诉新来的同事这个项目是干什么的、怎么跑起来之类的。而 AGENTS.md 呢它是给 AI 智能体看的。它告诉智能体什么呢◆用什么命令去构建、去测试这个项目◆代码风格和架构方面的约定是什么样的◆哪些地方是绝对不能去碰的比如说密钥啊、生产配置啊这些◆提交代码之前需要去跑哪些检查那有人可能会问了为什么要单独搞一个文件出来呢直接塞进 README 里不行吗其实原因是这样的有很多细节内容比如说精确的构建命令、测试流程、目录里面的一些坑之类的这些对人类贡献者来说其实算是噪音。但是对于 AI 智能体来说呢这些就是刚需了。所以说把这些内容给分离出来README 保持简洁就好了AGENTS.md 专门去服务智能体。这个格式最初是由 OpenAI Codex、Amp、Google Jules、Cursor、Factory 等好几家公司一起协作推出来的。目标是做一个开放的、通用的标准而不是说每家工具都自己去发明一套私有的格式。到目前为止呢它已经被 30 多种 AI 编程工具给支持了包括 OpenAI Codex、GitHub Copilot、Cursor、Gemini CLI、Google Jules、Factory、Aider、Zed、VS Code、Windsurf、Devin还有通过导入方式来支持它的 Claude Code。据说啊光是 OpenAI 自己的主仓库里面就有 88 个 AGENTS.md 文件分布在不同的目录下面。二、AGENTS.md 一般放在哪里比较好最常见的位置嘛就是仓库根目录了。一个最简单的项目在根目录放一个 AGENTS.md 就够用了。但是呢它的能力其实不止于此。1. 支持多个文件、可以分层嵌套在大型项目里面呢你可以在每个子项目、子模块里都放一个 AGENTS.md。比如说一个 monorepo 的话可能是这样的结构/AGENTS.md ← 全局约定/frontend/AGENTS.md ← 前端专属规则/backend/AGENTS.md ← 后端专属规则/services/payments/AGENTS.md ← 支付服务的特殊规则智能体在处理某个文件的时候呢它会就近去读取离它最近的那个 AGENTS.md。多个文件的内容会被合并起来越靠近正在编辑的那个文件呢优先级就越高。举个例子哈你在改 services/payments 下面的代码那支付服务里那份关于不许在没通知安全团队前轮换密钥的规则呢就会比根目录的通用规则优先生效。2. 全局层级有一些工具比如说 OpenAI Codex还支持在用户主目录比如 ~/.codex/ 这种地方放一份全局的 AGENTS.md作为所有项目的默认配置。仓库级别的文件呢会在这个基础上去进行补充或者覆盖。3. 你聊天时给的指令始终优先级最高不管 AGENTS.md 里面写了什么你在对话里临时给出的指令都会把它给覆盖掉。它更像是什么呢更像是一份背景资料而不是什么铁律。三、AGENTS.md 应该怎么去写AGENTS.md 本质上就是纯 Markdown没有固定的格式也没有什么必填字段。标题你想怎么起都行智能体只是把文本内容读进去理解而已。但是呢业界摸索出了一些公认比较好用的写法。‣ 3.1 建议包含的核心板块一份比较成熟的 AGENTS.md 通常会覆盖这么六个方面◆项目概述用一两句话把这个项目是做什么的给说清楚◆构建和测试命令要精确到能直接复制粘贴去执行的那种命令◆代码风格约定跟默认风格不一样的地方才需要去特别说明◆架构说明关键模块、核心的设计决策这些◆安全边界密钥怎么处理、哪些操作是绝对禁止的◆提交和 PR 规范commit message 的格式、分支规则之类的‣ 3.2 一个简单的示例# AGENTS.md### 项目简介这是一个基于 React 18 TypeScript Vite 的任务管理应用。### 开发环境- 用 pnpm 作为包管理器不要用 npm/yarn- pnpm install 安装依赖- pnpm dev 启动开发服务器### 测试- pnpm test 跑全部测试- 提交前必须保证测试全绿- 新增或者修改代码要补充对应测试即使没人要求### 代码风格- 使用 MUI v3注意不要写出 v4 语法- 状态管理统一用 mobx 的 useLocalStore- 禁止硬编码颜色值统一从 DynamicStyles.tsx 取设计 token### 禁止事项- 不要引入新的重量级依赖除非获得批准- 不要修改 .github/workflows 下面的 CI 配置- 涉及密钥的代码绝不能提交到仓库‣ 3.3 几条真正管用的写作技巧1. 命令写在前面而且要写得精确比起用 npm 测试这种说法呢写成 pnpm turbo run test --filter会更有用一些。带上具体的参数智能体就会反复去引用它。2. 一个真实的代码示例胜过三段文字描述你想让智能体照着某种风格去写代码的话呢直接贴一段真实的代码片段比长篇大论去解释规则要管用得多。3. 用三级边界把权限划清楚用总是可以做 / 先问一下 / 绝对不能做这三个层级来写规则的话呢能有效防止智能体做出破坏性的操作。比如说绝不能提交密钥这一条是 GitHub 分析了 2500 多个仓库之后发现的出现频率最高的规则。4. 别写文件路径要写能力和概念这是一个很容易踩的坑。如果你写认证逻辑在 src/auth/handlers.ts一旦这个文件被重命名或者挪动了呢AI 就会很自信地去错误的地方找。更稳妥的做法是什么呢是去描述这个项目有什么能力、大致的目录结构长什么样让智能体在真正干活的时候自己去定位。相对而言呢业务概念比如workspace和group的区别比文件路径要稳定得多更值得写进去。5. 反直觉的约定要优先写最值得记录的不是那些显而易见的规则而是那些反直觉但确实是故意这样设计的地方。比如说某个看起来应该加 try/catch 的地方偏偏不需要。这类内容能让智能体真正理解设计意图而不是死记硬背。6. 保持精简善用渐进式展开不要试图把所有细节都塞进一个文件里面。可以用链接引用的方式去做分层如需了解 TypeScript 规范请参考 docs/TYPESCRIPT.md这样根目录的 AGENTS.md 就能保持轻量了具体的细节按需去加载。一些工具还支持 Codex 型的可执行检查项比如说要求提交前必须跑通某个脚本但这些通常都是建议性的智能体可能会自行判断要不要执行。所以说呢指令写清楚比指望它一定遵守要更重要。7. 从简单开始边用边改不要指望第一次就能写出完美的 AGENTS.md。规则是什么呢就是跑一跑看智能体哪里出错了再针对性地去补充规则。有研究显示啊AI 自动生成的说明文件如果缺乏人工打磨的话效果甚至可能不增反减。只有人工精心撰写的文件才能带来稳定的正向提升。‣ 3.4 注意一下大小限制像 Codex 这样的工具呢会对 AGENTS.md 设置默认 32KB 的大小上限。超出的部分会被静默截断掉。所以说哪怕没到上限呢也建议尽量精简。文件里的每一行都在争夺智能体有限的注意力预算。四、AGENTS.md 和 CLAUDE.md 有什么区别这是很多人最困惑的地方了直接上结论吧AGENTS.mdCLAUDE.md定位开放的跨工具标准Claude Code 专属格式支持的工具30 多种Codex、Copilot、Cursor、Gemini CLI、Windsurf 等等仅限 Claude Code格式要求纯 Markdown没有固定字段纯 Markdown没有固定字段Claude Code 是否原生读取不会除非做特殊处理会原生就支持关键点在于什么呢Claude Code 默认只认 CLAUDE.md不会自动去读取 AGENTS.md。如果你想让 Claude Code 和其他工具共用同一份说明文件的话呢有两种常见的做法方法一用 语法去做导入新建一份 CLAUDE.md第一行写成这样AGENTS.md这样的话呢Claude Code 打开项目的时候就会通过这行导入去读取 AGENTS.md 的内容。相当于两份文件合并成一份来生效了。方法二运行 /init 命令如果项目里面已经有 AGENTS.md 了在 Claude Code 里直接运行 /init 命令就好了。它会自动读取并整合 AGENTS.md以及 .cursorrules、.windsurfrules 等其他工具的规则文件的内容。那该怎么去选呢◆如果你只用 Claude Code 的话呢直接写 CLAUDE.md 就行了不用去纠结。◆如果你同时用多个 AI 编程工具比如说团队里有人用 Cursor有人用 Codex有人用 Claude Code那就把通用规则写进 AGENTS.md 里面工具专属的特殊配置再单独放进各自的原生文件里。这样能避免同一套规则要维护好几份拷贝的问题。从生态位上来看呢AGENTS.md 目前兼容性是最广的。如果你只想维护一份说明文件的话AGENTS.md 是更保险的选择。只有当你需要用到某个工具的专属能力时呢才有必要额外去补一份该工具的原生格式文件。五、最后来小结一下◆AGENTS.md 是一份写给 AI 编程智能体看的项目说明书纯 Markdown 格式的可以分层嵌套在不同目录下面。离得越近呢优先级就越高。◆写的时候呢要给命令、给示例、给边界。少写那些容易过时的文件路径多写稳定的项目概念。◆CLAUDE.md 是 Claude Code 的专属格式。Claude Code 不会自动读取 AGENTS.md需要通过 AGENTS.md 导入或者运行 /init 来打通两者。◆如果你只用一个工具的话呢用它的原生格式就好了。如果多工具混用的话AGENTS.md 是目前兼容性最好的通用选择。一个好的 AGENTS.md 啊不是一次性写完就一劳永逸的。它更像是什么呢更像是像代码一样需要去迭代和维护的东西。智能体哪里理解错了呢就回来补一条规则。这才是它真正发挥作用的方式。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】