AI 上下文控制完整教程#

这篇笔记的范围

学会用 @ 精准控制 AI 看什么、不看什么，掌握「最小上下文」思路，减少跑偏与上下文污染。 练习目标：用 3–5 个文件完成一次「类型 → API → Hook → 页面」的分层生成。如果输出开始混乱，可以先移除无关文件，再用新对话处理一个具体任务。

目录#

核心公式与心智模型
上下文的四个层级
为什么上下文如此重要
@ 符号引用指南
上下文污染与最小上下文原则
分层上下文投喂实战
上下文预热、锚点与负面指令
实操练习
回顾与延伸

一、核心公式与心智模型#

核心公式

AI 输出质量 = f(上下文精准度) 上下文精准度 = 相关性 × (1 / 噪声量)

这个公式是一切方法论的起点。AI 不是全知全能的，它的每一次回答完全基于你给它的信息。你不能指望它「猜中」你项目里的隐藏约定；你给得越精准，它输出得越可用。

当信息不足时：AI 瞎猜 → 生成的代码和你的项目格格不入。
当信息过多时：AI 混乱 → 抓不住重点，输出质量下降。
当信息精准时：AI 高效 → 生成的代码直接可用。

所以我们的目标是追求「相关性高、噪声量低」的上下文组合，而不是「越多越好」。

二、上下文的四个层级#

AI 实际「看到」的信息来自四个不同层级，理解它们才能有意识地控制：

层级	来源	特点	控制方式
系统层	Rules 文件	自动加载，持久生效	编辑 `.codebuddy/rules/`
会话层	当前对话历史	随对话积累	开新对话清空
指令层	`@` 引用	精准注入	主动选择
隐式层	当前打开的文件	自动感知	切换/关闭文件

金发姑娘原则（Goldilocks Principle）：上下文要「不多不少刚刚好」——太少 AI 乱猜，太多 AI 混乱，精准才高效。

实践提示

系统层与隐式层是「被动」进入上下文的，最容易被忽视；指令层（@）才是你主动调控的杠杆，本教程重点就在它。

三、为什么上下文如此重要#

把上下文想成 AI 的「工作记忆」：

1
信息不足 → AI 瞎猜 → 生成的代码和你的项目格格不入
2
信息过多 → AI 混乱 → 抓不住重点，输出质量下降
3
信息精准 → AI 高效 → 生成的代码直接可用

很多新手以为「把整个项目丢给 AI 最省事」，结果恰恰相反——AI 在 500 行噪声里找不到你真正想要的那一行，反而产出最平庸的代码。后面第⑤节会专门讲「上下文污染」，这里先建立直觉：少即是多。

四、@ 符号引用指南#

最关键的一条

必须手动打出 @ 符号再引用需要的内容，否则直接粘贴示例里的 @ 不会生效。

4.1 `@Files` —— 精准引用文件#

用途：让 AI 阅读指定文件的完整内容。

语法

1
@Files src/components/UserCard.tsx

典型场景

1
请参考 @Files src/components/UserCard.tsx 的风格，
2
帮我创建一个 ProductCard 组件，展示商品图片、名称、价格和评分。

进阶：多文件引用

1
请阅读以下文件：
2
@Files src/types/user.ts
3
@Files src/types/product.ts
4

5
然后创建一个 OrderType，关联 User 和 Product。

注意事项

每次对话引用的文件 不要超过 5 个，否则上下文过长。
优先引用类型定义文件和接口文件，而不是实现文件（实现细节 AI 可以自己写，约定才是它最需要的）。

实操项目提示

本次配套练习在 practice-project 文件夹下进行。

4.2 `@Folders` —— 引用目录结构#

用途：让 AI 了解项目目录结构，而不必阅读每个文件。

语法

1
@Folders components

典型场景

1
看一下 @Folders components 的目录结构，
2
我想新增一个 Dashboard 模块，请规划它的文件结构，与现有结构保持一致。

适用：规划新功能的文件组织、了解项目整体架构、确保新代码放在正确的位置。AI 会先读取结构再规划文件布局并说明各核心文件职责；你应先审阅规划、确认符合预期后再执行。

4.3 `@Terminal` —— 引用终端输出#

用途：把终端的报错信息、日志等直接传递给 AI。

典型场景

1
运行 npm run build 后出现以下错误：
2
@终端
3

4
请帮我分析原因并修复。

最佳实践

只引用相关的终端输出，不要引用整个历史。
报错信息 + 触发命令一起提供（让 AI 知道「你做了什么才出现这个错」）。
如果错误信息很长，可以只截取关键部分。

