前端Agent上下文分层实践：告别巨型AGENTS.md

最新推荐文章于 2026-11-05 15:54:01 发布

原创最新推荐文章于 2026-11-05 15:54:01 发布 · 294 阅读

本内容遵循CC 4.0 BY-SA版权协议

本文针对前端团队AI Agent开发中巨型AGENTS.md导致的信息稀释、规则冲突和token浪费问题，提出四层上下文分层方案：全局层（安全护栏）、项目层（技术栈与工作流）、模块层（业务专属规则）和任务级（临时指令）。强调上下文接近性原则，即规则应物理贴近对应代码以提升召回率，并给出模板、命名规范、落地排查技巧及前端特化策略（如组件库、微前端、大屏适配）。核心目标是提升Agent行为稳定性与上下文利用效率。

先说一个我最近观察到的现象：很多前端团队在引入 AI Agent 辅助开发之后，做的第一件事就是往仓库根目录塞一个巨型 AGENTS.md，恨不得把所有技术栈、代码规范、组件库用法、发布流程全写进去。几个迭代下来，这个文件轻松突破上千行，然后大家发现 Agent 不但没有变聪明，反而经常答非所问，改代码改到一半突然开始处理另一个模块的逻辑，或者无视项目里早就约定好的规范，自顾自地“自由发挥”。

问题不在 AGENTS.md 这个机制本身，而在于我们把它当成了一个“万能说明书”。Agent 读取上下文的方式和人类看文档完全不一样，它虽然有很长的上下文窗口，但真正高效工作时依赖的是精准召回，而不是把所有内容一次性灌进去。堆得越厚，噪声越大，关键信息反而被稀释了。这篇文章我就把自己团队最近几个月的实践整理一下，聊聊前端团队怎么把 Agent 上下文从“一个文件堆到底”改成“分层管理”，以及每层到底该放什么、不该放什么。

适用对象很明确：正在用 Cursor、Claude Code、类似 Agent 编码工具做日常开发的前端团队，或者一个人维护多个前端项目、想在团队里建立起一套可持续的 Agent 协作规范的技术 Lead。如果你只是自己玩一玩，也可以按这套思路简化着用，至少能帮你少踩一些“Agent 越用越蠢”的坑。

1. 为什么 AGENTS.md 越堆越没用：先理解 Agent 是怎么“读”上下文文件的

1.1 上下文文件不是给人看的，是给 Agent 检索用的

很多团队把 AGENTS.md 写成了一个“团队新人入职手册”，从项目背景、技术选型、目录说明、组件规范写到大屏适配方案，事无巨细。这个思路其实是拿人类文档的标准去要求 AI 文件，两者的工作机制完全不同。

人类看文档是线性阅读，从头翻到尾，靠记忆和逻辑把信息串起来。Agent 不是这么工作的，它在一个任务开始的时候会读取一部分预加载的上下文，然后在执行过程中根据当前需求动态召回仓库里的其他文件。如果 AGENTS.md 本身内容太多，相当于把一个图书馆的目录卡片全贴在墙上，Agent 反而不知道该先看哪张。

我实测过的一个典型场景是：项目里有一个上千行的 AGENTS.md，里面第 200 行写了“所有 API 调用必须经过 src/services/request.ts 封装”，第 800 行写了一个特定页面的性能优化规则。结果 Agent 在改一个普通的路由跳转时，完全忽略了第 200 行的约束，直接自己写了一个 fetch 调用。原因很简单——那 200 行和 800 行之间的距离太远了，它预加载到的片段里并没有这条关键规则，而检索召回也没有把这条命中为当前任务的强相关内容。

结论很明确： AGENTS.md 的作用不是“储存知识”，而是“提高正确知识被召回的命中率”。 围绕这个目标，文件必须短、必须聚焦、必须贴近它要影响的代码范围。

1.2 “上下文接近性”是 Agent 工程里一个极其关键又没有写进文档的原则

