不知道你们团队现在的 AI 编程工具还听不听话。我陆续接触过不少前端团队反馈高度一致AGENTS.md 从一开始的三四十行两三个月就能膨胀到三四百行项目背景、技术栈、命名规范、组件结构、测试要求、禁用列表、提交信息模板甚至上一轮迭代的临时备注全都往一个文件里塞。AI 呢反而越来越“呆”。明明规则写得更多了生成组件还是经常不按套路前两天刚说“统一用 Composition API 写”今天又按旧 Options API 输出单次请求的 Token 消耗也越来越夸张经常一上来就是几十万 token。问题不是规则不够多而是上下文没有被好好分层管理。这篇文章把我们团队在实践中摸索出来的“上下文分层”做法完整写下来包括为什么单一 AGENTS.md 会失效、分层的设计思路、前端场景下的具体文件与目录方案以及一次真实迁移过程的复盘和踩坑记录。如果你是前端技术负责人、还在被 AI 编程 Agent 的“反复横跳”折磨的开发者或者正在给团队制定 AI 协作规范这篇文章应该能给你一份可以直接抄作业的落地方案。1. 为什么 AGENTS.md 会越堆越难用1.1 上下文过载的真实代价很多人觉得我的 Agent 都已经支持 1M context 了那把项目所有约定都写进 AGENTS.md 不就好了真实情况恰恰相反。“能装多少”和“该装多少”是两码事。大模型处理超长上下文时注意力会被大量无关信息稀释就像让你在一间堆满废纸的屋子里找一份合同文件越多反而越容易漏看关键条款。具体到前端项目AGENTS.md 里最常见的一类无效内容是“项目事实清单”。比如“本仓库使用 Vite 构建”“src/components 下面有 Button、Modal、Table 等组件”——这些信息 Agent 自己读代码就能得到写进去只会白白占用输入窗口。还有一类是“过度具体的历史约束”某次评审为了应付特殊情况加了一条规则问题结束后规则还留着以后每个会话都要为这条过期规则买单。上下文过载还有一个容易被忽视的成本每次工具调用都会携带固定 prompt文件越大单轮请求的 Token 消耗越大响应越慢。团队多人高频使用 AI 编程时这部分开销会被放大轻则影响效率重则直接撞上工具限流。1.2 单文件装太多规则指令开始打架前端团队的规则天然是分层的有团队层面的“禁止使用 any、禁止引入 lodash 顺手写工具函数”有项目层面的“showcases 目录是演示专用改业务不要动它”也有模块层面的“checkout 模块必须走统一的支付状态机”。这些东西如果全部放在一个 AGENTS.md 里就变成一份没有优先级的“平铺宣言”。Agent 遇到冲突时只能猜。它可能选最后看到的那条也可能选语法上更像强约束的那条还可能把两条都念一遍然后挑一个“综合理解”。我们原本指望用更多规则约束 Agent 行为结果多规则带来的不确定性反而更高。我见过最典型的一次根 AGENTS.md 里写着“所有新组件必须用 TypeScript 编写”后面又因为某个历史模块写了“utils/legacy 目录下可以保持 JavaScript”。Agent 在这个项目里连续三次生成 JS 组件直到我们把这两条拆开并写明适用范围问题才算解决。1.3 工具本身已经支持多级上下文团队却没用起来现在主流 AI 编程工具其实都提供了多级上下文机制只是很多人没意识到。Claude Code 支持用户级 CLAUDE.md、项目级 CLAUDE.md / AGENTS.md还支持目录级的 AGENTS.mdCursor 有 .cursor/rules 可以按 glob 自动匹配Codex 等也支持全局规则文件和项目规则文件。但团队普遍还在用最原始的方式仓库根目录一个 AGENTS.md所有内容一坨。工具提供了多层机制我们的文件结构却是单层的等于白扔了分层能力。后面要讲的内容本质上就是把这些机制真正用起来。2. 上下文分层的核心设计2.1 四层模型全局 / 仓库 / 模块 / 会话我们最终采用四层模型对应不同的作用范围和生命周期。第一层是全局层属于个人或团队级配置放置通用编码习惯、通用禁止清单、语言偏好。例如“统一使用中文注释”“不要在代码里留下没有 owner 的 TODO”“禁止引入无 license 的依赖”。这一层一旦设定所有项目都会生效所以要克制只放真正普适的规则。第二层是仓库层即项目根目录的 AGENTS.md。这一层放项目简介、技术栈、常用命令、目录地图、全局工作流纪律。它描述的是“这个仓库是谁、怎么跑、有哪些边界”是 Agent 进入项目后最先看到的内容。第三层是模块层以目录级规则文件形式存在。比如 src/features/checkout/AGENTS.md只讲这个模块的目标、特有约定、内部结构和修改指引。模块层不需要重复仓库层的技术栈信息只写“本模块特殊在哪里”。第四层是会话层即每次对话中临时补充的命令。当前做什么需求、涉及哪些文件、预期输出是什么这一层不落盘临时性最强。一个规则应该放在哪一层核心判断标准是它只对自己负责的范围生效吗只对支付模块生效的规则永远不要上升到仓库层只对全局生效的禁止令也不要塞进某个子模块文件。2.2 分层为什么能解决“塞太多就变傻”的问题我们可以类比软件的层次化设计。数仓要分 ODS、DWD、ADS嵌入式系统要把驱动、中间件、应用分开核心思想都一样每一层只依赖相邻层两层之间通过清晰接口通信哪层出问题就只改哪层。AGENTS.md 分层其实也是这个思路。把规则按作用范围拆开后Agent 在某个目录工作时只会自动加载该目录的规则需要时再通过 引用读取更深层文档而不是每次会话都把文件全塞进上下文。模型在推理时能保持“注意力集中”减少无关信息的干扰。对团队协作来说分层还带来两个额外好处。一是互不打扰业务组去改自己的模块规则不会影响全局规则二是可追溯规则变更的 diff 更小Code Review 起来更轻松。规则文件不再是某个人的私有文档而是团队可以共同维护的工程资产。2.3 上下文分层与“新同事入职文档”的区别有人会把 AGENTS.md 写成给新同事看的入职文档恨不得把团队 Wiki 全文复制进去。这是个很深的坑。Agent 不是人它不靠长篇阅读建立信任它需要的是“操作边界”和“调用前置条件”。一条好的上下文规则应该能回答三个问题什么情况下生效、允许做什么、不允许做什么。至于项目背景的详尽叙述、团队文化的描述应该放到文档站点而不是塞进上下文如果确实有必要让 Agent 知道再考虑放一个指向 docs 的引用让 Agent 按需拉取。这个区别想清楚后AGENTS.md 的定位就变了它更像 Agent 的“命令行入口”而不是一本百科全书。入口必须小、清晰、可控。3. 前端团队落地分层文件、模板与 Token 预算3.1 盘点现有内容先打标签再动手在动手拆文件之前先用 30 分钟做一件看似无聊但极其重要的事把现有 AGENTS.md 的每一条内容复制到表格里逐条打标签。标签可以分成四类全局习惯、项目技术栈与命令、模块特定约束、临时迭代备注。这一步会把问题暴露得非常清楚——你会发现大量内容其实属于“临时备注”和“模块特定约束”它们本就不该出现在根文件里。我随便列几条典型的现有条目实际类型应该放哪层处置建议注释必须用中文全局习惯全局层迁到用户级配置使用 pnpm禁止 npm install项目命令仓库层保留在根 AGENTS.mdcheckout 必须走支付状态机模块约束模块层迁到 src/features/checkout/AGENTS.md本季度灰度期间临时关闭 SSR 优化临时备注会话层/迭代文档移出上下文相关任务单独说明这一步最大的收获不是清单本身而是让团队形成一种意识规则不是“写了就生效”而是“放在对的位置才生效”。位置错了规则越写越多Agent 反而越难用。3.2 搭建分层的目录结构对典型的前端项目我们最终采用的目录结构长这样frontend-repo/ ├─ AGENTS.md # 仓库层全局项目上下文与规则索引 ├─ docs/agents/ │ ├─ frontend-conventions.md # 前端通用规范按需引用 │ ├─ testing.md # 测试策略按需引用 │ └─ performance.md # 性能预算与优化检查清单 ├─ src/ │ ├─ components/AGENTS.md # 组件库模块级规则 │ ├─ features/checkout/AGENTS.md # 支付模块级规则 │ └─ core/AGENTS.md # 核心 HTTP/状态管理模块规则这里有两个关键设计。一是 docs/agents 里的文档不要全部塞进上下文而是在根 AGENTS.md 中用 符号引用让 Agent 只在相关任务里按需拉取。二是目录级 AGENTS.md 要做好命名优先放在职责明确的业务模块而不是每个 src 子目录都放一个否则规则本身又会散乱。如果你的工具对目录级文件支持不好可以退而求其次在根 AGENTS.md 里写一句“处理 src/features/checkout 时先读取 src/features/checkout/AGENTS.md”让 Agent 显式读取。虽然不如自动加载优雅但也能保证关键模块规则不丢失。3.3 仓库层 AGENTS.md 的前端模板仓库层模板可以直接套用下面这份我已经把大多数前端项目需要的条目都列出来了# Frontend Agent Context ## 项目概况 - 项目名管理后台前端Vue 3 TS Vite - 包管理器pnpm禁止使用 npm/yarn 安装依赖 - 测试Vitest 单测 Playwright E2E ## 常用命令 - dev: pnpm dev - test: pnpm vitest - lint: pnpm eslint --fix - typecheck: pnpm vue-tsc ## 目录地图 - src/core请求封装、Pinia store、全局类型 - src/components通用展示组件不允许在这里放业务逻辑 - src/features业务模块按业务域拆分每个模块有独立目录规则 - src/styles全局样式与设计 token ## 全局工作流纪律 - 修改公共组件前先检查调用方避免隐性破坏 - 不允许直接提交有 eslint 报错的代码 - 新页面默认使用 Composition API禁用 mixin 新增逻辑 - 涉及接口联调时先读 src/core/api 下对应模块的类型定义 ## 按需加载的深链 - 前端统一规范docs/agents/frontend-conventions.md - 测试策略docs/agents/testing.md这份模板的关键是它不只写“技术栈有哪些”还写“Agent 在什么情况下应该做什么”。比如“修改公共组件前先检查调用方”就是在引导 Agent 的行动路径而不是丢给它一堆事实。命令、目录、纪律、深链四块基本覆盖了前端项目日常高频需求的上下文。3.4 模块层 AGENTS.md 怎么写模块层文件比如 src/features/checkout/AGENTS.md可以写成这样# Checkout 模块上下文 ## 模块职责 - 负责订单结算流程购物车 → 确认订单 → 支付 → 结果页 - 状态管理统一使用 checkoutStore禁止在组件里散落 orderStatus 相关逻辑 ## 关键文件 - api/order.ts下单与支付接口所有请求必须走这里的封装 - components/ResumeOrderList.tsx订单摘要列表改它会影响多个页面 ## 本模块禁忌 - 不要绕过 order.ts 直接调用 http client - 支付回调里的错误处理必须展示用户可读提示严禁直接把错误堆栈抛给用户模块层不需要重复仓库层的技术栈信息只写“本模块特有约束”。要注意重心放在“关键文件”和“禁忌”上这两个部分对 Agent 的生成质量影响最大。比如“改 ResumeOrderList 会影响多个页面”这条能有效阻止 Agent 随意改动公共组件而“错误提示必须用户可读”这条能避免它写出把 error 对象直接 render 出来的代码。模块层的行数建议控制在 30 行以内。如果某个模块规则超过 30 行继续按功能子目录拆分不要硬塞在一个文件里。3.5 Token 预算与文件大小的经验值以下是我个人实践后的经验值大家可参考后按项目调整根 AGENTS.md60 行以内通常控制在 4~6KB目录级 AGENTS.md30 行以内docs/agents 下的按需引用文档控制在 300 行以内会话层临时信息尽量在提问里覆盖不要写成文件。我们在实践中发现当根文件超过 8KB 后Agent 对早期“命令相关”规则的反应就会明显松动。这背后是模型注意力的分布问题不是玄学。你可以把 Token 想象成员工的工作记忆工作记忆就那么多塞得越满越容易把前面的话忘掉。当然文件不是越短越好硬性禁忌不能省。规则文件的目标是在“信息完整”和“足够精简”之间找到平衡点而不是单纯追求小。4. 实操过程从单文件到分层的一次完整迁移4.1 迁移背景拿我们团队一个 Vue3 管理后台项目举例。这个项目从 2025 年下半年开始启用 AI 编程最初只用一个根 AGENTS.md。到 2026 年 2 月文件膨胀到 400 多行内容包含技术栈说明、全部业务模块入口、各种历史决策记录甚至连“上个迭代遗留的问题清单”都在里面。当时最明显的症状Agent 在处理 features/checkout 需求时经常不看该模块的支付状态机明明根规则写了“组件放 components 目录”它还是会往业务页面里塞大段组件代码。我们都以为是模型版本不够聪明后来才意识到是上下文已经太脏了。4.2 迁移步骤第一步先冻结 AGENTS.md 的变更用 git 把当前版本存档。然后拉出所有条目分类。第二步把“全局习惯”类条目同步到每个人用户级配置。这一步说起来简单但要注意工具差异团队成员有人用 Claude Code有人用 Cursor用户级配置的存放路径不一样。我们当时写了一个内部脚本把同一份全局规则同步生成到不同工具的配置目录保证入职一个新成员时全局规则不会丢。第三步把“模块约束”类条目下沉到目录级 AGENTS.md。这一步要和模块 owner 确认防止漏掉边界条件。比如 checkout 模块的 owner 明确指出支付回调错误不允许直接展示 error 对象里的 message必须走 i18n key。这条如果不写进模块文件Agent 一定会犯错。第四步重写根 AGENTS.md保持在 70 行左右。把多余内容全部挪到 docs/agents/ 并通过 引用。这一步要重点检查“目录地图”是否准确因为 Agent 后续会依据这个地图决定去哪个目录读取模块规则。第五步临时迭代类内容全部删除改为在每次任务里用会话层指令补充。同时和团队约定AGENTS.md 里禁止出现“临时”两个字所有临时约束必须写在当前会话里。4.3 用一次真实需求验证效果为了确认迁移效果我们选了一个小需求做前后对比开发一个“订单列表的筛选表单”。迁移前Agent 生成表单组件时把筛选状态直接写在组件内部弹窗宽度用了一个很随意的数值不符合设计 token迁移后模块级规则里有“筛选表单必须走 useFilterStore 管理状态”和“所有尺寸变量从 designToken 取”同样的需求Agent 两次就生成了符合规范的代码。我们同时用 token 统计对比了迁移前后的输入长度。典型一个中型任务改动约 200 行代码输入 Token 从 18.6 万降到 13.8 万左右降幅约 25%响应速度也有明显提升。需要说明这个数字只代表我们自己的项目体感不同项目差异会很大但方向是一致的上下文越精炼模型表现越稳定。4.4 团队协作上的配套制度分层文件落地后最大的风险是“没人维护”。AGENTS.md 和模块级规则必须像代码一样被 review。我们给团队定的规矩是任何规则变更都开 PRPR 描述里写清楚“背景 / 对 Agent 的行为影响 / 影响范围”由前端 tech lead 或模块 owner 审批。同时约定一个规则文件的生命周期。每次迭代结束后留 15 分钟检查一遍确认临时规则是否已经移除。这个动作看起来很琐碎但它是分层体系能长期运转的关键。规则文件一旦开始累积过期内容过两个月就会退回原来的老路。5. 常见问题与排查技巧实录5.1 目录级 AGENTS.md 不被加载怎么办不同工具对目录级文件的加载策略不一样。Claude Code 相对友好进入目录会自动读取Cursor 需要用 .cursor/rules 的 glob 表达式才能做到自动匹配Codex 早期版本只读项目根文件。排查方法很简单在目录级文件第一行写一句“如果你读到了这句话请回答已读取目录规则”。然后在一个新会话里让 Agent 修改该目录下的文件看它是否回答。如果它没有意识到就在根 AGENTS.md 里补一个显式引用把模块文件路径写清楚让 Agent 在进入该模块前主动读取。这个验证开销很低但能避免一个大坑你辛辛苦苦写了模块规则Agent 压根没读过。5.2 分层之后仍然有规则冲突怎么办分层之后冲突会减少但不是完全消失。最常见的冲突场景是下层规则想推翻上层硬规则。比如根文件说“所有新代码必须 TS”某模块因为历史包袱写了“该模块允许 JS”。这种冲突的处理原则是下层不能覆盖上层的“硬性禁止类规则”但可以定义上层规则的例外范围与申请流程。我们通常把规则分为硬规则和软规则。硬规则是“不允许做”比如“禁止绕过 http 封装”软规则是“默认这么做”比如“组件优先使用 composition API”。硬规则冲突必须消除软规则允许下层特化。这个分级原则也需要写进团队规范而不是靠 Agent 自己领悟。5.3 排查技巧速查表现象可能原因排查方法解决方案Agent 生成代码和模块风格明显不一致模块级上下文没加载检查根文件 引用让 Agent 复述规则增加显式引用或迁移到自动加载的目录文件单次请求 Token 偏高根文件太大或引用文档过多统计各文件行数和字符数拆分到 docs/agents 并改为按需加载Agent 频繁违反新规则新旧规则在同一文件里冲突搜索关键词查看重复规则统一合并明确优先级Agent 每次都要问项目背景会话层信息不足查看任务描述是否覆盖需求上下文在任务描述里补充目标文件、验收标准规则文件改起来没人 review缺少评审流程确认变更是否走 PR 渠道建立 rule-as-code 评审制度5.4 一些容易忽略的细节最后记录几个实践中经常踩的细节也算给想落地分层的团队提个醒。不要写和代码可自明的事实。“src/components 下有哪些组件”这种信息Agent 自己 ls 一下就能拿到写进规则就是浪费 Token。同理不要在一个长规则里套另一个长规则保持每条规则“一句话能说清”。路径引用必须精确。写成docs/agents/testing.md比写“测试相关文档在 docs 里”可靠得多。Agent 对模糊路径的猜测经常是错的而且错得毫无道理。多个 AI 工具并存时规则文件会有格式差异。团队可以约定核心规则写在 AGENTS.md 里同时用脚本生成 Cursor 规则文件、Claude 规则文件避免不同工具之间规则不一致。我自己最大的体会是AGENTS.md 本质是给 Agent 看的“接口协议”不是给人看的“百科全书”。当你把它当作一个需要长期维护、需要 review、需要瘦身、需要分层的工程产物而不是一个“越写越全越好”的备忘录它的价值才会真正出来。前端团队的规则天然适合分层一次整理带来的收益可以持续很久而且后续每次新需求都会更放心让 Agent 直接上手。