4.4 `@Docs` —— 引用文档#

用途：让 AI 参考项目文档或外部文档。

典型场景

1
根据 @Docs 中定义的接口规范，
2
帮我实现前端的数据获取层，使用 useSWR。

易错点

点击 Docs 后还需选择具体文档才会真正生效。

4.5 `@Code` —— 引用代码片段#

用途：选中编辑器中的代码片段，精确引用（而不是整文件）。

典型场景

1
@Code 片段
2
请解释这段代码的逻辑。

五种引用速查

@Files：完整文件内容
@Folders：目录结构
@Terminal：终端报错/日志
@Docs：项目/外部文档
@Code：选中片段

五、上下文污染与最小上下文原则#

5.1 什么是上下文污染#

当你给 AI 的信息包含不相关或误导性内容时，输出质量会急剧下降。

污染类型	描述	后果
陈旧信息	引用了已经废弃的旧代码	AI 生成兼容旧代码的方案
噪声过多	把整个 500 行文件都扔给 AI	AI 抓不住重点
矛盾信息	对话前面说「用 REST」，后面又说「用 GraphQL」	AI 左右为难
跨任务污染	一个对话窗口讨论了 3 个不同的功能	AI 把功能搞混

5.2 最小上下文原则（Minimum Context Principle）#

一句话

只给 AI 看它完成当前任务所需的最少信息。

不推荐（上下文过载）

1
帮我写一个搜索功能。
2

3
@Files src/components/Header.tsx
4
@Files src/components/Footer.tsx
5
@Files src/components/Sidebar.tsx
6
@Files src/components/UserProfile.tsx
7
@Files src/components/SearchBar.tsx
8
@Files src/lib/api.ts
9
@Files src/types/index.ts
10
@Files src/hooks/useAuth.ts
11
@Files src/hooks/useSearch.ts
12
@Files src/styles/globals.css

推荐（精准上下文）

1
帮我完善搜索功能，要求：
2
1. 支持防抖（300ms）
3
2. 搜索结果高亮匹配关键词
4
3. 支持键盘导航（上下箭头 + Enter）
5

6
参考现有代码：
7
@Files src/components/SearchBar.tsx     ← 现有搜索组件
8
@Files src/hooks/useSearch.ts           ← 现有搜索 Hook
9
@Files src/types/index.ts              ← 类型定义（只看 SearchResult 类型）

5.3 一条实用原则#

一次对话只做一件事，避免跨任务污染。
矛盾需求拆成顺序指令，不要并存于同一段话。
宁可少给，让 AI 反问「还缺什么」，也不要堆噪声。

六、分层上下文投喂实战#

场景设定

后端同事给了你一份 API 文档，你需要在前端实现完整对接。实操项目在 api-practice-project 文件夹下。

6.1 分层构建链路#

每一步只引用上一步的产出，而不是把所有东西一股脑扔给 AI。这就是「分层上下文投喂」的精髓：

1
API 文档（源头）
2
   ↓ 引用文档
3
类型定义（数据结构）
4
   ↓ 引用类型文件
5
API 请求函数（网络层）
6
   ↓ 引用 API 文件
7
自定义 Hook（状态层）
8
   ↓ 引用 Hook 文件
9
页面组件（视图层）

6.2 Step 1：准备 API 文档 `docs/api-spec.md`#

1
# 用户管理 API
2

3
## 获取用户列表
4
- GET /api/users
5
- Query: page(number), pageSize(number), keyword(string)
6
- Response: { code: 200, data: { list: User[], total: number }, message: "success" }
7

8
## 获取用户详情
9
- GET /api/users/:id
10
- Response: { code: 200, data: User, message: "success" }
11

12
## 创建用户
13
- POST /api/users
14
- Body: { name: string, email: string, role: "admin" | "user" }
15
- Response: { code: 200, data: User, message: "success" }
16

17
## 更新用户
18
- PUT /api/users/:id
19
- Body: Partial<User>
20
- Response: { code: 200, data: User, message: "success" }
21

22
## 删除用户
23
- DELETE /api/users/:id
24
- Response: { code: 200, data: null, message: "success" }
25

26
## User 类型
27
- id: number
28
- name: string
29
- email: string
30
- role: "admin" | "user"
31
- avatar: string
32
- createdAt: string (ISO 8601)

6.3 Step 2：文档 → 类型#

1
阅读 @Files docs/api-spec.md，然后帮我：
2
1. 在 src/types/user.ts 中定义完整的 TypeScript 类型
3
2. 包含 API 请求参数和响应的类型
4
3. 包含通用的 API 响应包装类型

