AI Agent / 系统课时
引用文件与目录
引用文件与目录
本课学习如何把“看看相关代码”变成精确上下文。你将使用 @ 引用单个文件、目录和多个目标,并根据引用类型判断 Claude Code 实际获得的是文件内容还是目录清单。
学习目标
- 使用
@快速引用文件和目录 - 理解文件引用与目录引用的差异
- 避免一次加入过多无关上下文
引用单个文件
在交互输入中键入 @ 会触发路径补全。选择文件后,Claude Code 会把该文件内容加入当前会话,适合解释函数、审查配置或限定修改对象。
请解释 @src/auth/login.ts 中登录失败的处理流程,并指出相关测试位置。先不要修改文件。这是会话输入示例,不是 Shell 命令。相对路径通常以当前工作目录为基础,也可以使用绝对路径,但共享提示词时应优先使用稳定的仓库相对路径。
引用文件并不自动证明它是完整实现。该文件可能依赖接口定义、配置或调用方,因此可以要求 Claude 先说明还需要读取哪些文件,再继续调查。
引用目录
目录引用主要提供目录清单和文件信息,不会自动把目录下所有文件内容全部加入上下文。它适合了解结构、筛选候选文件,而不适合要求 Claude 立刻解释每个实现细节。
请根据 @src/auth/ 的目录结构,找出登录入口、令牌处理、权限校验和测试文件。先列出候选路径,再按需读取。这种写法先让 Claude 建立文件地图,再读取少量关键文件。对于大型目录,比直接要求“读取整个目录”更节省上下文,也更容易追踪结论来源。
同时引用多个目标
一个请求可以引用多个文件,用于比较实现、核对接口与测试,或追踪跨文件行为。引用数量仍应围绕一个目标,不要把所有“可能相关”的文件一次塞入。
比较 @src/order/OrderService.java 与 @src/order/OrderController.java 的职责边界,并检查 @src/test/order/OrderServiceTest.java 是否覆盖取消订单的失败分支。若文件名或目录很多,先用自然语言说明它们之间的关系。Claude 才能知道某个文件是主要实现、契约定义还是验证证据。
引用代码位置的写法
交互补全的核心单位是文件路径。需要聚焦具体位置时,可在文字中同时写出符号名或行号范围,例如“重点查看 createOrder 方法”和“解释第 80~120 行附近的异常处理”。行号会随修改变化,长期协作更适合使用稳定的类名、函数名或配置键。
当同名符号存在多个实现时,应同时给出路径和完整符号。若目标由框架动态注册,还要引用路由、依赖注入或配置文件,不能只看实现类。
控制上下文质量
精确引用的目标不是让 Claude 读得越多越好,而是让它获得足够证据。通常先引用入口文件,再让 Claude 搜索依赖;只有结论需要时才补充更多文件。
敏感文件不应因为方便而直接引用,例如包含密钥的 .env。应通过权限配置禁止访问,并提供脱敏示例。任何引用都要服从项目的安全边界。