客户端 AI 工程里的“上下文”，到底该怎么建设？

摘要

很多团队在用 AI 写代码时，真正卡住它的往往不是模型能力，而是上下文质量。

AI 能读代码、能搜代码、也能生成代码，但它并不天然知道：

• 哪个目录才是现在真正生效的实现
• 某个术语在你们团队里到底是什么意思
• 一个需求背后有哪些默认约束
• 改一个点通常要连带验证哪些链路

这些信息，对人来说叫经验；对 AI 来说，就是上下文。

所以，所谓“客户端 AI 上下文建设”，本质上是在做一件事：

把原本散落在人脑、文档、会议和历史决策里的隐性知识，沉淀成 AI 能理解、能召回、能使用的工程资产。

快速导航

如果你想看	对应章节
为什么 AI 写代码还是容易“猜”	一、为什么要做上下文建设
什么内容才算客户端上下文	二、什么叫“客户端上下文”
上下文应该怎么分层组织	三、上下文应该怎么组织
AGENTS.md 到底该写什么	四、AGENTS.md 为什么重要
除了目录说明，还有哪些召回方式	六、除了 AGENTS.md，还能怎么召回
为什么上下文必须嵌进研发流程	七、上下文不是补文档，而是流程的一部分
应该优先沉淀哪些内容	八、最值得优先建设的上下文
怎么判断上下文有没有价值	九、怎么评估上下文有没有价值
最容易踩的坑有哪些	十、最容易出现的误区

一、为什么要做上下文建设？

很多人第一次用 AI 辅助研发时，都会有一种错觉：
模型已经很强了，是不是只要把代码仓库扔给它，它就能把活干好？

现实通常不是这样。

在真实客户端工程里，如果没有足够好的上下文，AI 常见会出现三类问题。

1. 它能看见代码，但看不懂业务

它知道某个页面入口在哪里，却不知道这个入口已经被新链路替代。
它能搜到很多相似类名，却不知道哪个才是线上主链路。

换句话说，它看得到代码表面，但看不到业务语义。

2. 它能生成代码，但特别容易**“猜”**

一旦缺少边界、约束和历史背景，AI 就会自动用通用经验补空白。

在简单 demo 里，这可能问题不大；
但在复杂客户端工程里，这往往意味着误改、返工，甚至把风险带到线上。

3. 它能执行任务，但质量不稳定

同样一个需求，AI 有时表现很好，有时又很飘。
差别通常不在模型本身，而在于它这次拿到的上下文够不够准、够不够完整。

所以，AI 的上限确实取决于模型能力，
但 AI 的下限，往往取决于上下文建设水平。

二、什么叫“客户端上下文”？

可以把它简单理解成一句话：

一切能帮助 AI 正确理解项目、正确做出工程判断的信息，都是上下文。

这些信息通常包括：

• 代码目录和模块边界
• 业务术语和概念映射
• 编码约定和工程规则
• 关键入口和阅读路径
• 高风险区域和验证建议
• 需求背景、技术方案和评审结论
• 历史决策、Bug 修复原因和约束来源

它们有一个共同点：
很多都不是“看代码就能直接推导出来”的。

也正因为如此，这些内容才值得被专门沉淀。

三、上下文应该怎么组织？

一个比较稳妥的原则是八个字：

统一结构，就近沉淀。

所谓**“统一结构”，是让不同层级的上下文有稳定放法。
所谓“就近沉淀”**，是让知识尽量贴近它服务的代码区域。

可以把它理解成这样一套分层：

• 仓库级知识，放在仓库根目录附近
• 模块级知识，放在模块目录附近
• 子业务或子组件的特殊知识，继续下沉到对应子目录

这样做的好处很直接：
AI 进入哪个目录，就能顺着那一层的上下文继续理解，而不是每次都去读一份巨大总文档。

一个常见的组织方式，大概像这样：