6.4 Step 3：类型 → API 请求层#

1
基于 @Files src/types/user.ts 中的类型定义，
2
在 src/lib/api/user.ts 中创建完整的 API 请求函数：
3
1. 使用 fetch 封装
4
2. 统一错误处理
5
3. 支持 TypeScript 类型推导
6
4. baseURL 从环境变量读取

6.5 Step 4：API 层 → Hook#

1
基于 @Files src/lib/api/user.ts 中的 API 函数，创建以下 Hook：
2
1. useUsers(params) —— 获取用户列表，支持分页和搜索
3
2. useUser(id) —— 获取单个用户详情
4
3. useCreateUser() —— 创建用户（包含 loading 和 error 状态）
5
4. useUpdateUser() —— 更新用户
6
5. useDeleteUser() —— 删除用户（带确认）
7

8
使用 useSWR 实现数据获取和缓存。

6.6 Step 5：Hook → 页面#

1
基于 @Files src/hooks/useUsers.ts 中的 Hook，创建一个用户管理页面，包含：
2
1. 顶部搜索栏 + "新增用户"按钮
3
2. 用户列表表格（姓名、邮箱、角色、创建时间、操作）
4
3. 分页控件
5
4. 新增/编辑用户的弹窗表单
6
5. 删除确认弹窗
7

8
使用 TailwindCSS 样式，参考 Linear 的设计风格。

6.7 Step 6：运行与修复#

1
运行项目，先检查环境是否适配，不适合的话先安装适配依赖。

注意

由于模型给出的代码并不完全一致，运行项目出现错误时，请把报错界面截图再发回模型修复即可。

6.8 关键总结#

注意每一步我们是如何分层构建上下文的：每一步只引用上一步的产出。这比「一次性把所有文件丢进去」稳定得多，也更容易在出错时定位是哪一层的问题。

七、上下文预热、锚点与负面指令#

当对话变长、或跨多个功能时，单纯的「精准引用」还不够，需要更高阶的上下文控制技巧。

7.1 预热技巧（Preheating）#

在正式提需求之前，先让 AI 「认识」你的项目。

适用场景

你刚切到一个新项目
你要连续做 2–3 个相关功能
你希望 AI 输出风格与现有代码保持一致

错误用法（直接开干）

1
帮我做一个用户列表页面。

结果：AI 可能改用 React Query、改造目录结构，返工多。

正确用法（先预热再提需求）

1
我先让你了解一下项目结构：
2

3
@Folders src
4

5
目前项目使用 Next.js 14 + TailwindCSS，
6
状态管理用 Zustand，数据获取用 useSWR。
7

8
接下来我会让你帮我实现几个功能，
9
请在后续的回答中保持与项目现有模式的一致性。

结果：更容易沿用 useSWR + Zustand 现有模式，返工更少。

7.2 锚点技巧（Anchoring）#

当对话变长时，用「锚点」帮 AI 回忆关键信息。

适用场景

会话已经超过 10 轮
中间切过多个任务（列表、详情、导出）
你发现 AI 开始「忘记」既定类型或文件位置

错误用法（不回顾上下文）

1
现在加导出 CSV。

症状：AI 把导出字段写成 user_name，而现有类型是 name。

正确用法（先锚点再继续）

1
（接上面的用户管理功能）
2

3
回顾一下：
4
- 我们用的是 @Files src/types/user.ts 中的 User 类型
5
- API 层在 @Files src/lib/api/user.ts
6

7
现在帮我给用户列表添加"导出 CSV"功能。

效果：AI 会优先复用 User 类型，字段漂移明显减少。

7.3 负面上下文（告诉 AI「不要什么」）#

有时候告诉 AI 「不要做什么」比「要做什么」更有效。

适用场景

你只想局部重构，不想改外部行为
项目已上线，接口与样式不能被破坏
团队规范明确限制依赖与命名

错误用法（目标宽泛，边界缺失）

1
帮我优化这个组件。

风险：AI 可能顺手改 Props、替换样式体系。

正确用法（明确禁止项）

1
帮我重构这个组件：
2
@Files src/components/Dashboard.tsx
3

4
要求：
5
- 不要改变任何对外的 Props 接口
6
- 不要引入新的第三方库
7
- 不要修改现有的 CSS 类名
8
- 只拆分内部逻辑，提取子组件

效果：输出聚焦在「内部拆分与可读性优化」，可直接合并概率更高。

八、实操练习#

练习 1：API 对接#