你在写 AGENTS.md 的时候，一定要意识到一个底层规律：Agent 读取代码文件时，离当前编辑位置越近的文件，被完整加载和参考的概率越高。这不是某个工具的 bug，而是绝大多数 Agent 实现里 prompt 拼接的通用逻辑——它会优先把当前文件、相关依赖、最近的 git diff 放进来，再配合检索补充外围资料。

这带来的直接影响就是：如果你把一个规范放在仓库根目录的巨型文档里，而 Agent 正在编辑 src/modules/dashboard 下的业务代码，这条规范即使存在，也可能只是被“检索”到了摘要，而没有被“完整阅读并执行”。相反，如果你把这条规范直接写在 src/modules/dashboard/AGENTS.md 里，或者写在具体组件文件旁边的 context 文件里，它几乎一定会被加载。

所以从物理位置上，我们就应该让 Agent 的规范“跟着代码走”，而不是全部集中在根部。这也是“上下文分层”最底层的逻辑依据。很多人抱怨“我已经在 AGENTS.md 里写了啊，Agent 怎么不听”，先别急着怀疑模型能力，去检查一下规范的物理位置和当前任务距离有多远。大概率就是距离问题。

1.3 一个巨型文件掩盖了三个真实风险：信息稀释、规则冲突、token 浪费

堆文件的风险不只是“不好用”这么简单，展开来说有三个非常实际的问题。

第一个是信息稀释。假设有一条关键规则是“严禁直接修改 node_modules 下的文件”，它混在 800 行文档的第 743 行。Agent 在预加载时大概率只会把前面 200~300 行作为高优先级内容，后面的内容能不能被检索到属于概率事件。也就是说，文件的尾部规则实际是“薛定谔的规则”——你的项目里存在它，但 Agent 看不见它。

第二个是规则冲突。多个同事往同一个 AGENTS.md 里追加内容，很快就容易出现互相矛盾的说法。比如 A 同事写了“本项目使用 Vue 3 Composition API，禁止 Options API”，B 同事过两天加了一段某页面组件的示例代码，里面用的还是 Options API。模型遇到矛盾时不是报错停住，而是会“灵活”选择其中一条执行，最终结果完全不可控。

第三个是成本问题。AGENTS.md 一旦超过一定体量，每次会话启动都会消耗大量 token 来加载这个文件，而这个文件里的内容很可能和本次任务毫无关系。Cursor 这类工具有的时候还会把这个大文件反复放进多轮上下文中，token 消耗非常可观。我算过一笔账，一个 1200 行的 AGENTS.md 大概会吃掉 1.5 万到 2 万 token，如果你的团队整天开着 Agent 工具做代码审查，这个开销按季度算不是小数目。

2. 上下文分层方案设计：把一层拆成四层，让规则待在离代码最近的地方

2.1 分层的核心思路：全局规范管“恒量”，模块规则管“变量”

我最终在设计这套方案时，借用了一个很朴素的思想——把 Agent 需要知道的信息分成“恒量”和“变量”。

恒量指的是整个团队、整个仓库不太会变的事情，比如统一的技术栈约定、通用的代码风格、commit message 格式、Git 分支规范。这类信息适合放在最顶层，由少数人维护，变动的频率很低。

变量指的是具体模块、具体功能、具体页面的特殊逻辑。比如“结算页的金额计算只能走 backend 接口，不允许前端自行四舍五入”“上传组件在 Windows 路径下必须做转义处理”“可视化大屏组件只支持 1920x1080 分辨率”。这类规则只对相关代码有效，放在全局文件里反而会变成其他模块 Agent 的噪音。

因此我把原来的单一 AGENTS.md 拆成了四个层级：