.
├── .ai/
│   └── docs/              # 仓库级文档知识
├── .trae/
│   ├── rules/             # 全局规则
│   └── skills/            # 按意图加载的知识或流程
├── AGENTS.md              # 仓库级入口说明
│
└── modules/
    └── some-module/
        ├── .ai/
        │   └── docs/      # 模块级文档知识
        ├── AGENTS.md      # 模块级入口说明
        └── sub-domain/
            ├── .ai/
            │   └── docs/
            └── AGENTS.md

这套结构背后的核心，不是形式，而是维护关系：
谁最了解这段代码，谁就最适合维护这层知识；
知识离代码越近，越不容易失真，也越容易被更新。

四、AGENTS.md 为什么重要？

如果把整套上下文系统想象成一张知识网，
那么 AGENTS.md 更像是每个目录的“入口说明书”。

它不是一份大而全的设计文档，
而是一份短、准、能帮 AI 迅速做出判断的文件。

它主要回答三个问题：

• 这个目录到底是干什么的
• 在这里改代码要注意什么
• 如果需要更深入背景，应该继续看哪些文档

所以，AGENTS.md 最适合承载的，不是“看代码就能知道”的信息，
而是那些不写出来，AI 很难稳定推断出来的东西。

比如：

• 真实模块边界
• 推荐阅读路径
• 优先排查入口
• 高风险修改点
• 术语解释
• 文档索引和知识地图

一个好用的 AGENTS.md，通常要满足三个原则

1. 只管这一层

每一层 AGENTS.md 都应该只解释自己覆盖的目录范围，不要跨层讲太多别处的事。

2. 只放高价值信息

它是高频注入的上下文，越短越好。
如果把大量背景描述都塞进去，只会浪费 token，也会稀释重点。

3. 表达要明确

尽量少写“尽量”“建议”“可以考虑”这种模糊表达。
AI 对模糊边界的执行稳定性，通常比人更差。

一个示例写法

如果前面的原则还是有点抽象，可以看一个脱敏且精简的示例。

假设有一个内容模块，目录很大，下面同时挂着首页、发布、详情和地点能力。
这时候，AGENTS.md 更适合写成一种引导文件，而不是把所有实现细节都堆进去。

例如：

# content-module

`content-module/` 是一个聚合型业务目录，承载首页、发布、详情和地点等多个子域能力。
它更像业务实现集合，不是一个稳定对外的独立组件。

## 关键约束

- 先判断需求属于哪个子域，再继续往下搜索，不要从整个目录盲改。
- 优先从路由入口、页面容器和状态管理层理解主链路，不要直接猜某个具体页面文件。
- 顶层容器通常只负责装配；子业务逻辑尽量落在各自子域，不要反向塞回容器层。

## 文档索引

- `./.ai/docs/overview.md`：看目录定位、边界和关键入口。
- `./.ai/docs/development-guide.md`：看修改策略、高风险区域和验证建议。

## 快速入口

- 首页相关：`home/`
- 发布相关：`publish/`
- 详情相关：`detail/`
- 地点相关：`poi/`

这个写法的重点不是“把目录解释得多完整”，而是做到三件事：

• 先交代定位：这是聚合目录，不是稳定 SDK，也不是单一页面
• 先给出约束：先分子域，再找入口，避免盲改
• 先给阅读路径：告诉 AI 下一步该去看哪份文档、哪个子目录

而更长的内容，例如“这个模块负责什么、不负责什么”“哪些区域改动风险高”“改完至少要验证哪些链路”，更适合拆到 overview.md 和 development-guide.md。

可以把它们理解成一组配套文档：

• overview.md 解决的是这个目录到底是什么，包括模块定位、边界判断、结构总览和推荐阅读顺序
• development-guide.md 解决的是在这里改代码应该怎么下手，包括常见修改落点、高风险区域、搜索建议和验证建议

换句话说：

AGENTS.md 更像入口说明，overview.md 负责建立模块认知，development-guide.md 负责指导实际改动。

五、哪些内容不适合写进 AGENTS.md？

AGENTS.md 很重要，但它不是“什么都往里塞”的地方。

最不适合放进去的，通常是两类内容。

1. AI 很容易自己看到的内容

比如目录树、文件列表、类名分布、函数名扫描结果。

