案例分析二:Monorepo 里 backend 和 frontend 规则不同,为什么不能只读根目录 AGENTS.md?

再把视角放大到一个同时包含前后端的仓库。图中的根规则只负责共同约定,backend/ 和 frontend/ 各自还有工具链、测试方式和代码规范;Agent 进入不同目录时,应该拿到与目标路径匹配的规则组合。

图片[1]-案例分析二:Monorepo 里 backend 和 frontend 规则不同,为什么不能只读根目录 AGENTS.md?-大赛人网

如果只读根目录,很容易在前端误用后端的测试命令,或者把后端的修改限制套到前端。对于一次横跨多个子项目的任务,还需要分别检查目标文件的适用规则,而不是拿某一份局部规则覆盖全仓库。

场景背景

根:

不允许提交 secret
所有改动必须有验证

backend:

Python 3.9
pytest
禁止新增依赖

frontend:

Node 20
pnpm
允许新增 devDependency

用户让 Agent 同时修改:

backend/api.py
frontend/src/api.ts

如果只读根规则

Agent 不知道:

backend 用 pytest
frontend 用 pnpm

可能统一用错误工具。

多层规则

修改 backend 时加载:

root AGENTS.md
backend/AGENTS.md

修改 frontend 时加载:

root AGENTS.md
frontend/AGENTS.md

Main Agent 怎么协调?

Main Agent 可以:

拆成两个 Task

甚至交给:

Code Agent Backend
Code Agent Frontend

分别使用对应项目规则。

复盘

这说明 AGENTS.md 不只是:

项目根目录一个文件。

它可以形成:

作用域规则树。

这对复杂 Coding Agent 特别重要。

常见误区

误解: AGENTS.md 和 SKILL.md 都是 Markdown,所以二者本质一样。
正解: Skill 描述的是“某类任务的一般方法”,可以跨项目复用;AGENTS.md 描述的是“当前项目的具体约束”,通常与代码仓库一起版本管理。例如 python-debug Skill 可以在任何 Python 项目使用,但“禁止修改 tests/、必须 Python 3.9”只属于当前项目。两者作用域完全不同。

误解: AGENTS.md 只需要在任务开始时读一次,以后就不用管。
正解: 如果是单根目录小项目,读一次通常够;但 Monorepo 或多模块项目可能在不同子目录有不同 AGENTS.md。Agent 修改某个具体文件前,最好根据目标路径重新确定生效规则集合。规则还是可能在长 Run 中发生变化,因此重要操作前也可以重新校验当前规则版本。

误解: 把 AGENTS.md 放进 Prompt,就已经保证 Agent 不会违反规则。
正解: Prompt 注入只能提高模型遵守概率,仍然属于软约束。对“不能修改 tests/”“不能新增依赖”这类关键规则,更稳的是解析成 ProjectPolicy,并在 Middleware / ToolExecutor 执行层再次检查。真正生产系统要做到:模型知道规则,系统也能强制执行规则。

误解: 子目录 AGENTS.md 应该无条件覆盖根目录所有规则。
正解: 某些局部规则确实可以更具体,但安全和组织级硬规则不应该被随便覆盖。例如根目录禁止读取 secrets,子目录不能简单声明允许读取。正确做法是定义规则优先级和可覆盖范围,对明显冲突进行检测,而不是把所有冲突都交给模型自行理解。

误解: AGENTS.md 越长越好,最好把架构、历史、所有技术细节都写进去。
正解: AGENTS.md 应优先保存会直接影响 Agent 行为的项目规则,例如运行版本、测试命令、禁止目录、依赖策略和完成条件。大量历史背景更适合文档或 Memory。规则文件过长会增加 Context 噪声,也让真正关键约束不够突出。应尽量具体、短、可验证。

误解: 如果用户要求和 AGENTS.md 冲突,Agent 直接听用户就行。
正解: 真实项目里规则可能代表团队约束、CI 要求或安全边界,不能悄悄忽略。若用户明确要求“修改 tests/”而 AGENTS.md 禁止,应把冲突显式告诉用户,并根据系统策略决定是永久 DENY、需要更高权限、还是允许明确覆盖。规则冲突必须可见、可审计,而不是静默处理。

误解: 为了简单,可以把仓库里找到的所有 AGENTS.md 一次性加载。
正解: 无关子目录规则可能互相矛盾,也会增加 Context 噪声。应先确定目标文件,再加载 workspace 根到目标目录这条路径上的规则。一次任务跨多个作用域时,分别计算并考虑拆 Task。

误解: 用几个关键词从 Markdown 提取布尔值,就已经得到可靠的安全 Policy。
正解: 关键词解析适合教学演示和清晰格式,遇到条件、例外、否定嵌套就可能误判。关键权限应该来自明确 Schema 或审核后的结构化配置,并配套测试;原始 Markdown 仍作为模型理解项目的上下文。

误解: Agent 如果认为项目规则过时,可以先修改 AGENTS.md 再继续任务。
正解: 这会让执行者自行放松约束。规则修改应走独立授权路径,记录前后摘要并从后续 Run 生效,普通代码编辑工具不应悄悄改写自己的 Policy 来源。

误解: 项目里没有 AGENTS.md,Agent 就不能工作。
正解: 没有匹配规则文件是合法状态,此时继续遵守 System、用户要求、Tool 权限和通用 Skill。Loader 应返回明确的空结果,而不是编造项目约束或扫描 workspace 之外寻找替代文件。

© 版权声明
THE END
喜欢就支持一下吧
点赞7 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容