企业官网建设流程全解析

不知道你们团队现在的 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.md；Cursor 有 .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 的每一条内容复制到表格里，逐条打标签。标签可以分成四类：全局习惯、项目技术栈与命令、模块特定约束、临时迭代备注。这一步会把问题暴露得非常清楚——你会发现大量内容其实属于“临时备注”和“模块特定约束”，它们本就不该出现在根文件里。

我随便列几条典型的：

这一步最大的收获不是清单本身，而是让团队形成一种意识：规则不是“写了就生效”，而是“放在对的位置才生效”。位置错了，规则越写越多，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.md：60 行以内，通常控制在 4~6KB；
• 目录级 AGENTS.md：30 行以内；
• 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。我们给团队定的规矩是：任何规则变更都开 PR，PR 描述里写清楚“背景 / 对 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 排查技巧速查表

5.4 一些容易忽略的细节

最后记录几个实践中经常踩的细节，也算给想落地分层的团队提个醒。

不要写和代码可自明的事实。“src/components 下有哪些组件”这种信息，Agent 自己 ls 一下就能拿到，写进规则就是浪费 Token。同理，不要在一个长规则里套另一个长规则，保持每条规则“一句话能说清”。

路径引用必须精确。写成@docs/agents/testing.md比写“测试相关文档在 docs 里”可靠得多。Agent 对模糊路径的猜测经常是错的，而且错得毫无道理。

多个 AI 工具并存时，规则文件会有格式差异。团队可以约定核心规则写在 AGENTS.md 里，同时用脚本生成 Cursor 规则文件、Claude 规则文件，避免不同工具之间规则不一致。

我自己最大的体会是，AGENTS.md 本质是给 Agent 看的“接口协议”，不是给人看的“百科全书”。当你把它当作一个需要长期维护、需要 review、需要瘦身、需要分层的工程产物，而不是一个“越写越全越好”的备忘录，它的价值才会真正出来。前端团队的规则天然适合分层，一次整理带来的收益可以持续很久，而且后续每次新需求都会更放心让 Agent 直接上手。