先看要点

想让 Claude Code 参考某份本地代码、配置或说明文档，最直接的做法是在提示中用 @ 引用具体路径，再写清楚希望它据此完成什么。发送前核对引用的文件，收到回复后让它指出依据；如果目标文件在项目目录之外，还要留意会话的文件访问范围。以下介绍引用方法、核实步骤和常见限制。

Claude Code 怎么读取指定文件？用 @ 和完整路径点名

Claude Code 的官方常见工作流文档提供了通过 @ 引用文件或目录的方法。路径可以使用相对路径，也可以使用绝对路径。在输入框中键入 @，还可以打开路径建议菜单，选择目标路径后再发送提示。

例如，想让它解释配置逻辑，可以这样写：

请先参考 @src/config.ts，解释其中 apiTimeout 配置的用途和默认值。先说明依据，不要修改文件。

如果任务需要对照说明文档和实现代码，可以同时列出多个文件：

请对照 @docs/payment-requirements.md 和 @src/payment/client.ts，说明客户端实现是否覆盖文档中的重试要求。先列出你在两个文件里找到的相关内容，不要编辑代码。

路径应尽量写到目录层级。只说“看看配置文件”可能让目标不明确：项目里可能有开发、测试和生产配置，文件名也可能重复。明确的路径和任务分开写，既告诉 Claude Code 要看什么，也告诉它要从文件里找什么信息。

怎么确认 Claude Code 读的是正确文件？

引用路径并不等于它的分析一定准确。尤其是涉及接口行为、权限、数据写入或配置切换时，建议先让 Claude Code复述依据，再让它给结论或提出修改。

  1. 检查路径。查看提示中显示的文件引用，确认目录和文件名都正确。同名文件应写全路径，例如 @src/server/config.ts，而不是只写 config.ts。
  2. 要求说明依据。让它列出相关的函数名、配置项或文档段落，并用简短摘要说明这些内容与问题的关系。必要时加上“先不要修改”。
  3. 对照原文件。打开被引用文件，核对它提到的名称和内容是否真实存在。若回复里出现不存在的字段、路径或要求，先请它重新检查指定文件，不要顺着错误结论继续改动。
  4. 确认后再推进。确认它理解的是正确内容后，再要求分析、修改或运行测试。若任务会改文件，可以先要求它解释计划和改动范围，再检查最终差异。

例如可以补一句：请先指出 src/payment/client.ts 中负责重试的函数，并说明对应逻辑；如果找不到，请明确说没有找到，不要推测。这能帮助你区分“它给出了看起来合理的答案”和“答案确实来自指定文件”。

引用目录和项目外文件时要注意什么？

引用目录不等于读入目录里的所有文件

官方文档说明，引用目录会显示文件列表，不会自动把目录中每个文件的内容都加入对话。因此，若需要分析某个源文件，应直接引用文件路径；若只想先了解目录结构，引用目录再询问有哪些模块或文件较合适。目录很大时，可以先从列表中选出相关文件，再逐个引用，避免把“看到了文件名”误当成“读过文件内容”。

目标文件在项目目录之外

Claude Code 的文件读取权限受工作目录和附加目录设置影响。官方权限文档说明，工作目录及已添加的目录中的只读文件读取通常无需单独批准；若文件在项目外，当前会话未必能访问它。可以先查看 Claude Code 是否报告了路径或权限错误，不要仅凭它的推测认定文件已读取。

官方文档提供了 --add-dir 用于给会话增加目录访问范围。例如，在启动时添加一个确实需要访问的相邻目录：claude --add-dir ../shared-config。是否适用应按本机当前版本的说明和实际目录结构确认；只添加任务必需的目录，不要为了省事扩大访问范围。额外目录的文件访问与该目录下项目指引文件是否加载不是同一件事，相关配置也要查看官方说明。

文件很长或要参考多份资料时怎么办？

引用文件时，Claude Code 会在符合条件的情况下将内容加入对话。官方常见工作流文档注明，默认 Read 工具令牌限制为 25,000；超过 256KB 的文本文件不会通过该文件引用方式纳入对话。这个限制可能影响它能直接参考的内容，不应假设引用成功就代表整份大文件都已进入上下文。

面对长文档或多份资料，把任务拆小会更容易核对。先告诉它优先参考哪份文件、关注哪个章节或函数，再要求它说明找到的依据；确认这一部分无误后，再补充其他文件。比如先核对需求文档中的“错误重试”段落与实现函数，再讨论测试是否覆盖相同条件。若它表示无法读取、只看到目录列表，或无法确定具体范围，就根据反馈缩小目标、补充可访问路径，不能把猜测当作已读取。

提示中也可以写明文件的用途：@docs/requirements.md 是需求依据，@tests/payment.test.ts 是现有测试。请先分别总结与超时处理有关的内容，再指出两者是否一致；不要修改文件。这样比一次性要求它“分析整个项目”更聚焦，也方便逐项检查。

什么时候该用 CLAUDE.md，而不是每次都引用文件？

单次任务需要参考的需求稿、配置或代码，通常直接在当次提示中用 @路径 点名即可。若某些约定会在项目的许多会话中反复使用，例如测试命令、代码风格或固定工作流程，再考虑写入项目级 CLAUDE.md。官方记忆文档将它定位为持续提供给 Claude 的项目指引，并说明 Claude 会在会话开始时读取相应指引文件；它不是用来取代每次任务的文件定位。

官方常见工作流文档还说明，文件引用会把目标文件所在目录及父目录中的 CLAUDE.md 加入上下文。因此，引用文件时也应留意这些指引是否包含与任务相关的约定。临时资料不要为了“让它记住”就全部塞进项目指引；指引应聚焦稳定、反复适用的项目事实，也不要把密钥、访问令牌或不应共享的个人资料放进去。

让 Claude Code 读取文件的安全顺序

读取文件和允许修改文件是不同的操作。特别是配置、密钥文件、用户数据或生产环境资料，先确认目标内容是否适合提供给工具，再明确任务边界。对需要改动代码的工作，可以按下面的顺序进行：

  1. 在提示中引用准确路径，写清楚要解决的问题和不要触碰的范围。
  2. 要求它先复述相关文件中的依据，并在无法读取时明确报告。
  3. 核对路径、字段、函数或文档内容确实存在。
  4. 确认之后再让它提出修改方案；涉及写入时，检查工具权限提示和实际差异。

例如：请阅读 @src/config.ts，解释 timeout 的配置链路。只分析，不要修改；如果该文件不可访问，请告诉我具体路径和错误，不要用其他文件推断。这类提示同时限定了文件、目标和操作边界。本文涉及的文件引用、目录引用与权限信息依据 Claude Code 官方文档整理，核查日期：2026年10月9日；具体界面和行为请以当前安装版本为准。