找一个公开 API（如 JSONPlaceholder、GitHub API）
把 API 文档喂给 AI
用分层上下文法，逐步生成：类型 → API 函数 → Hook → 页面
记录每一步你给了哪些上下文

练习 2：对比不同上下文的输出#

故意给 AI 过多无关文件，观察输出质量
然后精简到最少文件，对比输出质量
记录两次的差异

练习 3：整理常用任务的上下文#

为你最常做的 3 种开发任务，各设计一套上下文投喂策略：

需要引用哪些文件？
按什么顺序提供？
哪些信息需要排除？

九、回顾与延伸#

整理上下文时，可以按下面几项检查：

熟练使用 @Files / @Folders / @Terminal / @Docs / @Code
理解并能应用「最小上下文原则」
能按「分层投喂」的顺序组织信息，提高稳定性
能识别常见的上下文污染并做排查
用一套清晰的上下文包完成一次 API 对接练习

回顾核心公式

AI 输出质量 = f(上下文精准度) 上下文精准度 = 相关性 × (1 / 噪声量)

接下来如果要做小范围修改，可以结合内联编辑与心流里的例子：先选中相关代码，再说明要改什么、哪些行为要保留。

一页速记

上下文四层：系统 / 会话 / 指令(@) / 隐式
五个 @ 工具：Files、Folders、Terminal、Docs、Code
两大原则：最小上下文、分层投喂
三大技巧：预热、锚点、负面指令
口诀：精准引用、逐层递进、少即是多

音乐

AI 上下文控制完整教程#

目录#

一、核心公式与心智模型#

二、上下文的四个层级#

三、为什么上下文如此重要#

四、@ 符号引用指南#

4.1 `@Files` —— 精准引用文件#

4.2 `@Folders` —— 引用目录结构#

4.3 `@Terminal` —— 引用终端输出#

4.4 `@Docs` —— 引用文档#

4.5 `@Code` —— 引用代码片段#

五、上下文污染与最小上下文原则#

5.1 什么是上下文污染#

5.2 最小上下文原则（Minimum Context Principle）#

5.3 一条实用原则#

六、分层上下文投喂实战#

6.1 分层构建链路#

6.2 Step 1：准备 API 文档 `docs/api-spec.md`#

6.3 Step 2：文档 → 类型#

6.4 Step 3：类型 → API 请求层#

6.5 Step 4：API 层 → Hook#

6.6 Step 5：Hook → 页面#

6.7 Step 6：运行与修复#

6.8 关键总结#

七、上下文预热、锚点与负面指令#

7.1 预热技巧（Preheating）#

7.2 锚点技巧（Anchoring）#

7.3 负面上下文（告诉 AI「不要什么」）#

八、实操练习#

练习 1：API 对接#

练习 2：对比不同上下文的输出#

练习 3：整理常用任务的上下文#

九、回顾与延伸#

文章分享

评论区

音乐

音乐

文章目录

音乐

AI 上下文控制完整教程

AI 上下文控制完整教程#

目录#

一、核心公式与心智模型#

二、上下文的四个层级#

三、为什么上下文如此重要#

四、@ 符号引用指南#

4.1 @Files —— 精准引用文件#

4.2 @Folders —— 引用目录结构#

4.3 @Terminal —— 引用终端输出#

4.4 @Docs —— 引用文档#

4.5 @Code —— 引用代码片段#

五、上下文污染与最小上下文原则#

5.1 什么是上下文污染#

5.2 最小上下文原则（Minimum Context Principle）#

5.3 一条实用原则#

六、分层上下文投喂实战#

6.1 分层构建链路#

6.2 Step 1：准备 API 文档 docs/api-spec.md#

6.3 Step 2：文档 → 类型#

6.4 Step 3：类型 → API 请求层#

6.5 Step 4：API 层 → Hook#

6.6 Step 5：Hook → 页面#

6.7 Step 6：运行与修复#

6.8 关键总结#

七、上下文预热、锚点与负面指令#

7.1 预热技巧（Preheating）#

7.2 锚点技巧（Anchoring）#

7.3 负面上下文（告诉 AI「不要什么」）#

八、实操练习#

练习 1：API 对接#

练习 2：对比不同上下文的输出#

练习 3：整理常用任务的上下文#

九、回顾与延伸#

文章分享

评论区

音乐

音乐

文章目录

4.1 `@Files` —— 精准引用文件#

4.2 `@Folders` —— 引用目录结构#

4.3 `@Terminal` —— 引用终端输出#

4.4 `@Docs` —— 引用文档#

4.5 `@Code` —— 引用代码片段#

6.2 Step 1：准备 API 文档 `docs/api-spec.md`#