上下文是一切：@引用/文件/符号/规则怎么喂才准
- 理解模型只看你给的上下文、看不到脑子里内容的底层机制，不再靠猜
- 熟练用 @文件、@符号、@文件夹、@docs、规则文件五种姿势精准喂上下文
- 掌握"喂多少才对"的权衡思路，避免上下文太满稀释注意力
- 用喂上下文 checklist 和故障排查表独立排查 AI 改错/幻觉的根本原因
同样一个 AI 编程工具，有人用起来像开了挂——改一个函数全套测试跟着更新，重构一个模块所有调用点一起联动；有人用起来天天翻车——它改错了文件，编了个根本不存在的 API，改完代码反而多出三个新 bug。
差距不在工具、不在模型、不在智商。差在喂上下文的功底。
为什么上下文是 AI 编程的命脉
先搞清楚机制，不然后面所有技巧都是无源之水。
模型只能看到你给它的上下文，它看不到你脑子里的东西。
这句话听起来像废话，但大多数人用 AI 编程工具翻车的根源，都在于忘了这一点。你"知道"这个函数是个工厂方法、你"知道"这个文件依赖另一个模块的类型声明、你"知道"项目约定用 snake_case——这些你脑子里觉得理所当然的东西，模型一个字都看不到，除非你显式地喂给它。
它拿到什么就基于什么工作。喂对了，它的输出会精准地符合你项目的结构；喂错了或者喂少了，它会凭自己的"猜测"补全——也就是幻觉。
具体说：
- 喂了无关文件：它的注意力分散了，可能把另一个文件的模式套到你的场景里
- 漏喂关键依赖：它不知道类型定义在哪、接口约定是啥，就自己编一套
- 没说清楚项目约定：它按通用最佳实践来，结果和你现有代码风格格格不入
- 任务描述太模糊：它猜你的意图，猜对了是运气，猜错了还得你改
用一个比喻：你把一个刚入职的高手工程师单独关在一个房间，只通过文字传纸条协作。他再厉害，看不到代码库就是没法干活。你得主动把他需要的信息递进去。
五种喂法：@引用、文件、符号、文件夹、规则文件
@文件：最基础、最常用
在对话里直接用 @文件路径 把某个具体文件纳入上下文。
语法（Claude Code / Cursor 通用思路）：
@src/api/userService.ts 帮我在 getUserById 下面加一个 getUsersByRole 方法，签名风格跟现有方法保持一致
什么时候用：
- 你要改的文件本身
- 这个改动依赖的类型定义文件
- 类似功能的参照文件（"按这个文件的风格来"）
反例：不要说"帮我在 userService 里加个方法"然后不带文件。它要么猜不到 userService 在哪，要么找到了但你没法确认它找的是不是对的那个。
@符号：精确到函数/类
当文件很大，你只需要让它关注某个函数或类时，用符号级引用。
@getUserById 这个函数有个边界 case 没处理：userId 是 0 的时候应该返回 null 而不是抛异常，帮我修一下
Cursor 里可以用 @symbol 语法；Claude Code 里可以先选中代码再提问，或者在任务描述里明确"在 getUserById 函数里"。
价值：避免把一个 800 行的文件全塞进上下文，只把相关函数喂进去，注意力更集中。
@文件夹：给它一张地图
有时候任务涉及一个模块的整体结构，你不知道具体哪些文件会被改动，这时候喂整个文件夹的目录结构。
@src/components 帮我做一个 UserCard 组件，风格和目录里已有的 ProductCard 保持一致，包括 props 类型声明的写法
注意：文件夹引用一般是喂目录结构，不是把所有文件内容全塞进去（那样上下文会爆）。它给了模型一张地图，知道这个模块有什么。
@docs：喂官方文档/内部文档
当你要用一个它可能不熟悉的库、或者要符合某个内部文档规范时，把文档内容直接喂给它。
@https://docs.example-lib.com/api/v2/authentication 按这个文档帮我实现 OAuth2 的 PKCE 流程
或者把内部 wiki 的关键段落粘贴进对话，明确标出来："这是我们的 API 约定规范，下面按这个来"。
特别适用：用 MCP 接入实时文档源，可以让它直接查特定版本的官方文档，而不是凭训练数据猜。
规则文件：一次配置，永久生效
以上四种都是"一次性喂"——每次对话都得重新喂。规则文件是"永久性喂"：你把项目约定写进规则文件，它每次对话都自动加载。
Claude Code 用 CLAUDE.md（放在项目根目录）：
# 项目规则
- 所有函数命名用 camelCase，不用 snake_case
- 类型声明统一放在 src/types/ 目录
- 不要使用 class，用纯函数 + 组合
- 测试文件放在 __tests__ 目录，命名为 xxx.test.ts
- 错误处理统一用 Result 类型，不抛异常
Cursor 用 .cursorrules 或 Cursor 的 Rules for AI 功能，效果类似。
规则文件的威力在于：你不需要每次对话都解释一遍"我们项目用什么约定"。这是让 AI 真正融入你代码库的关键，而不是作为游客来帮你写代码。详细用法见 规则文件渐进配置实战（3.5 节）。
喂多少才对：权衡和口诀
这是大多数教程跳过的部分。
喂上下文不是越多越好。模型的注意力是有限的——上下文太满，重要信息会被稀释，它的回复质量反而下降。
极端的例子：有人把整个几千行的代码文件塞进去，只让它改一个两行的函数。结果它改了，但同时"顺手"改了几个它觉得不对的地方，而那些地方并不是你想碰的。
口诀：精准够用，不是越多越好。
实操判断：
| 喂什么 | 什么时候喂 |
|---|---|
| 你要直接修改的文件 | 必须喂 |
| 这个文件依赖的类型定义 | 如果任务涉及类型，必须喂 |
| 相似的参照文件 | 让它保持风格时喂，不超过 2 个 |
| 整个文件夹内容 | 不喂，喂目录结构即可 |
| 无关的背景文件 | 不喂 |
| 任务无关的历史对话 | /clear 清掉，开新对话 |
另一个实用判断：如果你自己都说不清这个文件和当前任务的关系，就不要喂。上下文对你来说模糊，对它来说更模糊。
喂上下文 checklist
每次发任务之前，过一遍这个 checklist：
- 任务本身说清楚了吗？（"加个功能"太模糊；"在 UserService 里加 getUsersByRole 方法，参数是 role: string，返回 User[]，用现有的 DB 连接"才够清晰）
- 要改的文件喂进去了吗？
- 依赖的类型定义 / 接口文件喂进去了吗？
- 有没有需要保持一致风格的参照文件？（喂 1-2 个）
- 项目约定写进规则文件了吗？（一次性配好，后面不用每次想）
- 上下文里有没有无关的文件需要清掉？（开新对话 or
/clear） - 任务边界说清楚了吗？（"只改这个函数，不要动其他地方"）
故障排查表
| 症状 | 原因 | 解法 |
|---|---|---|
| 它改错文件了 | 没有明确指定文件，它自己猜了一个 | 用 @文件路径 明确喂目标文件；或在任务里写明"只改 src/api/user.ts" |
| 它编了个根本不存在的 API | 没喂相关库的文档或类型定义，它凭训练数据补全 | 把对应的 .d.ts、官方文档或 @docs 链接喂进去；或明确说"不要用你不确定的 API，不确定的地方标出来" |
| 改完代码风格和项目格格不入 | 没有规则文件，它按通用最佳实践来 | 在 CLAUDE.md 或 .cursorrules 里写明项目约定 |
| 它"顺手"改了不该动的地方 | 上下文太宽，任务边界不清晰 | 任务里加"只修改 xxx 函数，不要改其他地方"；缩小喂的上下文范围 |
| 类型不对，编出来的代码跑不了 | 类型定义文件没喂 | 把 types.ts 或相关 .d.ts 用 @ 加进来 |
| 它忽视了之前说好的约定 | 对话太长，规则被早期内容冲淡；或没用规则文件 | /clear 开新对话，重新喂关键上下文；把约定固化进规则文件 |
| 每次都要重复解释项目背景 | 没有规则文件 | 花 20 分钟把项目核心约定写进 CLAUDE.md，一劳永逸 |
进阶：上下文工程的两个思维升级
从"让它帮我写代码"到"让它读懂这个项目"
入门阶段用 AI 工具是"临时雇一个帮手"——每次交代任务都要从头解释背景。进阶之后是"培养一个懂你项目的协作者"——通过规则文件、持续更新的项目文档，让它对代码库的理解越来越深。
上下文是双向的
不只是你喂给它，它的输出也是下一轮的上下文。好的上下文工程包括：把它上一次的输出里有问题的部分明确指出来（"这里类型不对，应该是 string[] 不是 string"），而不是重新发一个新任务让它从头来。错误的上下文越早纠正，后续偏差越小。
关于上下文消耗和 token 管理的深层问题，见 上下文工程：管好 token 防飘移（4.3 节）。
常见问题
Q：规则文件该写多长？
没有固定标准，但宁短勿长。5-10 条核心约定比 50 条大而全的规则有用——太长了它扫一遍记不住，你自己维护也累。先写最痛的几条，用的时候发现漏了再补。
Q：@文件 和直接粘贴文件内容到对话里有什么区别？
效果基本相同，都是把内容放进上下文。@文件 语法更清晰，工具能追踪你引用了哪些文件，方便它自己管理；直接粘贴更直接但对话容易变长变乱。推荐用 @ 语法，它是为这个场景设计的。
Q：Cursor 和 Claude Code 的上下文喂法有什么差别？
核心逻辑相同，语法略不同。Cursor 有图形界面，可以直接在 Chat 面板里点击文件名引用，也支持 @ 语法；Claude Code 是终端里的 @路径。规则文件方面，Cursor 用 .cursorrules，Claude Code 用 CLAUDE.md。两个工具都在迭代，具体语法以官方文档为准，逻辑完全相通。
Q：喂了规则文件，它还是不遵守约定，怎么办？
先检查规则文件是不是真的被加载了（可以问它"你知道我们项目有什么约定"，看它的回答）。如果加载了但不遵守，可能是约定写得太模糊——"代码要好"不算规则，"函数命名用 camelCase，文件命名用 kebab-case"才算。另外，对话太长时规则可能被冲淡，/clear 开新对话试试。
下一步去哪
这节讲的是单次任务里怎么喂上下文。更复杂的场景是长任务里怎么用 Plan 模式让 AI 先想清楚再动手，3.2 Plan 模式：先想清楚再动手 接着展开。
关于 token 消耗和更系统的上下文管理策略，见 4.3 上下文工程：管好 token 防飘移。
工具使用细节：Claude Code 工具 / Cursor 工具。
回到 AI 编程教程大全 确认自己在哪个位置。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。