来源：腾讯云培训认证中心 · CodeBuddy 架构师认证课程 · ch4
第 四 章 · Chapter 4
上下文工程
本 章 学 什 么
-
理解上下文为什么重要 · 金发姑娘原则与四层优先级
-
熟练使用
@引用五种用法：Files / Folders / Terminal / Docs / Code -
掌握「最小上下文原则」+「分层投喂法」+ 预热 / 锚点 / 负面上下文进阶技巧
AI 不是全知全能的——它的每一次回答完全基于你给它的信息。信息不足它会瞎猜，信息过多它会混乱，信息精准它才高效。学会管理上下文，是从「能用 AI」到「用好 AI」的关键跃迁。
4.1 上下文为什么重要
金发姑娘原则
| 状态 | 结果 |
|---|---|
| 信息不足 | AI 瞎猜，生成的代码和你的项目格格不入 |
| 信息过多 | AI 混乱，抓不住重点。把 10 个不相关文件扔给它，它反而不知道你要干什么 |
| 信息精准 | AI 高效，生成的代码直接可用——给它看该看的文件，告诉它该做什么，产出可以直接合入 |
不能太多、不能太少、要刚刚好——这个平衡点需要你主动管理，不是 AI 的问题，是你"投喂"的问题。
上下文的四层结构
| 层级 | 来源 |
|---|---|
| 系统层 | Rules 文件 + CODEBUDDY.md——你提前配置好的规则 |
| 用户级 | 个人全局偏好设置——对你所有项目都生效 |
| 项目级 | 项目根目录的 CODEBUDDY.md 和项目 Rules——只在这个项目里起作用 |
| 对话级 | 本章核心——当次对话里 @ 引用的内容 + 你直接说的话。随时可用，随时可覆盖 |
优先级 · 考试要考
对话级 > 项目级 > 用户级 > 系统级——越靠近当次任务的，优先级越高。比如 Rules 写了"函数必须加注释"，但你在这次对话说"这次先别写注释"——AI 会听当次对话的。对话级是你用 @ 主动注入或在对话里直接说的，优先级最高，也是本模块的核心技能。
4.2 @ 引用五种用法
CodeBuddy 提供五种 @ 引用方式覆盖所有典型上下文需求——核心原则只有一个：给 AI 看它需要的，不多也不少。
五种 @ 引用
| 引用类型 | 典型用法 |
|---|---|
@Files |
精准引用文件——让 AI 阅读指定文件的完整内容。例：@Files src/components/UserCard.tsx 让 AI 参考这个组件的风格创建新组件 |
@Folders |
引用目录结构——让 AI 了解项目目录树，不需要阅读每个文件。例：@Folders components 让 AI 看完目录后帮规划新模块放在哪里 |
@Terminal |
引用终端输出——将报错信息或日志直接传给 AI。例：npm run build 出错后，引用终端输出让 AI 分析原因 |
@Docs |
引用文档——让 AI 参考项目文档或外部文档。例：选择 API 规范文档，让 AI 按文档接口规范实现数据获取层 |
@Code |
引用代码片段——选中编辑器中的一段代码精确引用。比选整个文件更精准，只让 AI 看你关心的那几行 |
使用注意事项
必须手动打出 @ 符号再引用——粘贴文本中的 @ 不会生效。
每次对话引用文件不超过 5 个。
优先引用类型定义和接口文件，而非实现文件。
对话变长时及时开新窗口或用锚点回顾。
4.3 上下文污染与最小上下文原则
四种常见的污染类型
| 污染类型 | 具体表现 |
|---|---|
| 陈旧信息 | 引用了已废弃的旧代码，AI 生成兼容旧代码的方案——方向就错了 |
| 噪声过多 | 把整个 500 行文件都扔给 AI，它抓不住重点，输出质量急剧下降 |
| 矛盾信息 | 对话前面说「用 REST」，后面又说「用 GraphQL」，AI 左右为难 |
| 跨任务污染 | 一个对话窗口讨论了 3 个不同功能，AI 把功能搞混——上一个任务的上下文干扰下一个 |
最小上下文原则
只给 AI 看它完成当前任务所需的最少信息。
反例——一次性引用 10 个文件：Header、Footer、Sidebar、UserProfile、SearchBar、api.ts……AI 被淹没在无关信息中。
正例——只引用 3 个相关文件：SearchBar.tsx（现有搜索组件）、useSearch.ts（搜索 Hook）、types/index.ts（只看 SearchResult 类型）。精准且足够。
黄金法则
一个任务一个对话——避免跨任务污染。 只引用相关文件——类型文件优先于实现文件、接口优先于内部逻辑、只给必要信息。 出问题时先缩减上下文——这是最有效的"急救"手段。
核心公式：输出质量 = 相关性 × (1 / 噪声量)——减噪就是提质
4.4 分层上下文投喂实操
每一步只引用上一步的产出，而不是把所有东西一股脑扔给 AI——这就是分层投喂的精髓。
四层投喂顺序
| 步骤 | 引用上下文 | 产出 |
|---|---|---|
| ① 文档→类型 | @Files docs/api-spec.md |
src/types/user.ts · TypeScript 类型定义（请求参数 + 响应类型） |
| ② 类型→API | @Files src/types/user.ts |
src/lib/api/user.ts · fetch 封装、统一错误处理、baseURL 从环境变量读取 |
| ③ API→Hook | @Files src/lib/api/user.ts |
src/hooks/useUsers.ts · useSWR 实现数据获取、缓存、增删改 |
| ④ Hook→页面 | @Files src/hooks/useUsers.ts |
页面组件 · 搜索栏 + 列表表格 + 分页 + 弹窗表单 + 删除确认（TailwindCSS） |
关键：每一层只看上一层的产出。Step 2 不需要再引用 API 文档——类型文件已经包含了所有需要的信息。这就是"分层"的含义。
**运行验证。**让 AI 检查环境、安装依赖、运行项目。如果报错，把错误截图发给 AI 修复——模型输出不是 100% 一致的，需要验证和微调。
4.5 进阶技巧
上下文预热
正式提需求之前，先让 AI「认识」你的项目。用法：先 @Folders src 让 AI 看目录结构，描述技术栈，告诉 AI 后续回答要保持与现有模式一致。
上下文预热 vs Rules · 这是考点
AI 每次对话不了解项目架构和技术栈 → 用上下文预热（每次开聊前热身）。
AI 生成代码风格跟项目不一致（命名、格式不对）→ 用 Rules（持久生效，写一次每次都管用）。
想让 AI 记住项目架构原则、每次自动生效 → 用 CODEBUDDY.md 或项目级 Rules。
预热是一次性的热身，Rules 是持久的约束——解决的问题不一样，别混用。
上下文锚点
对话变长后（10+ 轮），AI 会开始「忘记」早期信息。解决方法：在新任务开头加一段回顾——回忆用的是什么类型文件、API 在哪个文件、再提新需求。
负面上下文
有时候告诉 AI「不要做什么」比「要做什么」更有效——适用于：只想局部重构不想改接口、项目已上线不能破坏现有功能、团队规范明确限制某些做法。
| 场景 | 对比 |
|---|---|
| 反例 | 「帮我优化这个组件」——目标太宽泛，AI 可能顺手改 Props、换样式框架 |
| 正例 | 「重构这个组件，要求：不改 Props 接口、不引入新的第三方库、不修改 CSS 类名，只拆分内部逻辑提取子组件」——边界清晰，输出聚焦 |
**三个技巧的分工：**预热解决「AI 不了解项目」、锚点解决「AI 遗忘」、负面上下文解决「AI 越界」。
4.6 练习与自测
-
**API 对接实战（必做）。**找一个公开 API（JSONPlaceholder、GitHub API），把文档喂给 CodeBuddy，用分层上下文法逐步生成：类型 → API 函数 → Hook → 页面。记录每一步给了哪些上下文
-
**上下文污染实验（推荐）。**故意给 AI 过多无关文件，观察输出质量。然后精简到最少文件，对比输出。记录两次的差异——这个实验会让你对"噪声"有切身体会
-
**整理上下文策略（必做）。**为你最常做的 3 种开发任务，各设计一套上下文投喂策略：需要引用哪些文件、按什么顺序、哪些信息需要排除
本章小结
-
原理——AI 输出质量 = f(上下文精准度)。金发姑娘原则：不多不少刚刚好。四层优先级：对话级 > 项目级 > 用户级 > 系统级
-
@ 引用五种用法——Files / Folders / Terminal / Docs / Code，每次不超过 5 个文件，优先类型和接口文件
-
污染与最小原则——四种污染（陈旧 / 噪声 / 矛盾 / 跨任务）。核心：只给 AI 完成当前任务所需的最少信息
-
分层投喂——文档 → 类型 → API → Hook → 页面，每步只引用上一步产出
-
进阶——预热（AI 先认识项目）/ 锚点（对话变长回顾）/ 负面上下文（明确禁止项）
下一模块进入**「Speckit 规约驱动开发」**——上下文解决了「AI 看什么」的问题，下一讲解决「怎么系统化地驱动 AI 做完整项目」的问题。