前言最近这段时间,你要是在用 Cursor、Claude Code、Codex 这些 AI 编程工具,大概率见过一个新面孔——项目根目录下多了一个叫AGENTS.md的文件。圈子里有人去腾讯二面,面试官看到他简历上写了熟练使用多种 AI 编程工具,就问了一句: 你用了那么多编程 Agent,知道 AGENTS.md 吗?他愣了一下,说好像见过,但没仔细看过。面试官笑了笑:“建议你回去好好复习一下。”这道题考的不是你知不知道这个文件名,而是你有没有从工具使用者升级到工具配置者的思维。用 AI 编程工具不只是会写 prompt,还得会配置项目级的智能体行为规范。读完这篇文章,你能搞明白:AGENTS.md 是什么——写给 AI 智能体看的项目说明书分层嵌套与优先级机制——多个 AGENTS.md 怎么合并六个核心板块 七条写作技巧——怎么写出一份好用的 AGENTS.mdAGENTS.md vs CLAUDE.md——开放标准 vs 专属格式两种打通方式与选型建议——单工具 vs 多工具混用面试话术三层模板——60 分答法和 90 分答法的差距在哪不管你是天天用 AI 编程工具的开发者,还是需要在面试里讲清 Agent 配置的候选人,这个知识点都值得提前搞清楚。开拆!一、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。比如一个 monorepo:/AGENTS.md ← 全局约定 /frontend/AGENTS.md ← 前端专属规则 /backend/AGENTS.md ← 后端专属规则 /services/payments/AGENTS.md ← 支付服务的特殊规则智能体处理某个文件时,会就近读取离它最近的 AGENTS.md。多个文件的内容会被合并,越靠近正在编辑的文件,优先级越高。比如改services/payments下的代码,支付服务里不许在没通知安全团队前轮换密钥的规则,会比根目录的通用规则优先生效。全局层级:有些工具(如 OpenAI Codex)支持在用户主目录(如~/.codex/)放一份全局 AGENTS.md,作为所有项目的默认配置。仓库级别的文件会在此基础上补充或覆盖。聊天指令始终最高:不管 AGENTS.md 里写了什么,你在对话里临时给出的指令都会覆盖它。AGENTS.md 更像一份背景资料,而不是铁律。三、怎么写六个核心板块AGENTS.md 本质上是纯 Markdown,没有固定格式,没有必填字段。但业界摸索出了一些公认好用的写法,一份成熟的 AGENTS.md 通常覆盖六个方面:项目概述:一两句话说清这个项目是做什么的构建和测试命令:精确到能直接复制粘贴执行的那种代码风格约定:跟默认风格不一样的地方才需要特别说明架构说明:关键模块、核心设计决策安全边界:密钥怎么处理、哪些操作绝对禁止提交和 PR 规范:commit message 格式、分支规则一个简单示例:# AGENTS.md ### 项目简介 这是一个基于 React 18 TypeScript Vite 的任务管理应用。 ### 开发环境 - 用 pnpm 作为包管理器,不要用 npm/yarn - pnpm install 安装依赖 - pnpm dev 启动开发服务器 ### 测试 - pnpm test 跑全部测试 - 提交前必须保证测试全绿 ### 禁止事项 - 不要修改 .github/workflows 下的 CI 配置 - 涉及密钥的代码,绝不能提交到仓库四、七条真正管用的写作技巧业界沉淀了七条真正管用的写作技巧:技巧一:命令写在前面,而且要精确。比起用 npm 测试,写成pnpm turbo run test --filter更有用。带上具体参数,智能体会反复引用它。技巧二:一个真实代码示例胜过三段文字。想让智能体照着某种风格写代码,直接贴一段真实的代码片段,比长篇大论解释规则管用得多。技巧三:用三级边界划清权限。用总是可以做 / 先问一下 / 绝对不能做三个层级写规则,能有效防止智能体做破坏性操作。绝不能提交密钥这条,是 GitHub 分析了 2500 多个仓库后发现的出现频率最高的规则。技巧四:别写文件路径,要写能力和概念。如果写认证逻辑在 src/auth/handlers.ts,文件一旦被重命名或挪动,AI 就会自信地去错误的地方找。更稳妥的做法是描述项目有什么能力、大致目录结构长什么样,让智能体自己定位。业务概念(如workspace和group的区别)比文件路径稳定得多。技巧五:反直觉的约定优先写。最值得记录的不是显而易见的规则,而是反直觉但确实是故意这样设计的地方。比如某个看起来应该加 try/catch 的地方偏偏不需要。这类内容能让智能体真正理解设计意图。技巧六:保持精简,善用渐进式展开。不要把所有细节塞进一个文件,用链接引用做分层:“如需了解 TypeScript 规范,请参考 docs/TYPESCRIPT.md”。根目录的 AGENTS.md 保持轻量,细节按需加载。技巧七:从简单开始,边用边改。不要指望第一次就写出完美的 AGENTS.md。跑一跑,看智能体哪里出错了,再针对性补充规则。有研究显示,AI 自动生成的说明文件如果缺乏人工打磨,效果甚至可能不增反减——只有人工精心撰写的文件才能带来稳定的正向提升。五、大小限制与注意力预算像 Codex 这样的工具,会对 AGENTS.md 设置默认 32KB 的大小上限。超出的部分会被静默截断。所以哪怕没到上限,也建议尽量精简。文件里的每一行都在争夺智能体有限的注意力预算。这和提示词工程的原理一致:上下文越长,模型对每一条指令的注意力权重就越分散。一个 500 行的 AGENTS.md,不如一个 50 行但每条都精准的 AGENTS.md 有用。工程上的建议:把必须遵守的硬约束放前面(优先级最高),把参考性的软建议放后面或用链接引出。如果文件超 20KB,就该考虑拆分了。六、AGENTS.md vs 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 的几个工程取舍从架构师视角看几个 AGENTS.md 的工程取舍。取舍一:AGENTS.md vs CLAUDE.md vs .cursorrules——维护几份。多工具混用是常态,但维护多份规则文件会导致不一致。工程上建议:以 AGENTS.md 为单一事实来源(Single Source of Truth),其他文件(.cursorrules/CLAUDE.md)通过导入或 /init 自动同步。不要手动维护多份。取舍二:规则数量——多写 vs 少写。规则太少智能体容易犯错,规则太多又分散注意力。工程上建议:从 5-10 条核心规则起步,每出现一次智能体犯错就加一条。加到 30 条以上时考虑拆分子目录的 AGENTS.md。规则的生命力在于执行率,不在于条数。取舍三:自动生成 vs 人工撰写。有些工具支持自动生成 AGENTS.md(扫描代码库结构推断规则),但研究显示自动生成效果不如人工撰写。工程上建议:自动生成初稿 人工 review 定稿 持续迭代。不要直接用自动生成的版本上线。取舍四:规则的稳定性——写什么不容易过时。文件路径容易过时(重构后路径变了),业务概念相对稳定(workspace和group的区别不会因为重构变)。工程上建议:多写概念和约定,少写路径和具体实现细节。路径让智能体自己通过 glob/find 定位。取舍五:monorepo 中的分层策略。monorepo 的分层 AGENTS.md 要考虑规则冲突——根目录说用 jest 测试,子目录说用 vitest 测试,智能体听谁的?工程上建议:根目录写通用默认,子目录写本模块覆盖项,并在子目录文件开头明确标注本文件覆盖根目录的以下规则。取舍六:AGENTS.md 的版本管理。AGENTS.md 本身是代码库的一部分,应该用 Git 管理。但有个特殊点:AGENTS.md 的修改频率比代码低,但每次修改往往是因为智能体犯了某类错误——这和 bugfix 的节奏类似。工程上建议:AGENTS.md 的修改走和代码一样的 PR Review 流程,确保每次规则变更都有人审查。九、面试话术考官想听的是什么回到面试场景。这道题考的不是你知不知道 AGENTS.md 这个文件名,而是你有没有从工具使用者升级到工具配置者的思维。常见错误回答一:“见过,没仔细看”。这是零分——面试官想听的是你知不知道它干什么用的。常见错误回答二:“就是给 AI 看的 README”。方向对但太浅。面试官会追问和 README 什么关系“和 CLAUDE.md 什么区别”。高分答题模板:三层结构。第一层(抛本质):“AGENTS.md 是写给 AI 编程智能体看的项目说明书,和给人看的 README 分离——细节内容对人是噪音,对智能体是刚需。它是 30 多种 AI 编程工具支持的开放标准。”第二层(讲核心内容):“一份成熟的 AGENTS.md 覆盖六个板块:项目概述、构建测试命令、代码风格、架构说明、安全边界、提交规范。写的时候有七条技巧,核心是:命令要精确、给真实代码示例、用三级边界划权限、写概念不写路径、反直觉约定优先写。支持分层嵌套,越靠近编辑文件的优先级越高。”第三层(升华):“和 CLAUDE.md 的关系:AGENTS.md 是跨工具开放标准,CLAUDE.md 是 Claude Code 专属。Claude Code 不自动读 AGENTS.md,需要用 AGENTS.md 导入或 /init 打通。选型上,多工具混用以 AGENTS.md 为单一事实来源,其他文件通过导入同步。”60 分 vs 90 分对比:追问点60 分回答90 分回答“AGENTS.md 和 README 什么区别?”“一个给人看一个给AI看”“README 简洁给人看,AGENTS.md 放精确构建命令/测试流程/目录坑等细节;对人是噪音对AI是刚需,所以分离”“怎么写好一份 AGENTS.md?”“写清楚规则就行”“六个板块七条技巧;核心:命令精确到可复制粘贴、给真实代码示例、三级边界划权限、写概念不写路径、反直觉约定优先”“和 CLAUDE.md 什么关系?”“差不多”“AGENTS.md 是30工具的开放标准,CLAUDE.md 是Claude Code专属;Claude Code不自动读AGENTS.md,需导入或/init打通”“多工具混用怎么维护?”“各写各的”“以AGENTS.md为单一事实来源,其他文件(.cursorrules/CLAUDE.md)通过导入自动同步;不要手动维护多份”加分项提示:如果你能主动提到AGENTS.md 有 32KB 大小上限,超出会被静默截断,所以文件里每一行都在争夺智能体的注意力预算,面试官会认为你真的踩过坑。总结回到开头那道面试题。“你用了那么多编程 Agent,知道 AGENTS.md 吗”——这道题考察的是你有没有从工具使用者升级到工具配置者。AGENTS.md 是给 AI 智能体看的项目说明书:和给人看的 README 分离,30 多种工具支持的开放标准。分层嵌套优先级:越靠近编辑文件的 AGENTS.md 优先级越高;聊天指令始终最高。六个核心板块七条写作技巧:命令精确、给代码示例、三级边界、写概念不写路径、反直觉约定优先。32KB 大小上限:每一行都在争夺智能体的注意力预算,精简比全面更重要。AGENTS.md vs CLAUDE.md:开放标准 vs 专属格式;Claude Code 需 导入或 /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%免费】