# 01、现场：Agent改对了代码，改错了模块

我在一个Spring多模块仓库里让Coding Agent修订单超时问题。它很快改了代码，也跑了测试。

问题在于：它改的是库存模块，跑的是根目录的全量测试，还顺手动了生成代码目录。

这不是模型能力问题。它进入陌生仓库时，缺少一份稳定、可读、可复用的项目上下文。

再堆一段万能Prompt解决不了。Prompt随会话消失，仓库约定却应该跟着代码走。

---

# 02、拆题：缺的是上下文，不是提示词

AGENTS.md是面向Coding Agent的开放Markdown指令文件，官方仓库把它描述为“给Agent看的README”。

它与README互补：README服务人，讲项目是什么；AGENTS.md服务Agent，讲在这个仓库里怎么干活。

它不绑定某个Agent产品。同一份仓库约定可被多种Coding Agent读取，减少切换工具时重复解释约束的成本。

但共享文件不等于行为一致。各客户端何时加载、是否遵循、嵌套文件如何取舍，都要按目标宿主实测。

---

# 03、原理：规则要具体、可执行、可验证

适合写进AGENTS.md的内容包括：项目概览、目录与模块边界、环境准备、构建命令、测试指令、代码风格、依赖约束、安全注意事项、提交与发布约定。

关键是把口号换成命令。写“保证质量”没有用，写`./mvnw -pl order-service -am test`才有用。

写“遵守分层”也不够，要写清允许的依赖方向和禁止的调用关系，例如controller不得直接依赖其他模块的mapper。

高风险命令要写明审批要求，例如涉及数据库迁移或生产配置的命令必须先确认。

---

# 04、取舍：根规则与模块规则的分工

简单仓库在根目录放一个AGENTS.md即可。Monorepo可按模块或子目录增加更局部的文件，让Agent在任务上下文中拿到相关规则。

根文件适合放全局约定：JDK版本、构建入口、提交规范、禁止修改的目录。子目录文件适合放模块特有信息：端口、数据源、测试替身、对外契约。

代价是维护成本上升。规则分散后容易互相矛盾，也容易过期。

因此嵌套不是越多越好。只在该模块确有独立约束时才拆文件，并指定唯一Owner。

![部署边界图](https://developer.qcloudimg.com/http-save/yehe-9261324/6034ea3d343ab3640e00483b0aba8f1a.png)

---

# 05、架构：从根规则到构建测试的路径

我期望的加载路径是：根AGENTS.md给出全局边界，子目录AGENTS.md补充模块约束，二者共同进入当前任务上下文，再落到Build/Test。

这条路径能否成立，取决于宿主实现。有的客户端会合并嵌套文件，有的只读最近一层，冲突处理也各不相同。

所以架构上不能假设“写了就会被遵守”。规则是提示层，强制层必须另建。

强制层包括：CI流水线、分支保护、代码仓库ACL、执行沙箱。它们才是真正拦住危险操作的地方。

![跨角色泳道图](https://developer.qcloudimg.com/http-save/yehe-9261324/343df2b395a5b4ba66e3137ded522ced.png)

---

# 06、实战：Spring多模块最小示例

根目录AGENTS.md可以这样写：项目使用JDK 21与Maven Wrapper；模块清单为order-service、inventory-service、common。

再写：修改订单逻辑只允许动order-service；跨模块改动需在PR说明理由；禁止修改target与generated目录。

测试指令写具体：单模块验证用`./mvnw -pl order-service -am test`，全量验证用`./mvnw verify`。

order-service子目录再放一份：本模块对外契约在api包，改动需同步更新契约测试；本地启动依赖本地profile。

这些规则的价值不在文字漂亮，而在于Agent能据此选对模块、跑对命令、避开生成代码。

![MCP工具调用时序图](https://developer.qcloudimg.com/http-save/yehe-9261324/234c68f7a563361d530d5922ba938b0f.png)

---

# 07、复盘：用两个Agent做同一道题

验收方法很直接：选两个不同的Coding Agent，执行同一个修复任务。

检查四件事：是否读取了规则；是否选中正确模块；是否运行了指定测试；是否避免修改生成代码。

最后要求在PR中给出执行证据，例如跑了哪条命令、结果如何。没有证据的“已完成”不算通过。

如果某个Agent没读到嵌套规则，不要改规范去迁就它，而是记录宿主差异，必要时在任务描述里显式指向文件。

---

# 08、洞见：规则治理才是长期成本

要区分四类东西的职责。README面向人，讲背景与上手。AGENTS.md面向Agent，讲操作约束。Agent Skills偏向可复用的能力封装。CI Policy是强制门禁。

四者不能互相替代。AGENTS.md不是编译器、策略引擎、权限控制或沙箱，它拦不住Agent访问密钥、执行危险命令或绕过CI。

安全约束必须由ACL、CI、分支保护和执行沙箱强制。规则提示不等于权限控制。

工程上要配三件事：规则Owner、版本检查、过期扫描。规则随代码演进，命令变了规则就得改。

商业化落点也在这里：研发规范治理、仓库上下文生成、Coding Agent接入服务。卖的不是一份模板，而是持续维护的上下文资产。

---

# 09、小结

Agent在陌生仓库里出错，多半不是不会写代码，而是不知道这个仓库的规矩。

AGENTS.md提供了一个开放、可读、可复用的载体，把模块边界、构建测试命令和禁止事项写清楚。

但它只是提示层。真正的强制要靠CI、ACL和沙箱。把两者分清，规则才既好用又可信。

延伸阅读：可查阅agents.md官方站点与agentsmd/agents.md仓库的README，了解格式定位与最小示例。

延伸阅读：AAIF项目页可用于了解该项目在开放生态中的定位，具体以官方页面当前描述为准。

延伸阅读：Maven官方文档中关于多模块构建与-pl、-am参数的章节，可用于核验示例命令语义。

我在一个Spring多模块仓库里让Coding Agent修订单超时问题。它很快改了代码，也跑了测试。

91:AAIF开源项目AGENTS.md研究实践-代码仓库如何给 Agent 立规矩？

从Coding Agent在Java多模块仓库改错模块、跑错测试的现场出发，说明AGENTS.md作为面向Agent的开放Markdown指令文件应承载什么、如

架构师

开发工具

人工智能

职业发展

AGENTS.md作为面向编码Agent的仓库上下文规范，通过根规则与子目录规则分层定义模块边界、构建测试命令及禁止事项，有效解决多模块项目中Agent改错模块或跑错测试的问题。本文以Spring多模块为例，展示规则落地的具体写法与验收方法，并明确区分规则提示层与CI/ACL强制层的职责边界。

数据库

编译器

Markdown

Agent

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

91:AAIF开源项目AGENTS.md研究实践-代码仓库如何给 Agent 立规矩？-腾讯云开发者社区-腾讯云

91:AAIF开源项目AGENTS.md研究实践-代码仓库如何给 Agent 立规矩？

91:AAIF开源项目AGENTS.md研究实践-代码仓库如何给 Agent 立规矩？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