2.5 文件引用与上下文
预计耗时：12 分钟
本关任务简报
很多新手问 Claude 问题时是这样的："帮我优化这个函数"——然后发现回答很泛，感觉 Claude 在猜你在说什么。
问题不是 Claude 不够聪明，而是它没看见你的代码。
Claude Code 不会自动读取你的整个项目。当你问问题时，它只能看到当前对话里已经有的信息。如果你没有明确把文件内容带进来，它就只能根据文字描述来猜。
这一关解决的就是这个问题：如何精准地把文件、命令输出、网页内容注入到对话里，让 Claude 基于真实内容回答，而不是凭空推测。
通关奖励：解锁以下技能
- 📂 用
@文件名把文件内容带入对话 - 📁 引用整个目录或用 glob 模式批量引用文件
- 🌐 直接粘贴 URL 让 Claude 读取网页内容
- ⚡ 用
!命令执行 shell 命令并把结果注入对话 - 💡 知道什么时候需要主动引用上下文，什么时候 Claude 会自己去读
开始前先检查装备
| 前置知识 | 说明 |
|---|---|
| 2.3 斜杠命令指南 → | 理解输入框里 @、!、/ 三种前缀的区别——本关主要讲前两个 |
机制解析
Claude 怎么获取文件内容
有两种方式：
方式一：Claude 自己主动去读
当你说"帮我看看 src/utils.ts 有没有问题"时，Claude 会自己调用 Read 工具读取这个文件，不需要你手动引用。
方式二：你主动用 @ 把内容带进来
当你说 @src/utils.ts 帮我看看有没有问题，文件内容会作为你消息的一部分直接放进对话上下文，Claude 在开始思考前就已经看到了。
大多数时候两种方式效果相似。但有一个明显的差别：你想让 Claude 对比多个文件、或者在提问的同时就让它看到内容时，主动引用更直接。
@文件 — 引用单个文件
在输入框输入 @ 后会自动触发文件路径补全，继续输入文件名可以筛选：
@src/utils/auth.ts 这个函数的逻辑有什么问题？@package.json @tsconfig.json 帮我检查这两个配置是否一致支持相对路径和绝对路径，可以同时引用多个文件。
@目录/ — 引用整个目录
@src/components/ 帮我梳理一下这些组件的职责分工引用目录时，Claude 会读取该目录下的所有文件。注意 token 消耗——一个大目录可能消耗大量上下文空间，用 /cost 查看当前用量。
Glob 模式 — 批量引用符合条件的文件
@src/**/*.test.ts 检查测试文件的覆盖情况@**/*.md 帮我整理一下所有文档的主题和结构支持标准 glob 语法，可以跨目录批量引用同类型文件。
粘贴 URL — 引用网页内容
网页不走 @（@ 只补全本地文件路径），直接把 URL 贴进消息即可，Claude 会自动抓取网页内容加入上下文：
https://docs.example.com/api 根据这份文档帮我写一个调用示例适合引用 API 文档、README、技术规范等公开页面。
限制：需要登录才能访问的页面无法直接抓取。如果页面需要浏览器渲染（JavaScript 动态加载），需要配置 Playwright MCP 才能正常获取内容（见 2.12 MCP 服务器 →）。
!命令 — 执行命令并注入结果
! 前缀让 Claude 执行一条 shell 命令，并把命令输出自动带入对话：
!npm run test
帮我分析测试失败的原因!git log --oneline -20
总结一下最近 20 次提交做了什么，有没有值得关注的风险!cat error.log
这段错误日志说明什么问题？! 和普通问话的区别：如果你直接说"帮我分析测试结果"，Claude 需要自己调用工具跑一次测试。用 !npm run test 是你先跑好，把结果交给 Claude 分析，效率更高。
什么时候不需要手动引用
Claude Code 在以下情况会自己去读文件，不需要你 @：
- 你说"帮我看
xxx.py"——它会自己 Read - 它在执行任务时需要了解某个文件——它会主动读
- 你让它修改代码——它会先读再改
需要你主动引用的场景：
- 你想在提问的同时就带上内容，让回答更精准
- 你需要 Claude 同时对比多个文件
- 你已经有了命令输出，想直接把结果传给 Claude（用
!） - 你想引用外部 URL 的内容
控制 token 消耗
引用大量内容时，token 消耗会快速增加。几个实用技巧：
- 引用前先用
/cost看看当前用量 - 能引用具体文件就不要引用整个目录
- 对话太长时用
/compact压缩，或/clear开新会话 - 引用 URL 时优先选内容精简的文档页面，避免引用首页或长文
开始闯关
目标：用 @ 引用一个真实文件，让 Claude 基于文件内容回答你的问题。
第 1 步：用 @ 引用一个文件
在你的项目里找一个文件（比如 README.md 或 package.json），在输入框里输入：
@README.md 帮我用一句话总结这个项目是做什么的观察 Claude 的回答——它应该基于文件的实际内容来回答，而不是说"我不知道这个项目是什么"。
第 2 步：用 ! 把命令结果带进来
如果你的项目有 git，输入：
!git status
根据这个状态，告诉我现在有哪些未提交的改动观察 Claude 是基于实际的 git 状态来回答的，而不是通用解释。
通关检定
- [ ] 用
@文件名成功引用了一个文件，Claude 的回答明显基于文件内容 - [ ] 知道输入
@会触发路径补全 - [ ] 用
!命令成功把命令输出带进了对话 - [ ] 知道引用目录和大文件时要注意 token 消耗
- [ ] 知道什么时候需要主动引用、什么时候 Claude 会自己读
全部点亮就算通关 ✓
卡关了？翻车指南在这
粘贴网页 URL，但 Claude 说读取失败或内容不对
常见原因：① 页面需要登录才能访问；② 页面依赖 JavaScript 渲染，静态抓取拿不到内容。前者换成不需要登录的公开 URL，后者需要配置 Playwright MCP。
引用了文件，但 Claude 说"我没有看到这个文件的内容"
踩坑清单：① 检查路径是否正确，相对路径从当前工作目录起算；② 确认文件存在且不为空；③ 文件编码如果不是 UTF-8 可能导致读取失败。
!命令 执行了，但 Claude 没有基于输出回答
把 !命令 和你的问题放在同一条消息里，而不是先发命令、再发问题。Claude 在处理你的消息时才会把 ! 的输出注入上下文。
引用了一个大目录，对话变得很慢
大目录会消耗大量 token，导致响应变慢甚至超出限制。改为只引用具体需要的文件，或者直接告诉 Claude 文件路径让它自己去读。
下一关
每次对话的上下文都是有限的——这一关告诉你如何合理管理对话的生命周期，在该清空时清空，在需要继续时接续。