“AI 生成的代码质量全看运气。”——这几乎是每个重度使用大语言模型辅助编程的开发者都会有的感受。同一个模型有时候能写出一段干净利落、完全符合项目约定的代码有时候却给你返回一个风格迥异、连类名都起得莫名其妙的结果甚至还会“理直气壮”地修改你根本没让它碰的配置。问题出在哪里很多人归结为“模型不够聪明”但更常见的真相是模型根本不知道你的项目长什么样。它不知道你们用 Lombok 还是手写 Getter不知道异常是抛给上层还是就地处理不知道数据库字段必须用下划线命名也不知道为什么 Controller 层严禁直接操作 Repository。当这些约束全部缺失时模型只能依据训练数据里的“平均代码风格”来生成结果——而这种平均恰恰适配不了任何真实项目。这就是 agent.md 这类项目级提示文件的价值所在把项目上下文、技术规范、代码约定、架构约束用一份可维护的 Markdown 文件固化下来让大语言模型在开始工作前就读到你的规则而不是靠你反复口头强调。这篇文章会讲清楚 agent.md 到底是什么、它和 .cursorrules、README、AGENTS.md 有什么区别、如何设计一份高质量的项目级提示文件、又如何让主流的 AI 编程工具在你的项目里真正读它。文章末尾还会给出可复制的模板、常见坑和工程化建议。1. 为什么 AI 写代码的质量总是不稳定先从一个日常场景说起。你接手了一个使用 Spring Boot 3 MyBatis-Plus 的中型项目团队规范明确Controller只做参数校验和路由业务逻辑必须下沉到Service。你让 AI 助手“帮我加一个用户查询接口”模型正常发挥时会生成一个符合分层的标准实现但更多时候它可能会在 Controller 里直接注入 Mapper把业务查询写在 Controller 方法里。这个结果“错”吗从纯语法角度看没有任何问题能编译、能运行。但从项目角度来看这就是一次质量事故代码评审会被打回架构风格被破坏后续维护成本上升。这一类问题的根源不是模型能力不足而是项目上下文缺失。大语言模型生成代码时依赖的是两样东西一是它在海量公开代码中学习到的通用编程模式二是用户在当前对话里提供的上下文。通用模式是“平均解”它对所有项目一视同仁而真实项目的代码质量恰恰取决于那些“非平均”的约定——命名风格、分层规范、异常处理策略、事务边界、日志格式、第三方库的固定用法。如果你不把这些约定告诉模型它就只能靠猜。猜对了质量不错猜错了就产生了“AI 写的代码风格和项目不一致”的问题。很多开发团队为了解决这个问题走了不少弯路在每次提问时手动补充背景“我们用的是 MyBatis-Plus不要用 JPAController 里不要写业务逻辑……”——讲一次两次可以每次都讲不现实。把项目文档丢给模型——“你先看看这份 50 页的设计文档”——上下文窗口很快被无关内容占满真正关键的约束反而被稀释。靠模型“记住”之前的对话——长对话后模型会遗忘早期信息而且换一个会话、换一个同事所有上下文归零。这些方案的根本缺陷在于项目知识没有被结构化管理而是零散地散落在人的大脑和聊天记录里。agent.md 要解决的正是“把项目知识系统化地交给模型”这件事。2. agent.md 是什么从 README 到项目级提示文件agent.md 的本质是一份放在项目根目录下的 Markdown 文件。它用自然语言描述项目的技术栈、架构约束、代码风格、运行方式、常见坑位目的是让 AI 编程助手在生成代码、修改代码、审查代码时能够遵循项目的真实约定。你可以把它理解成一份专门写给 AI 读的 README。普通 README 是给人看的侧重“项目怎么运行、接口怎么调用”agent.md 是给模型看的侧重“修改这个项目的代码时必须遵守哪些规则”。两者的服务对象不同内容自然不同。如果你用过 Cursor 的.cursorrules文件或者 GitHub Copilot 的自定义指令你会发现 agent.md 和它们在理念上很相似但定位有差异文件形态主要服务对象作用范围维护方式README.md人类开发者、用户项目说明、运行方式随项目演化重视可读性.cursorrulesCursor 的 AI 助手单个工具内的规则由使用该工具的个人维护.github/copilot-instructions.mdGitHub CopilotGitHub 平台内的 AI 提示团队共同维护纳入仓库AGENTS.md多 Agent 协作场景跨工具、跨 Agent 的项目说明书更关注任务边界与协作规范agent.mdAI 编程助手项目级提示面向多种 LLM 工具团队共同维护内容聚焦代码质量这里有一个重要的判断agent.md 并不是要取代 .cursorrules 或 copilot-instructions.md。你的项目完全可以同时使用这些文件。.cursorrules 负责工具层面的局部调优agent.md 负责项目层面的事实与约束。更普适的做法是维护一份权威的 agent.md然后在需要时让不同工具去读它、引用它而不是为每个工具各写一份互相打架的规则。从搜索结果看Agent、大语言模型、提示词工程这些关键词在 2024 至 2025 年持续高热正是因为开发者逐渐意识到不改变提示方式只更换模型版本很难带来稳定的代码质量提升。项目级提示文件正是“提示词工程”在代码生成领域最值得落地的一个分支。3. 核心原理上下文窗口与“结构化前置”要理解 agent.md 为什么有效需要回到大语言模型工作的基本机制。大语言模型生成每个 token 时只能依赖当前上下文窗口内的信息。无论模型参数多么庞大训练数据多么充分它在一次生成中能看到的只有窗口内的内容。这意味着两件事第一信息放不进窗口就等于不存在。你的项目技术栈再清晰、规范再完整如果这些内容没有出现在上下文中模型就无法遵循。第二窗口是有限资源放什么内容需要取舍。上下文窗口虽然越来越大但不能把整个项目的文档、代码、注释全部塞进去。输入越长模型对关键信息的注意力可能越分散成本也在上升。所以必须选择“高密度、高相关的信息”优先进入上下文。agent.md 的作用就是在“模型进入项目”之前把最重要的项目知识整理成一份高密度的摘要。它不是替代你阅读源码而是引导模型优先关注哪些约定、避免哪些做法。这种方法在提示词工程里对应的是System Prompt 与上下文压缩的思路。代码生成任务中agent.md 就扮演着“项目级 System Prompt”的角色。当你打开一个项目把 agent.md 的内容交给 AI 助手时模型的行为就从“一个什么都会但什么都不了解的程序员”变成了“一个读过项目规范、知道自己该做什么的工程师”。你可以做一个简单实验不提供任何上下文让模型写一个 Spring Boot 的分页查询接口。它大概率会返回一套“标准但可能不符合你项目现状”的实现。提供一段 agent.md里面写着“本项目使用 MyBatis-Plus 的 IPage 分页返回结构固定为 Result 不允许在 Controller 层操作 Mapper”模型生成的代码就会明显收敛。这就是“结构化前置”的效果把项目知识放在生成之前而不是生成之后靠人来纠偏。4. 设计 agent.md一份可直接套用的标准结构agent.md 没有统一的官方标准但综合社区实践和实际项目经验一份高质量的 agent.md 通常包含以下九个部分。每个部分都要克制只写“模型需要知道且容易忽略”的信息。4.1 项目概述用两到三句话说明项目是干什么的、核心业务场景是什么。模型不需要理解全部业务但需要知道代码背后的领域背景。比如这是一个电商订单系统还是一个物联网设备管理平台直接影响它对类名、方法命名、数据模型的合理推断。4.2 技术栈清单列出项目实际使用的语言、框架、ORM、数据库、构建工具、关键中间件。重点是标注“版本和用法上是否有约束”。例如Java 17 Spring Boot 3.2禁止使用 javax 包统一使用 jakarta。ORM 使用 MyBatis-Plus禁止在业务代码中直接使用原生 SQL。构建工具为 Maven统一使用 3.9不引入 Gradle。技术栈清单不需要面面俱到但应该把最容易让模型“用错 API”的地方写清楚。模型训练数据中不同版本的 API 是混在一起的不指定版本它很可能生成一段过时或错误用法。4.3 目录结构与分层职责给出项目的顶层目录结构并明确每一层的职责边界。这是模型生成代码时最容易跑偏的地方。很多 AI 生成的代码“能运行但放错位置”根源就是它不知道这个包应该放 Controller、Service 还是 Repository。理想情况下agent.md 里直接写清楚controller/只做参数校验、调用 Service、返回统一结果。service/处理业务逻辑、事务控制。mapper/只做数据库访问禁止业务逻辑。4.4 代码风格与命名规范包括类名、方法名、变量名的命名风格是否使用 Lombok是否强制使用 Optional集合初始化方式常量定义位置等。这些细节单独拎出来都“不影响运行”但合在一起就决定了代码是否像“这个项目的人写出来的”。4.5 关键约束与禁止事项这是 agent.md 的核心价值区。把项目里那些“不是语法错误但决不允许出现”的约定整理出来。例如禁止在循环中调用 RPC 接口。禁止在事务方法内做远程调用。禁止在 SQL 中使用SELECT *。禁止使用System.out.println输出日志必须使用 SLF4J。禁止捕获异常后静默吞掉。模型并不天生知道这些规则它们通常来自团队踩坑后的沉淀。把它们写进 agent.md等于把团队的经验直接注入 AI 的生成过程。4.6 常用命令与操作方式列出项目常用的构建、测试、启动、数据库迁移命令。这看起来是给人看的内容但对模型同样有价值——当模型需要告诉你“如何验证这个修改”或者帮你生成一段 CI 配置时它必须知道你们项目用什么命令跑测试、用什么方式启动。4.7 已知问题与使用提示记录当前项目中容易出错的模块、遗留系统的不合理设计、第三方库的版本陷阱。这些内容是团队内部非常珍贵的“暗知识”写在 README 里显得不正式但放在 agent.md 里给模型看正好合适。4.8 变更记录agent.md 本身也需要版本管理。每次重大规则调整时记录变更原因和时间。这不仅帮人类维护者理清演进历史也能让模型在“为什么会有这条规则”的问题上给出更合理的回答。4.9 边界声明明确哪些事模型不应该做。比如不要修改pom.xml中的依赖版本不要动数据库迁移脚本不要重构公共工具类。边界声明越清晰模型越不会“自作主张”扩大修改范围。这九个部分不需要一次性写全。和代码一样agent.md 的最大价值产生于最小可用版本先用五条核心约束跑起来然后在日常使用中持续补充。5. 完整示例一个 Spring Boot 项目的 agent.md下面给出一份完整的 agent.md 示例场景是一个基于 Spring Boot 3 MyBatis-Plus 的后端服务项目。你可以直接复制后按自己项目的实际情况修改。# agent.md 本文件用于向 AI 编程助手提供项目上下文与代码约束。 请在你执行任何代码生成、修改、审查任务前先阅读本文件。 ## 项目概述 本项目是公司内部的订单履约服务负责订单创建、拆分、状态流转和 物流对接。项目属于 Spring Boot 单体应用整体采用分层架构不 引入微服务。 ## 技术栈与版本 - Java 17 - Spring Boot 3.2.x - MyBatis-Plus 3.5.x - MySQL 8.x - Redis 7 - Maven 3.9 - Lombok 约束 - 禁止使用 javax.* 包统一使用 jakarta.*。 - 禁止在 Service 层直接使用 MyBatis-Plus 的 QueryWrapper 做复杂 查询复杂查询请使用自定义 SQL。 - 依赖版本统一在父 pom.xml 中管理不要在子模块中单独写版本号。 ## 目录结构与分层职责 - controller接收 HTTP 请求参数校验调用 Service返回 Result。 - service业务逻辑事务控制消息发送。 - service.implService 实现类。 - mapper数据库访问继承 BaseMapper。 - domain.entity数据库实体类。 - domain.dto入参对象。 - domain.vo出参对象。 - common常量、枚举、统一异常、工具类。 分层约束 1. Controller 禁止注入 Mapper。 2. Service 禁止出现 HttpServletRequest、HttpServletResponse。 3. 外部 RPC 调用统一封装在 client 包中Service 不直接持有 RPC 客户端。 4. Entity 类禁止被直接用作接口入参或出参。 ## 代码风格 - 使用 Lombok实体类使用 DataBuilder 场景使用 Builder。 - 方法名尽量以动词开头命名要表达行为而非状态。 - 常量使用 static final统一放在常量类中禁止散落魔法值。 - 集合初始化指定初始容量。 - 不允许使用 Date统一使用 LocalDateTime。 ## 禁止事项硬性约束 1. 禁止在循环内执行数据库查询或 RPC 调用。 2. 禁止在事务方法中执行远程调用或耗时 IO。 3. 禁止使用 SELECT *。 4. 禁止硬删除业务数据删除操作一律逻辑删除。 5. 禁止捕获异常后不记录日志。 6. 禁止在主流程中打印堆栈后继续执行异常交由全局异常处理器处理。 7. 禁止直接修改数据库表结构或迁移脚本。 ## 常用命令 - 构建mvn clean package - 跳过测试构建mvn clean package -DskipTests - 启动mvn spring-boot:run - 测试mvn test - 代码格式化mvn spotless:apply ## 已知问题与使用提示 - 订单状态机部分的代码在 order-service 模块的 state 包中改动需 同步修改状态流转表见 docs/order-state.md。 - MyBatis-Plus 的逻辑删除是全局配置新增实体时必须在 TableLogic 注解字段上注明。 - 物流对接模块依赖外部接口本地运行没有真实环境测试时使用 Mock 数据。 ## 变更记录 - 2025-05-10新增“禁止在事务方法中执行远程调用”约束。 - 2025-04-18明确 Controller 禁止注入 Mapper。这份文件的优点是每一条规则都是可执行的模型不需要“理解”就能“服从”。它不像 README 那样追求语言的优雅而是追求指令的单义性。6. 如何让主流 AI 编程工具读取 agent.md编写了 agent.md 只是第一步。接下来要让 AI 编程工具在合适的时机读到它。不同工具的读取方式不一样下面梳理主流通用做法。6.1 Cursor使用 .cursor/rules 规则文件Cursor 是当前 AI 编程助手中对项目级规则支持最完善的工具之一。新版 Cursor 推荐在项目根目录下创建.cursor/rules目录每个规则文件使用.mdc后缀并在文件头部用 YAML front-matter 声明规则的适用场景如codebase、ask、chat、edit。--- description: 项目核心规则AI 修改代码时必须遵守 globs: src/**/*.java --- # 项目规则 - 本项目使用 Spring Boot 3 MyBatis-Plus禁止使用 javax.*。 - Controller 层禁止注入 Mapper。 - 禁止使用 SELECT *禁止硬删除数据。Cursor 会在满足 globs 条件时自动加载对应规则。规则文件支持精确度较高的路径匹配适合把 agent.md 的约束拆分成“全局规则”和“特定模块规则”。如果你更习惯简单的方式也可以在项目根目录放置.cursorrules文件Cursor 会将它作为全局规则加载。但考虑到.cursorrules的核心规则条款较多、且格式缺乏 explicit description维护体验通常不如新版 rules 目录。6.2 GitHub Copilot使用 copilot-instructions.mdGitHub Copilot 支持在仓库根目录放置.github/copilot-instructions.md该文件内容会自动进入 Copilot 的提示上下文。适合团队已经在使用 GitHub 的场景。# Copilot 项目规则 - 本仓库代码遵循 Spring Boot 分层架构。 - Controller 层禁止写业务逻辑。 - 使用 SLF4J 记录日志禁止 System.out.println。 - 新增数据库字段时必须同时提交迁移脚本。如果你的项目还配置了.github/pull_request_template.md可以让模板提示开发者在提交 PR 时检查 AI 生成的代码是否遵循 copilot-instructions.md。6.3 Trae在项目规则中配置Trae 是国内开发环境中较常见的一款 AI IDE支持项目级规则配置。通常可以在项目根目录下配置规则文件也支持在 IDE 设置中维护全局规则。以 Trae 为例你可以在.trae/rules目录中维护项目规则并在 IDE 的规则管理中启用。# Trae 项目规则 project: order-service language: java rules: - 禁止在 Controller 层注入 Mapper。 - 方法命名使用动词开头。 - 数据库查询必须指定列禁止 SELECT *。Trae 的具体配置路径可能随版本变化建议以官方文档为准。关键是理解它的规则加载机制规则文件或配置项会在交互前被注入到上下文中因此你只需要保证规则内容准确它会像 Cursor 一样在 AI 生成代码前自动读取。6.4 通用方式手动导入或对话引用如果你使用的工具不原生支持“项目规则文件”最简单的方式是把 agent.md 作为问题前缀。也就是说每次在 AI 编程工具中新建对话并开始项目任务前先发送“请先阅读项目根目录下的 agent.md 文件并遵循其中所有规则”。不要小看这个动作它的效果往往比你在对话里零散补充十句话更好。也可以更进一步在项目根目录提供一份AGENTS.md作为通用入口不同的 AI 工具各自引用这个入口。比如 Cursor 的规则文件里写“项目全局规则请参考根目录的 AGENTS.md”既保留了各工具的灵活性又避免了多份规则文件内容不同步的问题。7. 验证效果如何确定 agent.md 真的生效很多人在写完 agent.md 后会产生一个疑问怎么知道 AI 真的读了而且真的起作用了下面提供三个可操作的验证方法。7.1 代码审查追溯法让 AI 助手对项目内某段既有代码做一次审查并在审查结果中明确要求“引用 agent.md 中的对应条款”然后观察它的输出是否引用了。具体提示词可以参考请审查 src/main/java/com/example/order/service/impl/OrderServiceImpl.java 这个文件。 审查时以项目根目录的 agent.md 为唯一规则依据。 对每一条违规请指出它违反了 agent.md 的哪一条约定。如果 agent.md 生效模型的审查结果会具体列出“第 3 条禁止事项”“分层约束第 2 条”等内容。如果它的回答空泛只讲“代码整体清晰、可读性良好”那就说明上下文没有正确注入。7.2 盲测相似任务法找两个相似的问题分别让 AI 完成一个在对话中提供 agent.md另一个不提供。对比两次生成的代码风格差距。例如“新增一个订单查询接口”不提供 agent.md 时它可能会生成 JPA 风格的代码提供 agent.md 后它会使用 MyBatis-Plus 的IPage返回ResultT并且把业务逻辑放到 Service 中。差异越明显说明 agent.md 的作用越大。7.3 违规自检法给 AI 一个“带病代码片段”让它检查这段代码存在什么问题。如果它只说出语法层面的问题说明上下文缺失如果它能指出“这段代码在 Controller 层操作了 Mapper违反项目分层约束”说明规则被正确读取了。需要提醒的是验证不能只做一次。大语言模型的生成具有随机性建议在多次会话中观察结果稳定性。不要因为某一次效果好就认为规则已经完善也不要因为某一次效果差就否定 agent.md 的价值。更合理的做法是记录失败场景反推是哪条规则没写清楚或没被加载。8. 常见问题与排查思路在引入 agent.md 的过程中你会遇到一些典型问题。下面整理出最常见的六类并给出排查思路。问题现象可能原因排查方式解决方案模型生成的代码仍然无视项目规范agent.md 没有被加载进上下文或规则写得不够具体检查工具的规则文件路径和加载条件用 7.1 的审查法验证将规则文件放到工具要求的目录把模糊描述改成可执行的“禁止/必须”句式规则文件太长模型上下文被占用过多agent.md 塞入了大量低价值信息查看各工具上下文中规则文件的 token 占用精简内容只保留模型容易犯错的约定拆分出“核心规则”和“按需加载规则”同一项目存在多份规则文件内容冲突团队没有统一维护规则文件的入口对比 .cursorrules、copilot-instructions.md、agent.md 的内容以 agent.md 为唯一事实源其他文件通过引用方式指向它团队只有少数人维护 agent.md规则过期没有建立规则评审机制查看 agent.md 最后的变更记录把 agent.md 纳入代码评审范围提交 PR 必须同步更新相关规则规则写得像散文模型“理解”但执行不一致指令不是原子的含义模糊让多个同事阅读规则看是否能得出同一执行结果改为“禁止 xxx”“必须 xxx”的硬性句式每条只表达一个约束模型开始遵守规则但生成代码变得保守、不敢改边界声明过多限制了模型的合理发挥检查边界声明是否误伤了正常的重构需求把“禁止修改”限定在明确模块和文件而不是对所有文件生效排查问题时一个通用的做法是“最小复现”在一个全新的对话中只粘贴 agent.md 和一个最简单的代码任务看模型的表现。这能帮你快速判断是规则本身的问题还是工具加载的问题。9. 最佳实践与工程化建议agent.md 看似只是一份 Markdown 文件但它背后是一种工程实践。以下建议来自社区经验能显著提高它的实际收益。9.1 从五条规则开始不要追求大而全一开始就写一份 300 行的 agent.md不仅维护困难而且模型在读取时可能抓不住重点。正确起步方式是写五条最核心的约束例如“技术栈是什么”“Controller 不写业务”“禁止 SELECT *”“使用统一返回体”“异常交给全局处理器”。跑通这个最小版本后再在日常开发中遇到模型犯错时把对应场景补充成规则。这样沉淀下来的每一条规则都是真实踩过坑的而不是拍脑袋写出来的。9.2 把 agent.md 纳入版本管理agent.md 应当和 README 一样纳入 Git 仓库随项目变更演进。团队成员对规则的修改应该像改代码一样经过评审。建议在文件顶部加入变更记录区让后续维护者知道每条规则的来源和原因。9.3 建立对应工具的规则同步机制如果你同时使用 Cursor、Trae、Copilot 等多个工具不要让每个工具的规则文件各自为政。最好以 agent.md 为事实源然后在各个工具的规则文件中通过引用方式指向它。比如 Cursor 的规则文件用一句话说明“请阅读项目根目录下的 agent.md 并完全遵守”而不是把 agent.md 的内容复制一百份到不同配置文件中。9.4 规则要原子化避免歧义将每一条规则写成“主语 禁止/必须 行为”的格式。例如弱写法“Controller 层尽量简洁不要在 Controller 中处理过多逻辑。”强写法“Controller 层禁止注入 Mapper禁止编写业务逻辑。”前者给模型留下了太多解释空间后者则是一条可以直接执行的质量门禁。9.5 关注安全边界不要写入敏感信息agent.md 中不要包含数据库密码、云厂商密钥、内部网络地址等敏感信息。这些内容会进入 AI 工具的服务端上下文存在泄露风险。如果需要模型理解某些安全配置用占位符说明即可例如“数据库连接字符串从环境变量读取禁止硬编码”。9.6 定期审查规则生效情况建议每两周做一次“规则复盘”翻看过去两周 AI 生成代码中被人工修改最多的部分反向判断是模型没有遵守规则还是规则没有覆盖这个场景。这个循环是 agent.md 持续完善的动力。总结agent.md 不是什么玄学。它把“人写文档给 AI 读”这件事标准化了用一份维护成本很低的 Markdown 文件把项目知识从开发者的脑子里搬运到模型的上下文里。它不能替代代码评审不能替代自动化测试但它能明显降低 AI 生成代码时的“不确定性”——让模型的输出从“随机的正确”变成“符合约定的正确”。接下来的建议很具体今天就打开你手头最常写代码的项目先写五条规则提交到仓库然后在下次让 AI 修改代码前先把这份文件交给它。你甚至不需要立刻配置所有工具只要在对话里让模型“先读一下 agent.md”就能感受到差异。等这五条规则稳定后再逐步补充和细化把项目的架构约束、已知坑位、技术栈版本全部沉淀进去。等到这份文件真正长成项目的一部分你会发现 AI 辅助编程的质量开始从“看运气”变成“有保障”。 agent.md：让AI代码生成从“看运气”到“有保障”
“AI 生成的代码质量全看运气。”——这几乎是每个重度使用大语言模型辅助编程的开发者都会有的感受。同一个模型有时候能写出一段干净利落、完全符合项目约定的代码有时候却给你返回一个风格迥异、连类名都起得莫名其妙的结果甚至还会“理直气壮”地修改你根本没让它碰的配置。问题出在哪里很多人归结为“模型不够聪明”但更常见的真相是模型根本不知道你的项目长什么样。它不知道你们用 Lombok 还是手写 Getter不知道异常是抛给上层还是就地处理不知道数据库字段必须用下划线命名也不知道为什么 Controller 层严禁直接操作 Repository。当这些约束全部缺失时模型只能依据训练数据里的“平均代码风格”来生成结果——而这种平均恰恰适配不了任何真实项目。这就是 agent.md 这类项目级提示文件的价值所在把项目上下文、技术规范、代码约定、架构约束用一份可维护的 Markdown 文件固化下来让大语言模型在开始工作前就读到你的规则而不是靠你反复口头强调。这篇文章会讲清楚 agent.md 到底是什么、它和 .cursorrules、README、AGENTS.md 有什么区别、如何设计一份高质量的项目级提示文件、又如何让主流的 AI 编程工具在你的项目里真正读它。文章末尾还会给出可复制的模板、常见坑和工程化建议。1. 为什么 AI 写代码的质量总是不稳定先从一个日常场景说起。你接手了一个使用 Spring Boot 3 MyBatis-Plus 的中型项目团队规范明确Controller只做参数校验和路由业务逻辑必须下沉到Service。你让 AI 助手“帮我加一个用户查询接口”模型正常发挥时会生成一个符合分层的标准实现但更多时候它可能会在 Controller 里直接注入 Mapper把业务查询写在 Controller 方法里。这个结果“错”吗从纯语法角度看没有任何问题能编译、能运行。但从项目角度来看这就是一次质量事故代码评审会被打回架构风格被破坏后续维护成本上升。这一类问题的根源不是模型能力不足而是项目上下文缺失。大语言模型生成代码时依赖的是两样东西一是它在海量公开代码中学习到的通用编程模式二是用户在当前对话里提供的上下文。通用模式是“平均解”它对所有项目一视同仁而真实项目的代码质量恰恰取决于那些“非平均”的约定——命名风格、分层规范、异常处理策略、事务边界、日志格式、第三方库的固定用法。如果你不把这些约定告诉模型它就只能靠猜。猜对了质量不错猜错了就产生了“AI 写的代码风格和项目不一致”的问题。很多开发团队为了解决这个问题走了不少弯路在每次提问时手动补充背景“我们用的是 MyBatis-Plus不要用 JPAController 里不要写业务逻辑……”——讲一次两次可以每次都讲不现实。把项目文档丢给模型——“你先看看这份 50 页的设计文档”——上下文窗口很快被无关内容占满真正关键的约束反而被稀释。靠模型“记住”之前的对话——长对话后模型会遗忘早期信息而且换一个会话、换一个同事所有上下文归零。这些方案的根本缺陷在于项目知识没有被结构化管理而是零散地散落在人的大脑和聊天记录里。agent.md 要解决的正是“把项目知识系统化地交给模型”这件事。2. agent.md 是什么从 README 到项目级提示文件agent.md 的本质是一份放在项目根目录下的 Markdown 文件。它用自然语言描述项目的技术栈、架构约束、代码风格、运行方式、常见坑位目的是让 AI 编程助手在生成代码、修改代码、审查代码时能够遵循项目的真实约定。你可以把它理解成一份专门写给 AI 读的 README。普通 README 是给人看的侧重“项目怎么运行、接口怎么调用”agent.md 是给模型看的侧重“修改这个项目的代码时必须遵守哪些规则”。两者的服务对象不同内容自然不同。如果你用过 Cursor 的.cursorrules文件或者 GitHub Copilot 的自定义指令你会发现 agent.md 和它们在理念上很相似但定位有差异文件形态主要服务对象作用范围维护方式README.md人类开发者、用户项目说明、运行方式随项目演化重视可读性.cursorrulesCursor 的 AI 助手单个工具内的规则由使用该工具的个人维护.github/copilot-instructions.mdGitHub CopilotGitHub 平台内的 AI 提示团队共同维护纳入仓库AGENTS.md多 Agent 协作场景跨工具、跨 Agent 的项目说明书更关注任务边界与协作规范agent.mdAI 编程助手项目级提示面向多种 LLM 工具团队共同维护内容聚焦代码质量这里有一个重要的判断agent.md 并不是要取代 .cursorrules 或 copilot-instructions.md。你的项目完全可以同时使用这些文件。.cursorrules 负责工具层面的局部调优agent.md 负责项目层面的事实与约束。更普适的做法是维护一份权威的 agent.md然后在需要时让不同工具去读它、引用它而不是为每个工具各写一份互相打架的规则。从搜索结果看Agent、大语言模型、提示词工程这些关键词在 2024 至 2025 年持续高热正是因为开发者逐渐意识到不改变提示方式只更换模型版本很难带来稳定的代码质量提升。项目级提示文件正是“提示词工程”在代码生成领域最值得落地的一个分支。3. 核心原理上下文窗口与“结构化前置”要理解 agent.md 为什么有效需要回到大语言模型工作的基本机制。大语言模型生成每个 token 时只能依赖当前上下文窗口内的信息。无论模型参数多么庞大训练数据多么充分它在一次生成中能看到的只有窗口内的内容。这意味着两件事第一信息放不进窗口就等于不存在。你的项目技术栈再清晰、规范再完整如果这些内容没有出现在上下文中模型就无法遵循。第二窗口是有限资源放什么内容需要取舍。上下文窗口虽然越来越大但不能把整个项目的文档、代码、注释全部塞进去。输入越长模型对关键信息的注意力可能越分散成本也在上升。所以必须选择“高密度、高相关的信息”优先进入上下文。agent.md 的作用就是在“模型进入项目”之前把最重要的项目知识整理成一份高密度的摘要。它不是替代你阅读源码而是引导模型优先关注哪些约定、避免哪些做法。这种方法在提示词工程里对应的是System Prompt 与上下文压缩的思路。代码生成任务中agent.md 就扮演着“项目级 System Prompt”的角色。当你打开一个项目把 agent.md 的内容交给 AI 助手时模型的行为就从“一个什么都会但什么都不了解的程序员”变成了“一个读过项目规范、知道自己该做什么的工程师”。你可以做一个简单实验不提供任何上下文让模型写一个 Spring Boot 的分页查询接口。它大概率会返回一套“标准但可能不符合你项目现状”的实现。提供一段 agent.md里面写着“本项目使用 MyBatis-Plus 的 IPage 分页返回结构固定为 Result 不允许在 Controller 层操作 Mapper”模型生成的代码就会明显收敛。这就是“结构化前置”的效果把项目知识放在生成之前而不是生成之后靠人来纠偏。4. 设计 agent.md一份可直接套用的标准结构agent.md 没有统一的官方标准但综合社区实践和实际项目经验一份高质量的 agent.md 通常包含以下九个部分。每个部分都要克制只写“模型需要知道且容易忽略”的信息。4.1 项目概述用两到三句话说明项目是干什么的、核心业务场景是什么。模型不需要理解全部业务但需要知道代码背后的领域背景。比如这是一个电商订单系统还是一个物联网设备管理平台直接影响它对类名、方法命名、数据模型的合理推断。4.2 技术栈清单列出项目实际使用的语言、框架、ORM、数据库、构建工具、关键中间件。重点是标注“版本和用法上是否有约束”。例如Java 17 Spring Boot 3.2禁止使用 javax 包统一使用 jakarta。ORM 使用 MyBatis-Plus禁止在业务代码中直接使用原生 SQL。构建工具为 Maven统一使用 3.9不引入 Gradle。技术栈清单不需要面面俱到但应该把最容易让模型“用错 API”的地方写清楚。模型训练数据中不同版本的 API 是混在一起的不指定版本它很可能生成一段过时或错误用法。4.3 目录结构与分层职责给出项目的顶层目录结构并明确每一层的职责边界。这是模型生成代码时最容易跑偏的地方。很多 AI 生成的代码“能运行但放错位置”根源就是它不知道这个包应该放 Controller、Service 还是 Repository。理想情况下agent.md 里直接写清楚controller/只做参数校验、调用 Service、返回统一结果。service/处理业务逻辑、事务控制。mapper/只做数据库访问禁止业务逻辑。4.4 代码风格与命名规范包括类名、方法名、变量名的命名风格是否使用 Lombok是否强制使用 Optional集合初始化方式常量定义位置等。这些细节单独拎出来都“不影响运行”但合在一起就决定了代码是否像“这个项目的人写出来的”。4.5 关键约束与禁止事项这是 agent.md 的核心价值区。把项目里那些“不是语法错误但决不允许出现”的约定整理出来。例如禁止在循环中调用 RPC 接口。禁止在事务方法内做远程调用。禁止在 SQL 中使用SELECT *。禁止使用System.out.println输出日志必须使用 SLF4J。禁止捕获异常后静默吞掉。模型并不天生知道这些规则它们通常来自团队踩坑后的沉淀。把它们写进 agent.md等于把团队的经验直接注入 AI 的生成过程。4.6 常用命令与操作方式列出项目常用的构建、测试、启动、数据库迁移命令。这看起来是给人看的内容但对模型同样有价值——当模型需要告诉你“如何验证这个修改”或者帮你生成一段 CI 配置时它必须知道你们项目用什么命令跑测试、用什么方式启动。4.7 已知问题与使用提示记录当前项目中容易出错的模块、遗留系统的不合理设计、第三方库的版本陷阱。这些内容是团队内部非常珍贵的“暗知识”写在 README 里显得不正式但放在 agent.md 里给模型看正好合适。4.8 变更记录agent.md 本身也需要版本管理。每次重大规则调整时记录变更原因和时间。这不仅帮人类维护者理清演进历史也能让模型在“为什么会有这条规则”的问题上给出更合理的回答。4.9 边界声明明确哪些事模型不应该做。比如不要修改pom.xml中的依赖版本不要动数据库迁移脚本不要重构公共工具类。边界声明越清晰模型越不会“自作主张”扩大修改范围。这九个部分不需要一次性写全。和代码一样agent.md 的最大价值产生于最小可用版本先用五条核心约束跑起来然后在日常使用中持续补充。5. 完整示例一个 Spring Boot 项目的 agent.md下面给出一份完整的 agent.md 示例场景是一个基于 Spring Boot 3 MyBatis-Plus 的后端服务项目。你可以直接复制后按自己项目的实际情况修改。# agent.md 本文件用于向 AI 编程助手提供项目上下文与代码约束。 请在你执行任何代码生成、修改、审查任务前先阅读本文件。 ## 项目概述 本项目是公司内部的订单履约服务负责订单创建、拆分、状态流转和 物流对接。项目属于 Spring Boot 单体应用整体采用分层架构不 引入微服务。 ## 技术栈与版本 - Java 17 - Spring Boot 3.2.x - MyBatis-Plus 3.5.x - MySQL 8.x - Redis 7 - Maven 3.9 - Lombok 约束 - 禁止使用 javax.* 包统一使用 jakarta.*。 - 禁止在 Service 层直接使用 MyBatis-Plus 的 QueryWrapper 做复杂 查询复杂查询请使用自定义 SQL。 - 依赖版本统一在父 pom.xml 中管理不要在子模块中单独写版本号。 ## 目录结构与分层职责 - controller接收 HTTP 请求参数校验调用 Service返回 Result。 - service业务逻辑事务控制消息发送。 - service.implService 实现类。 - mapper数据库访问继承 BaseMapper。 - domain.entity数据库实体类。 - domain.dto入参对象。 - domain.vo出参对象。 - common常量、枚举、统一异常、工具类。 分层约束 1. Controller 禁止注入 Mapper。 2. Service 禁止出现 HttpServletRequest、HttpServletResponse。 3. 外部 RPC 调用统一封装在 client 包中Service 不直接持有 RPC 客户端。 4. Entity 类禁止被直接用作接口入参或出参。 ## 代码风格 - 使用 Lombok实体类使用 DataBuilder 场景使用 Builder。 - 方法名尽量以动词开头命名要表达行为而非状态。 - 常量使用 static final统一放在常量类中禁止散落魔法值。 - 集合初始化指定初始容量。 - 不允许使用 Date统一使用 LocalDateTime。 ## 禁止事项硬性约束 1. 禁止在循环内执行数据库查询或 RPC 调用。 2. 禁止在事务方法中执行远程调用或耗时 IO。 3. 禁止使用 SELECT *。 4. 禁止硬删除业务数据删除操作一律逻辑删除。 5. 禁止捕获异常后不记录日志。 6. 禁止在主流程中打印堆栈后继续执行异常交由全局异常处理器处理。 7. 禁止直接修改数据库表结构或迁移脚本。 ## 常用命令 - 构建mvn clean package - 跳过测试构建mvn clean package -DskipTests - 启动mvn spring-boot:run - 测试mvn test - 代码格式化mvn spotless:apply ## 已知问题与使用提示 - 订单状态机部分的代码在 order-service 模块的 state 包中改动需 同步修改状态流转表见 docs/order-state.md。 - MyBatis-Plus 的逻辑删除是全局配置新增实体时必须在 TableLogic 注解字段上注明。 - 物流对接模块依赖外部接口本地运行没有真实环境测试时使用 Mock 数据。 ## 变更记录 - 2025-05-10新增“禁止在事务方法中执行远程调用”约束。 - 2025-04-18明确 Controller 禁止注入 Mapper。这份文件的优点是每一条规则都是可执行的模型不需要“理解”就能“服从”。它不像 README 那样追求语言的优雅而是追求指令的单义性。6. 如何让主流 AI 编程工具读取 agent.md编写了 agent.md 只是第一步。接下来要让 AI 编程工具在合适的时机读到它。不同工具的读取方式不一样下面梳理主流通用做法。6.1 Cursor使用 .cursor/rules 规则文件Cursor 是当前 AI 编程助手中对项目级规则支持最完善的工具之一。新版 Cursor 推荐在项目根目录下创建.cursor/rules目录每个规则文件使用.mdc后缀并在文件头部用 YAML front-matter 声明规则的适用场景如codebase、ask、chat、edit。--- description: 项目核心规则AI 修改代码时必须遵守 globs: src/**/*.java --- # 项目规则 - 本项目使用 Spring Boot 3 MyBatis-Plus禁止使用 javax.*。 - Controller 层禁止注入 Mapper。 - 禁止使用 SELECT *禁止硬删除数据。Cursor 会在满足 globs 条件时自动加载对应规则。规则文件支持精确度较高的路径匹配适合把 agent.md 的约束拆分成“全局规则”和“特定模块规则”。如果你更习惯简单的方式也可以在项目根目录放置.cursorrules文件Cursor 会将它作为全局规则加载。但考虑到.cursorrules的核心规则条款较多、且格式缺乏 explicit description维护体验通常不如新版 rules 目录。6.2 GitHub Copilot使用 copilot-instructions.mdGitHub Copilot 支持在仓库根目录放置.github/copilot-instructions.md该文件内容会自动进入 Copilot 的提示上下文。适合团队已经在使用 GitHub 的场景。# Copilot 项目规则 - 本仓库代码遵循 Spring Boot 分层架构。 - Controller 层禁止写业务逻辑。 - 使用 SLF4J 记录日志禁止 System.out.println。 - 新增数据库字段时必须同时提交迁移脚本。如果你的项目还配置了.github/pull_request_template.md可以让模板提示开发者在提交 PR 时检查 AI 生成的代码是否遵循 copilot-instructions.md。6.3 Trae在项目规则中配置Trae 是国内开发环境中较常见的一款 AI IDE支持项目级规则配置。通常可以在项目根目录下配置规则文件也支持在 IDE 设置中维护全局规则。以 Trae 为例你可以在.trae/rules目录中维护项目规则并在 IDE 的规则管理中启用。# Trae 项目规则 project: order-service language: java rules: - 禁止在 Controller 层注入 Mapper。 - 方法命名使用动词开头。 - 数据库查询必须指定列禁止 SELECT *。Trae 的具体配置路径可能随版本变化建议以官方文档为准。关键是理解它的规则加载机制规则文件或配置项会在交互前被注入到上下文中因此你只需要保证规则内容准确它会像 Cursor 一样在 AI 生成代码前自动读取。6.4 通用方式手动导入或对话引用如果你使用的工具不原生支持“项目规则文件”最简单的方式是把 agent.md 作为问题前缀。也就是说每次在 AI 编程工具中新建对话并开始项目任务前先发送“请先阅读项目根目录下的 agent.md 文件并遵循其中所有规则”。不要小看这个动作它的效果往往比你在对话里零散补充十句话更好。也可以更进一步在项目根目录提供一份AGENTS.md作为通用入口不同的 AI 工具各自引用这个入口。比如 Cursor 的规则文件里写“项目全局规则请参考根目录的 AGENTS.md”既保留了各工具的灵活性又避免了多份规则文件内容不同步的问题。7. 验证效果如何确定 agent.md 真的生效很多人在写完 agent.md 后会产生一个疑问怎么知道 AI 真的读了而且真的起作用了下面提供三个可操作的验证方法。7.1 代码审查追溯法让 AI 助手对项目内某段既有代码做一次审查并在审查结果中明确要求“引用 agent.md 中的对应条款”然后观察它的输出是否引用了。具体提示词可以参考请审查 src/main/java/com/example/order/service/impl/OrderServiceImpl.java 这个文件。 审查时以项目根目录的 agent.md 为唯一规则依据。 对每一条违规请指出它违反了 agent.md 的哪一条约定。如果 agent.md 生效模型的审查结果会具体列出“第 3 条禁止事项”“分层约束第 2 条”等内容。如果它的回答空泛只讲“代码整体清晰、可读性良好”那就说明上下文没有正确注入。7.2 盲测相似任务法找两个相似的问题分别让 AI 完成一个在对话中提供 agent.md另一个不提供。对比两次生成的代码风格差距。例如“新增一个订单查询接口”不提供 agent.md 时它可能会生成 JPA 风格的代码提供 agent.md 后它会使用 MyBatis-Plus 的IPage返回ResultT并且把业务逻辑放到 Service 中。差异越明显说明 agent.md 的作用越大。7.3 违规自检法给 AI 一个“带病代码片段”让它检查这段代码存在什么问题。如果它只说出语法层面的问题说明上下文缺失如果它能指出“这段代码在 Controller 层操作了 Mapper违反项目分层约束”说明规则被正确读取了。需要提醒的是验证不能只做一次。大语言模型的生成具有随机性建议在多次会话中观察结果稳定性。不要因为某一次效果好就认为规则已经完善也不要因为某一次效果差就否定 agent.md 的价值。更合理的做法是记录失败场景反推是哪条规则没写清楚或没被加载。8. 常见问题与排查思路在引入 agent.md 的过程中你会遇到一些典型问题。下面整理出最常见的六类并给出排查思路。问题现象可能原因排查方式解决方案模型生成的代码仍然无视项目规范agent.md 没有被加载进上下文或规则写得不够具体检查工具的规则文件路径和加载条件用 7.1 的审查法验证将规则文件放到工具要求的目录把模糊描述改成可执行的“禁止/必须”句式规则文件太长模型上下文被占用过多agent.md 塞入了大量低价值信息查看各工具上下文中规则文件的 token 占用精简内容只保留模型容易犯错的约定拆分出“核心规则”和“按需加载规则”同一项目存在多份规则文件内容冲突团队没有统一维护规则文件的入口对比 .cursorrules、copilot-instructions.md、agent.md 的内容以 agent.md 为唯一事实源其他文件通过引用方式指向它团队只有少数人维护 agent.md规则过期没有建立规则评审机制查看 agent.md 最后的变更记录把 agent.md 纳入代码评审范围提交 PR 必须同步更新相关规则规则写得像散文模型“理解”但执行不一致指令不是原子的含义模糊让多个同事阅读规则看是否能得出同一执行结果改为“禁止 xxx”“必须 xxx”的硬性句式每条只表达一个约束模型开始遵守规则但生成代码变得保守、不敢改边界声明过多限制了模型的合理发挥检查边界声明是否误伤了正常的重构需求把“禁止修改”限定在明确模块和文件而不是对所有文件生效排查问题时一个通用的做法是“最小复现”在一个全新的对话中只粘贴 agent.md 和一个最简单的代码任务看模型的表现。这能帮你快速判断是规则本身的问题还是工具加载的问题。9. 最佳实践与工程化建议agent.md 看似只是一份 Markdown 文件但它背后是一种工程实践。以下建议来自社区经验能显著提高它的实际收益。9.1 从五条规则开始不要追求大而全一开始就写一份 300 行的 agent.md不仅维护困难而且模型在读取时可能抓不住重点。正确起步方式是写五条最核心的约束例如“技术栈是什么”“Controller 不写业务”“禁止 SELECT *”“使用统一返回体”“异常交给全局处理器”。跑通这个最小版本后再在日常开发中遇到模型犯错时把对应场景补充成规则。这样沉淀下来的每一条规则都是真实踩过坑的而不是拍脑袋写出来的。9.2 把 agent.md 纳入版本管理agent.md 应当和 README 一样纳入 Git 仓库随项目变更演进。团队成员对规则的修改应该像改代码一样经过评审。建议在文件顶部加入变更记录区让后续维护者知道每条规则的来源和原因。9.3 建立对应工具的规则同步机制如果你同时使用 Cursor、Trae、Copilot 等多个工具不要让每个工具的规则文件各自为政。最好以 agent.md 为事实源然后在各个工具的规则文件中通过引用方式指向它。比如 Cursor 的规则文件用一句话说明“请阅读项目根目录下的 agent.md 并完全遵守”而不是把 agent.md 的内容复制一百份到不同配置文件中。9.4 规则要原子化避免歧义将每一条规则写成“主语 禁止/必须 行为”的格式。例如弱写法“Controller 层尽量简洁不要在 Controller 中处理过多逻辑。”强写法“Controller 层禁止注入 Mapper禁止编写业务逻辑。”前者给模型留下了太多解释空间后者则是一条可以直接执行的质量门禁。9.5 关注安全边界不要写入敏感信息agent.md 中不要包含数据库密码、云厂商密钥、内部网络地址等敏感信息。这些内容会进入 AI 工具的服务端上下文存在泄露风险。如果需要模型理解某些安全配置用占位符说明即可例如“数据库连接字符串从环境变量读取禁止硬编码”。9.6 定期审查规则生效情况建议每两周做一次“规则复盘”翻看过去两周 AI 生成代码中被人工修改最多的部分反向判断是模型没有遵守规则还是规则没有覆盖这个场景。这个循环是 agent.md 持续完善的动力。总结agent.md 不是什么玄学。它把“人写文档给 AI 读”这件事标准化了用一份维护成本很低的 Markdown 文件把项目知识从开发者的脑子里搬运到模型的上下文里。它不能替代代码评审不能替代自动化测试但它能明显降低 AI 生成代码时的“不确定性”——让模型的输出从“随机的正确”变成“符合约定的正确”。接下来的建议很具体今天就打开你手头最常写代码的项目先写五条规则提交到仓库然后在下次让 AI 修改代码前先把这份文件交给它。你甚至不需要立刻配置所有工具只要在对话里让模型“先读一下 agent.md”就能感受到差异。等这五条规则稳定后再逐步补充和细化把项目的架构约束、已知坑位、技术栈版本全部沉淀进去。等到这份文件真正长成项目的一部分你会发现 AI 辅助编程的质量开始从“看运气”变成“有保障”。