老读者应该都有这种体验你给 AI Coding Agent 提了个小需求它改完代码你一看模块边界被它推平了自己擅自从“新建模块”跳到“修改核心类”还自作主张引入了个没人维护的库。更离谱的是它在多语言项目里给你写出了“用 Java 给 Python 项目传参”这种诡异代码。问题不在 Agent 笨而是没人告诉它你的项目是怎么组织的。AGENTS.md 就是干这个用的给 AI Coding Agent 一份“项目说明书”让它从第一行代码开始就知道你在哪里、要什么、别碰哪儿。这篇文章我会以一套真实的多语言多框架项目为底子把 AGENTS.md 的规划思路、目录组织、内容写法、踩坑实录全部拆给你看。你照着抄也能用不用非得是架构师。1. 先搞懂一个核心问题AI Coding Agent 为什么总要“编”架构先说结论AI Coding Agent 不是看不懂你的代码而是它的“视野”非常有限所以只能靠猜。1.1 AI 不是读代码是猜上下文主流 AI Coding Agent 的工作模式大致是你把代码仓库交给它它会读取一部分文件作为上下文然后在对话里根据你的指令写出代码。问题是一个真实项目动辄几千个文件、上百万行代码Agent 不可能全部读进来。它通常只会看当前打开的文件、你提到的文件、入口文件、以及它自己检索到的相关文件。这个机制带来的直接后果是AI 对“项目全局架构”没有稳定认知。你让它改一个支付模块的函数它看不到支付模块依赖了消息队列也看不到订单模块的历史选择——它只能靠模型训练时积累的“通用经验”来推断。通用经验在多语言多框架项目里几乎等于没有因为像 Spring Boot 加 React 加 Python 数据处理管道这种组合AI 单靠猜十次有九次会错。我最早是在一个用 Java 写后端、React 写中台、Python 写离线任务的混编项目里吃了大亏。AI 自动生成的代码里出现过一个 Java 类直接调 Python 脚本文件的“硬编码绝对路径”上线就炸。后来我花了一晚上写了第一版 AGENTS.md再来一个需求它给的代码就全对上了。从那时候起我就确定这不是“看运气”而是“看说明书”。1.2 AGENTS.md 补齐了哪块拼图AGENTS.md 这个名字来自 Claude Code 最早的文件约定后来 Cursor、Cline、Windsurf、GitHub Copilot 等主流的 Coding Agent 陆续都支持了。它的原理很简单当 AI 扫描项目或准备写代码时会优先读取根目录以及相关子目录下的 AGENTS.md把它当作“项目最高优先级的上下文”。你可以把它理解成给 AI 看的“入职手册”。新员工入职第一天最怕的不是不会写代码而是不知道公司规矩用什么框架、代码规范是什么、构建命令是什么、哪些接口不能乱改。AGENTS.md 就是把这些信息用结构化的方式喂给 AI让它一上来就在你的架构框架里工作而不是天马行空。但 AGENTS.md 不是随便写写就有用。它的核心难点在于你要在多语言多框架项目里让 AI 准确理解“当前目录的代码属于哪个技术栈”“这个模块和别的模块什么关系”“哪些规则必须遵守哪些只是偏好”。写不好它就是一份没人看的手册写好了它比 80% 的代码注释都值钱。2. 多语言多框架项目的 AGENTS.md 内容规划我见过的很多团队写 AGENTS.md 就是列几个技术栈名词加一段“请遵循最佳实践”实际效果约等于零。原因很简单AI 需要的是可执行规则不是口号。下面我按重要性把内容规划拆开讲。2.1 明确技术栈清单与版本约束这是 AGENTS.md 里最基础也最容易被忽略的部分。很多项目文件里没有明确的版本约束AI 一看没有 package.json 里的版本号就默认用它在训练数据里见过最多的那个版本——这在快速迭代的前端项目里非常致命。我的做法是在 AGENTS.md 靠前的位置放一张“技术栈事实表”格式大致是这样技术栈版本/约定说明Java17后端主语言禁止使用 Java 8 语法Spring Boot3.2.x只用 starter-web 和 starter-data-jpa禁止引入重框架React18.3函数组件 Hook禁止使用 class 组件TypeScript5.xstrict 模式必须开启Python3.11仅供离线数据任务禁止参与 Web 请求链路这里有几个细节值得注意。第一版本要写到能影响代码写法的最小粒度比如 Spring Boot 2.x 和 3.x 的 API 差异很大不写清楚AI 大概率会用错。第二要写“禁止做什么”AI 对约束的敏感度比建议高得多。你光说“推荐函数组件”它可能觉得 class 组件也没问题你说“禁止 class 组件”它会自动绕开。第三要把“每个技术栈用在哪里”说清楚避免 AI 在 Python 目录下面生成 Java 风格代码。2.2 架构模块划分与数据流光有技术栈还不行AI 还需要知道代码是怎么组织在一起的。多语言多框架项目的架构描述不是要你写几千字的架构设计文档而是要写清楚三件事有哪些模块、模块之间怎么依赖、关键请求/数据是怎么流动的。我在 AGENTS.md 里通常用一个小章节描述模块边界大概长这样项目分为 4 个核心模块 - backend(Spring Boot)提供 REST API依赖 database-service 和 mq-service - frontend(React TS)SPA 页面只通过 HTTP 调用 backend禁止直接访问数据库 - worker(Python)异步消费 MQ 消息处理离线数据写入结果表 - shared存放协议定义、DTO、常量其他模块不得反向依赖业务模块这段描述对 AI 的价值在于它知道了“frontend 禁止直接访问数据库”这个约束后就不会在 React 里生成连接数据库的代码知道了“shared 是公共层”后就不会把业务代码塞进 shared 目录里。我之前遇到过 AI 在 shared 包里生成一个带完整业务逻辑的 Service 类就是因为没有模块边界约束。数据流部分我建议用一段文字描述比如“请求从前端进入 backend 的 Controller经过 Service 层调用 Repository 访问数据库支付成功后发送 MQ 消息由 worker 消费并进行对账”。这类信息能帮 AI 判断“改这段代码会影响哪些下游”从而避免它只改一个点、忽略整条链路。不要用复杂的图把流向和层级用一句话写清楚就够。AI 对自然语言的语义理解远比图形强图它反而可能解析不准。2.3 编码规范与命令手册编码规范这一节要写“当前仓库真实执行的规范”不是网上的通用规范。比如你的项目里已经用 Lombok 了就明确写“实体类用 Data 减少样板代码”你的项目的测试框架是 JUnit 5就写“单元测试统一用 JUnit 5禁止使用 TestNG”。AI 默认会把常见组合往里面套你不写它就按训练数据里的“最大概率”来。命令手册是最容易被低估的部分。一定要写清楚构建命令、测试命令、lint 命令、启动方式。你可以专门开一个“Before You Write Code”章节列这几条cd backend ./mvnw test cd frontend pnpm lint cd worker pytest tests/我建议把命令写到“复制就能跑”的程度因为 Agent 在生成代码后经常会自己跑测试如果命令不对它会“编”一个命令凑合。实测下来给清楚命令后AI 自测率会高很多生成的代码质量也明显更稳。人格一点说AGENTS.md 里最不该省的就是命令手册。AI 跟你一样不知道怎么验证代码时它会选择梭哈而梭哈的结果就是给你提交一堆跑不通的代码。3. AGENTS.md 的目录组织什么时候拆什么时候合一套多语言多框架项目根目录放一份 AGENTS.md 就够吗答案分情况。我见过有团队一份文件写了 200 行AI 经常抓不住重点也见过拆了七八份子文件AI 反而不知道该听谁的。这里我给一个我自己用下来最顺手的判断标准。3.1 单文件 vs 多文件的选择依据先定一个简单的分界线如果项目里不同目录技术栈差异明显、规则互不相同就必须拆如果全项目规则基本一致一份文件足够。举个例子一个目录结构大概是这样的仓库repo/ backend/ # Spring Boot frontend/ # React TS worker/ # Python docs/backend 和 worker 的代码风格、依赖管理方式、测试命令完全不同。如果你只在根目录写一份 AGENTS.md你必须把三个技术栈的规则混在一起写AI 阅读时要么抓不住重点要么把 Python 的规则误应用到 Java 上。相反如果你的项目就是简单的前后端同构用一套 TypeScript 技术栈那拆太多份只会增加维护成本一份根文件足够。我的经验是根目录 AGENTS.md 负责“项目全局事实”子目录 AGENTS.md 负责“局部细节”。全局事实包括技术栈总览、模块划分、层级依赖、跨模块规则局部细节包括具体技术栈的编码规范、命令行、目录内部约定。这样既不会让 AI 在根文件里被细节淹没也不会让子文件缺少全局视野。3.2 按子目录放置模块级 AGENTS.md模块级文件的最佳用法是独立描述“这个模块是什么、结构怎么组织、有哪些关键目录”。比如 frontend/AGENTS.md 可以写本目录是 React 前端使用 TS strict 模式。 组件统一放在 src/components 下按业务域分子目录。 状态管理使用 zustand禁止引入 redux。 样式使用 CSS Modules禁止使用 Tailwind。 API 请求统一封装在 src/api 下禁止在组件里直接写 fetch。这份文件放在 frontend/ 目录下当 AI 在这个目录里改代码时它会自动读取并优先遵从。比你在根 AGENTS.md 里写“前端不能怎样”要精准得多。还有一个实用技巧子目录文件可以只写“本目录相关的规则”而不是重复罗列根目录内容。这样维护成本低而且 AI 读取子目录文件时根文件通常也会被读入两层上下文叠加正好互补。你不需要在子文件里重复“项目是电商系统”这种背景信息那属于根文件的职责。3.3 让 AI “按图索骥”的引用机制AGENTS.md 是纯文本文件AI 并不会像人一样“一次读完所有文件”它通常按需读取。这时你可以利用引用标记来引导它。主流的 Agent 支持在对话里用 或 # 索引文件你也可以在根 AGENTS.md 里明确写“详细的前端规范见 frontend/AGENTS.md”这样当 AI 处理前端任务时就有更大概率主动去读取子文件。如果某个 AI 产品不支持自动读取子目录 AGENTS.md你还可以在根文件里放一个“关键文档索引”把子文件路径列出来关键文档索引 - frontend/AGENTS.md前端技术栈与代码规范 - backend/AGENTS.md后端 Java/Spring Boot 约束 - worker/AGENTS.mdPython 离线任务规则别小看这种“指路牌”。AI 的上下文窗口再大也不可能所有文件都读但有一个明确入口后它就知道该去哪里找参考答案。4. 完整实战示例一个真实的“多语言多框架”项目前面讲了理论和目录组织下面我放一份可以直接参考的实战配置文件。这个项目原型来自我今年初给一个电商中台做的落地技术栈是 Java 17 Spring Boot 3.2、React 18 TypeScript、Python 3.11 离线任务目录结构按模块划分。4.1 项目背景与技术栈这套系统核心业务是电商订单管理和数据报表。后端提供订单 API前端是运营后台Python 负责每小时从数据库抽取数据算报表。特殊之处在于后端订单模块依赖了消息队列报表数据由 Python 写入独立的只读库。在这样的背景下AGENTS.md 最关键的目标就是防止 AI 在改订单接口时顺手把 Python 报表逻辑也用 Java 重写一遍或者在前端代码里直接访问数据库。4.2 根目录 AGENTS.md 全文这是根目录文件的完整实现你可以直接对照你的项目做替换修改# AGENTS.md ## 项目定位 本仓库是电商订单中台包含订单管理后端、运营后台前端、离线报表任务三个可独立部署的部分。 仓库内禁止出现跨模块直接调用模块之间只允许通过 API、MQ 或数据库约定交互。 ## 技术栈总览 - backendJava 17 Spring Boot 3.2提供 REST API - frontendReact 18 TypeScript 5SPA 页面 - workerPython 3.11消费 MQ 并计算离线报表禁止参与同步请求链路 ## 模块边界 - backend 是对外唯一 API 入口所有前端请求只允许到达 backend - worker 只允许消费 MQ 消息、读取业务库并写入报表库禁止对外提供 HTTP 服务 - frontend 禁止直接访问数据库或调用 MQ - 公共类型定义放在 shared 目录模块间共享数据必须经过 shared 定义 ## 关键流程 订单从创建到完成 1. 前端调用 POST /api/orders 2. backend Service 层创建订单记录 3. 支付成功后发送 OrderPaidEvent 到 MQ 4. worker 消费事件计算订单报表并写入报表库 修改任何订单相关代码前必须先理解这条链路。 ## 开发命令 - backend 测试cd backend ./mvnw test - backend 启动cd backend ./mvnw spring-boot:run - frontend lintcd frontend pnpm lint - frontend 构建cd frontend pnpm build - worker 测试cd worker pytest tests/ - worker 启动cd worker python main.py ## 全局编码约束 - 禁止在非 shared 目录之间复制 DTO需要共享必须引用 shared - 禁止硬编码数据库地址、消息队列地址等环境配置 - 后端禁止使用 Java 8 语法前端禁止使用 class 组件worker 禁止使用 pandas 处理小数据量任务用标准库即可 - 新增第三方依赖前需先确认技术栈清单中是否已有替代方案你发现没有我这里没有写“请遵循最佳实践”这种空话每一条都是 AI 可以直接执行或不执行的硬规则。实测下来AI 对“禁止”类规则的遵从率明显高于“建议”类。4.3 子目录 AGENTS.md 与效果验证上面根文件已经覆盖了全局规则我再放一份 frontend/AGENTS.md 用于说明“子目录文件应该怎么写更具体”# frontend/AGENTS.md ## 技术约束 - 使用 React 18 TypeScript strict 模式函数组件 Hooks - 状态管理仅允许使用 zustand禁止引入 redux / mobx - 样式必须使用 CSS Modules禁止使用 Tailwind CSS - API 请求统一通过 src/api/index.ts 封装禁止在组件内直接写 fetch ## 目录结构 - src/components按业务域分子目录公共组件放 common/ - src/pages路由页面页面组件只负责拼装业务组件 - src/api接口定义与请求封装 - src/store全局状态管理 ## 命令 - 安装依赖pnpm install - lint 检查pnpm lint - 构建pnpm build这里面的规则非常明确AI 处理前端任务时会读取 frontend/AGENTS.md就不会生成 Tailwind 样式风格代码哪怕它在训练数据里很喜欢 Tailwind也不会在组件里直接写 fetch。这就达到了“让 AI 在架构约束里干活”的目的。最后我强烈建议你做个“效果验证”随便挑一个小需求不给 AGENTS.md 让 AI 改一遍再给 AGENTS.md 让 AI 改一遍对比生成的代码。通常你会看到从“能用但方向歪”到“符合模块边界直接可用”的差距。我说它“值一个通宵”真不是开玩笑。5. 常见问题与排查技巧实录光有好模板还不够落地过程中你会遇到各种“看起来能读、实际上不生效”的问题。这一节我把我踩过的坑和排查经验整理成一张速查表再补几个亲测有效的技巧。5.1 问题速查表问题现象可能原因解决方法AI 改了代码但完全没遵循 AGENTS.md文件太长规则被上下文截断精简文件把禁止项放最前面按优先级排序AI 在 Java 目录生成了 Python 风格代码根文件技术栈没有写明“每个目录用什么语言”在根文件模块描述中逐条写明目录语言与角色子文件规则和根文件冲突两层文件规则不一致统一原则根文件写全局子文件写局部冲突时以子文件为准但根文件不要反向矛盾AI 总是忽略“禁止引入 redux”禁止性规则太靠后把禁止项提到文件前三分之一用“禁止”“不得”等强指令词Agent 不读取子目录 AGENTS.md工具有截断或未支持自动读取在根文件加“关键文档索引”并说明路径规则更新后 AI 还是按旧规则写AI 上下文已缓存旧文件新开对话或通过提示词强制刷新上下文AGENTS.md 太长导致命令被忽略命令埋太深单列“开发命令”章节放在文件前半部分多模块场景 AI 改了一个模块不考虑影响数据流/链路说明缺失补充“关键流程”章节描述请求链路与影响范围这张表里的问题我基本都真实遇到过。最让我意外的是“文件太长导致规则被截断”这一个最早我把 AGENTS.md 写成了 300 行的项目文档AI 经常读了开头就忽略后半段。后来我把内容精简到 60 行把禁止项集中放前面效果立竿见影。5.2 几个亲测有效的技巧最后分享三个我长期在用的技巧属于“文档里不写但实际很管用”的经验。第一多语言项目的 AGENTS.md 一定要用“目录路径前缀”约束语言范围。比如在根文件的模块说明里写“backend/ 目录下所有代码必须是 Java禁止任何 Python 代码”这能直接杜绝 AI 在错误目录生成错误语言代码。我的经验是这条比“请遵循各语言最佳实践”有效十倍。第二用“负面清单”代替“正面原则”。AI 生成代码时训练数据的先验概率非常强你说“维持现有风格”它听不懂但你说“禁止使用 SQL 拼接”“禁止在组件里 console.log”它就知道怎么做了。我的 AGENTS.md 里负面清单占了一半以上实际 AI 的违规率下降非常明显。第三固定一个周期 REVIEW 一次 AGENTS.md。我一般是每隔一两个迭代、或者每次项目有大的技术栈变更时把 AGENTS.md 拿出来过一遍。比如引入新的依赖管理工具、前端从 CRA 迁移到 Vite这些都会让旧规则失效。你不更新AI 就会按过时规则给你写代码。说白了AGENTS.md 的价值不是“写一次用一年”而是要跟项目架构同步进化。把它当作项目的活文档AI Coding Agent 才能真正常态化地在你的架构框架里干活。我个人在实际操作中的体会是写 AGENTS.md 的过程本身就是一次绝佳的架构梳理。你必须先把模块边界、依赖关系、禁止项想清楚才能把规则写明白。很多团队说 AI 写代码不可控其实不是 AI 的问题而是团队自己都没有把“可控的输入”准备好。把这份文件写到能“防住 AI 手滑”的程度你的项目离靠谱交付就不远了。