这些内容本来就是 AI 能通过搜索直接获取的。
如果重复写进去，通常只会占上下文，不会真正提升效果。

2. 特别容易过期的内容

比如页面视觉细节、某个功能当前的完整行为描述、频繁变动的实现细枝末节。

这类内容一旦失效，就会从“帮助理解”变成“误导判断”。

更合适的做法通常是：

• AGENTS.md 只保留索引、边界和关键约束
• 长内容拆到 ./.ai/docs/
• 通过文档地图把知识串起来

例如：

## 文档索引

- `./.ai/docs/overview.md`：模块定位、边界和关键入口
- `./.ai/docs/development-guide.md`：修改策略、高风险区域和验证建议

这样既保留了入口，也避免把所有内容堆在一个文件里。

六、除了 AGENTS.md，还能怎么召回？

光靠目录级说明文件，通常还不够。
更大的文档知识，一般还需要另外两种召回方式。

1. 精准召回

做法是：在 AGENTS.md 里直接引用仓库内的具体文档路径。

适合内容：

• API 文档
• 模块术语表
• 功能入口说明
• 典型实现示例

它的优点是路径明确、歧义低、上下文完整性最好。
凡是“必须看原文，不能模糊理解”的知识，都适合用这种方式。

2. 按意图匹配

做法是：把知识和流程封装成 Skill，按任务意图决定是否加载。

适合内容：

• 业务探索
• 模块入口分析
• 技术方案生成
• 需求拆解
• 特定领域知识注入

它的价值不只是“带知识”，还可以顺带带流程、约束和执行建议。

3. 模糊搜索

做法是：把背景文档沉淀到知识库里，通过自然语言检索。

适合内容：

• PRD
• 技术方案
• 评审纪要
• 历史 BugFix 记录
• 重构背景说明

这类内容往往量大、变化快，也不适合全部塞进仓库。
它们更像“背景资料库”：
不是每次都要加载，但在需要时必须搜得到。

可以把这三种方式理解成三个层次：

精准召回   -> 我知道要看哪份文档
按意图匹配 -> 我知道自己要做哪类任务
模糊搜索   -> 我只知道大概问题，需要先找背景

七、上下文不是补文档，而是流程的一部分

如果把上下文建设理解成“业务做完以后顺手补点文档”，这件事通常坚持不久。

真正更有效的做法，是把上下文嵌进研发流程本身。

也就是说，上下文不是额外产物，
而应该随着需求流转、方案设计、代码实现一起自然产生。

1. 从需求理解到客户端需求拆解

一份产品需求真正变成客户端可执行内容，通常不只依赖 PRD 正文。

很多关键约束，其实散落在：

• 原始需求文档
• 流程图和示意图
• 评审纪要
• 评论区讨论
• 术语定义
• 排期和范围说明

如果这些信息没有被一起带进来，
AI 和新人看到的往往只是“表面需求”，而不是“真实约束”。

2. 从客户端需求到技术方案

AI 想写出靠谱代码，前提通常不是“模型足够聪明”，
而是它面前先有一份足够好的技术方案。

而一份高质量技术方案，通常依赖这些上下文：

• 技术评审结论
• 客户端与服务端的接口约束
• UI 或组件文档
• 对应模块的 AGENTS.md
• 模块下的补充文档

这里面最关键的现实是：

没有方案，AI 就只能猜；方案越清楚，AI 的输出越稳定。

这也是为什么上下文建设不能只停留在“目录说明”层面，
它必须进入需求拆解和方案生产这些关键环节。

八、最值得优先建设的上下文

如果资源有限，不可能一开始什么都做。
更实际的办法，是优先沉淀那些最能直接提高 AI 输出质量的内容。

1. 模块边界

告诉 AI：

• 这个模块负责什么
• 不负责什么
• 改动应该优先从哪里下手

边界一旦清晰，很多“误改到不该动的地方”的问题会立刻减少。

2. 术语和概念映射

在真实业务里，同一个概念常常会有多种叫法：
产品、服务端、客户端和运营侧的命名未必一致。

如果这层映射不沉淀，AI 很容易搜错方向，甚至把两个不同概念当成一个。

