@ 文件引用

高手复盘里有个判断被反复提到：

@ 文件引用是被低估的能力。

新手用 Claude Code，习惯把代码复制粘贴进对话框——挑几行贴过去，问「这段有什么问题」。这种做法有两个毛病：一是容易漏，你挑的几行可能漏了关键上下文；二是信息不全，Claude 看到的是片段，不知道这个文件整体长什么样、被谁调用。

@ 引用解决的就是这个。它让 Claude 直接读文件，比手动复制粘贴更完整、更少遗漏。

@ 引用单文件

最基础的用法——在 prompt 里打 @ 加文件路径：

> 看 @src/utils/auth.js，这个文件里的 token 验证逻辑有什么问题？

Claude 会用 Read 工具读这个文件，拿到完整内容——不是你挑的片段。它能看见整个文件的结构、所有函数、所有边界处理，判断才准。

> 帮 @src/components/Header.tsx 加上响应式断点。

这种引用比「帮 Header 组件加响应式」明确得多——你直接告诉它改哪个文件，没有歧义。

@ 引用目录

@ 不只能引用文件，还能引用整个目录：

> 通读 @src/payment/ 目录，画一份模块依赖图。

Claude 会把这个目录下的所有相关文件都读进来，给你一份完整的依赖关系。比你说「看看支付模块」要精确——它不会漏掉哪个子目录，也不会读岔到别的地方。

引用目录的场景：

摸清一个子系统的全貌
审查整个模块的代码质量
重构前先看清所有相关文件

@git：引用 git 输出

@ 还能引用 git 命令的输出。这是高手复盘里特别推荐的一招。

引用某个 commit：

> 看 @git show a3f5e1c，总结这个 commit 的目的。

Claude 会读这个 commit 的 diff，告诉你：这次改动干了什么、是重构还是行为变更、影响范围有多大。比你自己逐行读 diff 快得多。

引用最近几次提交：

> 看 @git log -5 --patch，把最近 5 次提交区分成「重构」和「行为变更」两类。

让 Claude 帮你区分哪些 commit 是纯重构（不改行为）、哪些改了行为——这是写 release note、评估回归风险时特别有用的活。

@git 的价值在于：让 Claude 直接拿 git 的原始输出，而不是你手动复制 diff 贴过去。git 输出可能很长、很乱，手动复制容易漏行、容易截断，@ 引用让 Claude 自己拿全。

比手动复制粘贴好在哪

对比一下：

维度	手动复制粘贴	@ 引用
完整性	你挑几行，可能漏上下文	读整个文件/目录
准确性	容易漏行、截断	拿到完整原始内容
上下文	只看到片段	知道文件整体结构
效率	你手动选、复制、粘贴	一句话搞定

最大的差别是完整性。你复制粘贴时，是按你的理解挑内容——但你可能不知道哪几行才是关键。@ 引用让 Claude 拿到全貌，它的判断不会被你的片段选择限制。

管道：cat error.log | claude

除了 @，还有一条路把外部内容喂给 Claude：Unix 管道。

cat error.log | claude "总结这个错误日志的根因"

把日志、文件、命令输出通过管道喂进去，Claude 拿到 stdin 直接处理。适合：

喂一份很大的日志
把别的命令输出交给 Claude 分析
在脚本里把 Claude 串进流水线

# 把测试失败的输出交给 Claude 分析
npm test 2>&1 | claude "总结失败的测试，给出修复建议"

# 把某个命令的输出交给 Claude
kubectl get pods | claude "哪些 pod 状态异常？"

管道和 @ 的分工：@ 引用文件系统里的东西，管道喂任意命令的 stdout。两者都能让 Claude 拿到「你没手动复制的内容」。

让 Claude 自己 fetch：Bash/MCP/Read

更高阶：有些内容不在本地文件系统，需要 Claude 自己去拿。这时候让它用工具自己 fetch：

> 用 Bash 跑 curl https://api.example.com/health，把返回结果分析一下。
> 用 Read 工具读 ~/.config/app.yaml，看里面数据库配置对不对。
> 用 MCP 的 fetch 工具把这个 URL 的内容拉下来总结。

这比「你先跑命令、复制输出、贴回去」自然得多——让 Claude 自己拿，自己消化，你只管提需求和看结论。

参考官方 common-workflows 里的「Pipe Claude into scripts」「Reference files and directories」两条——核心思路一脉相承：别当人肉中转站，让 Claude 直接读、直接拿。

一句话总结

@ 文件引用是被低估的能力：@src/utils/auth.js 引用单文件、@src/payment/ 引用目录、@git show 引用 git 输出，比手动复制粘贴更完整更少遗漏。管道 cat error.log | claude 喂任意输出，让 Claude 用 Bash/MCP/Read 自己 fetch。别当人肉中转站。

下一步，去看并行开发 6 纪律——怎么同时开多个 Claude 不打架。🚀