全局代理规范（例如 .agents/global.md、根 AGENTS.md）：只放所有任务都必须遵守的最高约束，控制在 50 行以内。
项目级约定（根 AGENTS.md 或 docs/agents/project.md）：放技术栈、目录结构、通用工作流，控制在 100~200 行。
模块级上下文（src/modules/xxx/contexts/*.md）：放具体业务模块的专属规则，贴近代码存放。
任务级临时上下文（在 prompt 里用 @ 引用的方式，或用 .agents/tasks/ 存放临时说明）：只针对某一次任务生效，结束后就删。

这里我必须先说明一点：不同 Agent 工具对文件名的约定不统一，有的认 AGENTS.md，有的认 CLAUDE.md，有的支持自定义 rules 文件。但这不影响分层模型本身，你只需要把第一层和第二层的载体换成你团队实际使用的工具约定即可。我用 AGENTS.md 作为统称举例，实际项目中按自己工具链调整文件后缀。

2.2 全局层的定位：这个文件存在的意义不是“教 Agent 做事”，而是“拦住 Agent 惹祸”

全局层是整个分层里最短的那个文件，它的作用更像一个安全护栏，而不是操作手册。

我给团队设定的全局文件内容大概只包含以下几类：

禁止执行的操作（比如“不允许修改 tsconfig.json 里的 paths 别名配置”“不允许删除现有 export 名字”）
必须遵守的底线约束（比如“所有对外 API 请求必须走统一 request 实例”“新增文件必须使用 kebab-case 文件名”）
通用的验证方式（比如“每次修改后必须执行 pnpm run typecheck”“涉及组件改动时附带 Storybook 验证说明”）

这些规则有一个共同特点：它们在任何任务下都成立，所以值得被做成全局预加载。换个角度说，如果你发现某条规则只在某个模块下成立，它就不属于全局层，应该下沉到模块层。

为什么一定要控制全局层体量？因为全局层如果写得太长，Agent 的注意力分配会出问题。这和人大脑里的“默认模式”一样，如果一个系统永远把一堆高优先级指令摆在前面，那真正的高危红线反而会被淹没。全局层的理想状态是控制在 40~60 行，任何超过这个体量的人都要问自己一句：这条规则真的全局适用吗？

2.3 项目层与模块层的分工：用“单元测试”的粒度去理解模块上下文

项目层和模块层的区分，我建议用一个很简单的判断标准：这条规则在单测层面是否跨模块生效。

如果一条规则适用于所有业务代码，比如“禁止在组件内直接写内联样式，必须用 design-token 变量”，那它就是项目层规则。如果一条规则只对“订单导出”这个模块生效，比如“导出文件名必须带日期且使用 UTC 时间”，那它就应该是订单模块自己的上下文。

模块层的文件位置建议直接放在模块根目录下，例如 src/modules/order/AGENTS.md 或 src/modules/order/context.md。这样做的好处是物理距离足够近，Agent 检索对应模块代码时几乎必然能覆盖到它。我在实践过程中发现，这个文件比项目层文件的命中率稳定得多，哪怕行数超过 200 行，效果依然不错，因为它的上下文距离“正在修改的组件”足够近。

还有一个小技巧：你可以使用 @file 的方式，在一个模块的关键入口文件里直接引用这个模块的 AGENTS.md，例如在 src/modules/order/index.ts 头部写一行注释： @agent-context ../context.md （这个语法因工具而异），这样 Agent 只要打开这个入口文件，就会主动看到模块规范的指引，相当于给它一张“必读清单”。

3. 前端场景下的落地实操：文件模板、命名规范、以及真实内容示例

3.1 全局规范文件模板：精炼到 50 行以内的写法参考

我不喜欢把模板写得太死，因为每个团队的情况不同，但下面这个结构是经过多轮验证的，可以直接抄一半改一半。

# AGENTS.md - 全局 Agent 规范

## 角色
你是本仓库的资深前端开发工程师，负责在现有工程结构下完成业务开发与重构工作。
优先保持现有代码风格一致，不要擅自引入新的架构模式。

## 红线约束
- 禁止修改 tsconfig.json 中的路径别名配置。
- 禁止直接修改 package.json 中的 scripts 命令，如需调整先询问。
- 禁止删除已有 export 的名称，避免破坏上游依赖。
- 所有 API 请求必须通过 src/services/request.ts 中的封装方法发起。

## 稳定性要求
- 不要批量重构命名，不要修改类型定义中的字段名。
- 涉及公共组件改动时，必须同步检查调用方。
- 完成修改后必须执行 `pnpm run typecheck` 和对应模块的测试。

## 默认工作流
1. 阅读相关模块的 AGENTS.md 或 context 文件。
2. 定位相关代码，梳理现有实现。
3. 用最小改动完成目标，优先复用已有工具函数。

这个模板最大的特点是没有“废话”。没有“欢迎来到本仓库”这种寒暄，没有“这是一个基于 Vue3 的中后台项目”这种跟任务无关的背景介绍，全是约束和动作。

3.2 项目层和模块层的内容拆分示例：一个中后台项目的真实写法

项目层文件可以稍微丰富一些，但仍然要克制。以 Vue3 + Vite + pnpm monorepo 的常见前端工程为例，我会在项目层写清楚这些信息：

技术栈关键词（Vue3、TypeScript、Pinia、Vue Router、Vite）
目录结构的精简映射（每个一级目录大概干什么）
关键的工程命令（dev、build、typecheck、lint 对应的 pnpm script）
编码风格的核心约定（组件命名、样式方案、状态管理原则）

但注意，项目层文件不要写成“技术栈说明书”。Agent 本身就是大语言模型，它知道 Vue3 的响应式原理，不需要你去科普。你需要写的是“本项目的特殊性”和“本项目与通用实践的差异”。

模块层文件的写法则完全不同，它应该像一张“模块地图”，重点包含：

这个模块的领域边界（负责什么、不负责什么）
关键数据流（数据从哪来、经过什么处理、到哪里展示）
该模块特有的坑（表单校验规则、旧接口兼容、多租户逻辑等）
外部依赖关系（依赖哪些公共组件、哪些服务端接口）

模块层文件建议放在模块目录下，并取一个固定名称。我们团队统一用 context.md ，这样 Agent 检索时更容易识别，也便于团队成员形成习惯：进入一个模块先读 context。

3.3 用任务级上下文处理“一次性信息”：不要什么都往长期上下文里沉淀

很多团队犯的另一个错误是把临时性信息扔进长期文件里。比如“本周正在迁移接口到 v2 版本，旧接口将在下周一废弃”，这类信息下周就失效了，但写在 AGENTS.md 里之后，两周后 Agent 还在遵守一个已经不存在的规则。

我们现在对这类时间敏感信息采用两种方式处理：

在发起任务时的 prompt 中用 @ 引用一个临时说明文件，任务结束后删除。
或者把这个信息放在 git 分支的说明、commit message 里，让 Agent 从仓库历史中感知当前状态。

这样做的意义在于：长期文件保持稳定，Agent 不会因为规则频繁变动而产生冲突。稳定，是上下文分层里最容易被忽略的价值。

任务级上下文也可以用于大批量任务的统一指令。比如你接手了一个老项目，要在 30 个文件里统一加 loading 状态，你可以在根目录写一个 tasks/loading-refactor.md，然后在每轮和 Agent 对话时用 @tasks/loading-refactor.md 引用它，保证每个文件改造遵循同一套模式，改造完直接删掉这个文件。

3.4 一个常见误区：不同工具读的文件不一样，不是“写了就好”

这里单独提一下，因为我见过太多团队把规则写在了一个 Agent 根本不会主动去读的文件里。比如在 Cursor 里，规则文件是 .cursor/rules/*.mdc ，在 Claude Code 里是 CLAUDE.md ，在 Codex 里则可能用 AGENTS.md 。虽然现在很多工具开始互相兼容 AGENTS.md，但兼容程度参差不齐，有的只识别特定路径。

所以落地之前，第一步永远是确认你团队主力用的 Agent 工具读取哪些文件、支持哪些通配和引用语法。不要想当然地认为写进 AGENTS.md 就万事大吉。我见过一个团队在源码里放了一份写得很认真的 AGENTS.md，结果主力工具根本不读它，等于白写。

如果你用的是多个工具并行的环境，建议做一个“入口统一”。要么用工具的规则导入机制把公共内容引到各工具的对应文件里，要么约定所有 Agent 任务都必须从同一个 README 入口开始阅读。分层方案是通用的，文件载体要因地制宜。

4. 常见问题与排查技巧：文件也分层了，Agent 还是不听怎么办

4.1 Agent 忽略显式规则：先排查物理距离和规则是否冲突

当你清晰地写了规则，Agent 却不执行时，第一反应不应该是“模型不行”，而是按下面的顺序排查。

先看规则所在文件与当前修改文件的位置关系。如果规则在项目层，而正在修改的是很深层的业务组件，很可能规则压根没被加载进去，或者只以低优先级片段存在。解决办法是把规则下沉到模块层，甚至直接在当前文件头部的注释里写一句“本组件所有 API 响应中的数字字段必须转成 BigNumber 处理，参考 src/utils/bignumber.ts”。

再看是否有其他文件里的规则和这条冲突。冲突是 Agent 表现出“无视规则”的最常见原因。用索引去全局搜一下关键词，比如你写了“禁止直接修改 store 中 getter”，就要确认没有别的文件写“可以按业务需要调整 getter”。

最后再考虑是不是规则用词不够“机器友好”。我自己的经验是，给 Agent 的规则要尽量用肯定句和动词开头，而不是否定句加形容词。比如“不要使用任何非脚手架默认配置”这种说法，效果远不如“如需要修改配置文件，先列出当前改动和影响范围，等待确认后再执行”。前者是开放式约束，模型不知道边界在哪里，后者是一个明确的动作序列。

4.2 分层之后 token 不减反增：检查是不是全局文件加载策略出了问题

有位朋友跟我反馈，说把 AGENTS.md 拆分之后，凭证费用反而上升了。我让他导出了 Cursor 的会话 debug 信息，发现每次会话系统提示词里都塞入了所有层级文件，不是按需加载。这是因为他把模块层文件放在了项目根目录，工具在启动时扫描到了多个规则文件并全部预加载。

解决方式很简单：模块层文件不要放在 Agent 工具的默认扫描范围内，或者干脆把它命名为 context.md （不带 AGENTS 前缀），让它在默认扫描时被跳过，只在需要用 @ 引用或 Agent 追踪代码时被读取。这样既保留了物理接近性，又避免了全局预载的消耗。

我现在的习惯是根目录只留一个精简的 AGENTS.md，大概 30 行。项目信息放在 docs/agents/*.md，模块信息放在各模块的 context.md。这样每次会话的固定成本固定可控，按需加载的部分只有真正处理到的模块。

4.3 团队协作冲突：多人维护多层文件时，怎么保证规则不自相矛盾

分层之后，文件数量变多了，团队协作的瓶颈就从“文件太长没人敢动”变成了“文件太多各自为政”。我的解法不加任何自动化工具，就用代码评审来兜底。

我们的约定是： 任何涉及规则文件的变更，必须过技术评审，且变更说明必须写清楚“这条规则的生效范围”和“它要解决的实际问题”。 有了这两点，评审者就能快速判断这个变更该放哪一层、是否能和其他规则兼容。

我还建了一个索引文件 docs/agents/INDEX.md，里面用表格列出所有层级的规则文件路径、维护人、更新日期、核心内容摘要。Agent 不需要读这个索引，但人需要。它能帮你自己快速回答“我们到底在哪些地方给 Agent 写了规范”这个问题，否则文件一多，很快就没人记得全套规则长什么样了。

4.4 关于验证：先用一个小范围的高频任务测试分层效果，而不是等“上线”

我强烈建议团队不要一次性把所有项目都切换到分层方案，而是挑一个核心业务模块做试点，跑一两周再推广。

验证的方式也别搞得太复杂，就记录三个指标来对比：

Agent 处理同一个类型任务的首次成功率
一次任务平均消耗的 token 数量
开发者的主观干预次数（回滚、手动修改 prompt、帮 Agent 纠正逻辑的次数）

下面是我自己在一个中等复杂度的前端项目里做改造前后的对比数据（数据做了脱敏处理）：

指标	单一巨型 AGENTS.md	分层上下文方案
根文件行数	852 行	32 行
模块 context 文件	0 个	7 个
单次会话固定 token 消耗	约 2.1 万	约 0.4 万
跨模块修复时误伤率	约 35%	约 8%
首次成功率（同类型 UI 跳转任务）	61%	83%

这份数据当然不严谨，因为影响 Agent 效果的因素很多，但方向是一致的：文件变短、位置变近之后，Agent 的行为稳定性肉眼可见地提升了。

5. 分层方案之外：前端团队还要想清楚的两件事

5.1 上下文分层是“术”，agent 能力边界和 skill 机制是“道”

写完分层方案之后，我想再补充一点更宏观的思考。分层可以解决“Agent 不知道规则”的问题，但解决不了“Agent 不会做这件事”的问题。尤其是前端领域，有些任务本身就超出了通用模型的既有能力范围，比如大屏布局探针、低代码平台联动、复杂微前端沙箱调试。这时候单纯堆上下文是没用的，你需要做的是给 Agent 编写可复用的 skill，把一系列原子操作封装成一个它能调用的能力。

上下文分层关注的“Agent 该知道什么”，skill 机制关注的是“Agent 能做什么”。两者是上下游的关系。AGENTS.md 里应该写的是在哪些场景下调用哪个 skill，而不是把 skill 内部的实现细节全部铺开。比如全局规范里写一句“当任务涉及表单页面改动时，先调用 form-pattern skill 梳理当前页面的表单校验链路”，比你在 AGENTS.md 里详细描述校验链路的每个环节要高效得多。

这背后的逻辑其实也简单：大语言模型读长文的推理质量会随着内容长度衰减，与其让规则的颗粒度无限细分，不如让规则指向一个已经封装好的 skill，让 skill 本身去承载那些复杂但可复用的专业能力。两者结合才是前端 Agent 生产力最大的组合。

5.2 前端业务的特殊性：组件库、微前端、大屏项目需要定制自己的上下文策略

前端领域跟后端不一样的地方在于，组件库和 UI 体系在整个工程里的占重极高。通用 LLM 对特定组件库的 API 记忆并不可靠，凡是涉及自研组件库的团队，我建议单独维护一个 components-context.md ，专门描述这个组件库的设计约束、常用 props、受控与非受控的使用边界。这个文件甚至应该比业务模块的 context 优先级更高，因为前端 Agent 产出的大部分代码都要和组件库打交道。

微前端项目又不一样。子应用的隔离规则、全局状态跨应用通信的方式、路由归属的划分，这些信息极其容易在使用 Agent 时造成“跨应用污染”。我在微前端项目里会额外增加一层 micro-frontend-rules.md ，并且强制要求 Agent 每次操作前先判断当前代码属于哪个子应用，再决定使用哪套上下文。

大屏项目则主要是分辨率和适配策略的问题。如果视觉稿基于某个特定分辨率，开发时又要求适配不同尺寸，那 Agent 很容易在 style 处理上自由发挥。这种情况我会在模块 context 里加上“所有大屏样式必须通过 scale 方案适配，禁止使用百分比宽度”，一两句话就能把行为约束住。

要记住：上下文分层是一套思路，具体怎么分，永远取决于你的工程形态。前端没有一个放之四海而皆准的 AGENTS.md 模板，但“全局短、模块近、任务临时、过期即删”这个原则是通用的。