3. 关键入口和阅读路径

对大模块来说，真正高价值的信息通常不是“有哪些文件”，
而是：

• 应该先看哪个入口
• 数据流从哪里进
• 容器层和子业务怎么分工
• 页面、状态管理和视图层分别扮演什么角色

4. 高风险区域

告诉 AI 哪些地方改动成本高、联动范围大、容易引发连锁反应。

例如：

• 某些容器层耦合很高
• 某些公共模型改动会影响多个页面
• 某些老目录虽然还在，但不应该作为新增逻辑落点

5. 验证建议

对 AI 来说，写完代码从来不等于任务完成。

更关键的是，它要知道：

• 改这个模块至少要验证哪些主链路
• 哪些状态切换最容易出问题
• 哪些页面或交互区一定要回归

这些经验如果不沉淀，每次都只能靠熟悉业务的人临场提醒。

九、怎么评估上下文有没有价值？

上下文建设最容易陷入一个误区：
写了很多文档，但没人知道它们到底有没有用。

所以，真正重要的不是“写了多少”，而是：

这些上下文有没有在真实任务里，被 AI 有效使用。

比较值得关注的指标，通常有四类。

1. 召回次数

看哪些文档、技能、目录说明文件被频繁召回。
这至少能说明：它们经常和真实任务相关。

2. 真实使用情况

被召回，不等于被真正采纳。
还要进一步看，AI 在任务执行时是否真的用了这些信息做判断。

3. 指令遵循情况

如果某份上下文里写了明确约束，
就要看 AI 是否真的按这些约束选择了方案、修改点和验证路径。

4. 资源使用分布

统计不同资源的调用频率，也很有价值。

因为这能帮助团队看清楚：

• 哪些能力是高频刚需
• 哪些建设方向值得继续投入
• 哪些内容已经低价值甚至过期

度量的意义，不是做报表，
而是形成一个持续优化的闭环：

• 高价值内容继续建设
• 低价值内容及时淘汰
• 过期内容尽快清理
• 让知识库越来越准，而不是越来越大

十、最容易出现的误区

结合很多团队的实践，几个常见误区几乎都会重复出现。

1. 以为“文档越多越好”

不是。
真正的问题往往不是信息不够多，而是高价值信息不够准。

2. 以为“所有目录都要写 AGENTS.md”

也不是。
只有复杂度高、变化快、业务耦合强的区域，才值得重点维护。

3. 以为“写完就结束了”

上下文不是静态资产，而是持续演进的工程系统。
过期内容很多时候比没有内容更危险。

4. 以为“这是少数人的事”

也不是。
上下文建设必须嵌进日常研发流程，由模块负责人、方案设计者和实际开发者共同维护。

5. 以为“有了上下文，AI 就会自动全都做对”

上下文能显著降低猜测和误判，但它不是魔法。
它更像是在给 AI 提供稳定地面，而不是直接替代工程判断。

十一、这件事最终想解决什么？

如果用一句最直白的话来总结：

它想解决的，是“团队真正知道的东西，AI 还不知道”这件事。

而一旦这件事被系统化处理，带来的收益就不仅是 AI 写代码更准。

它还会顺带改善很多老问题：

• 新人理解模块更快
• 跨团队协作时背景更容易对齐
• 技术方案质量更稳定
• 历史经验不再只掌握在少数人手里
• 问题排查和需求落地更少依赖“某个最熟的人”

从这个角度看，上下文建设并不只是一个 AI 工具话题。
它其实是在倒逼团队把知识管理、模块边界和研发流程做得更工程化。

结语

很多团队谈 AI 落地时，最容易把注意力放在模型能力上。
但在真实客户端工程里，决定 AI 产出质量的，往往不是模型本身，而是你是否为它准备好了足够好的上下文。

模型决定了它“会不会做”，
上下文决定了它“会不会做对”。

所以，客户端 AI 上下文建设不是锦上添花，而是基础设施。

谁先把这套基础设施建起来，
谁就更有机会把 AI 从“偶尔好用的助手”，真正变成“稳定可靠的工程协作者”。