用了几天 Claude Code 之后我最大的感受是这工具能力上限不取决于模型而取决于你会不会“喂”它。很多人装上之后只会说“帮我写个登录接口”“看看这段代码有什么问题”结果 AI 要么答非所问要么改出来的东西和项目结构完全不搭。原因很简单——你没有告诉它该看哪些文件、哪个目录、什么上下文。说白了Claude Code 里引用文件和目录就是你跟这个 AI 结对编程的第一步也是最关键的一步。这篇文章就围绕“如何在 Claude Code 中引用文件和目录”这件事把我自己实际踩过的坑、验证过的姿势、推荐的工作流全部整理出来。不管你是刚装好 Claude Code 准备试试水还是已经在项目里用了几天但总觉得 AI 不够聪明这篇都适合你。我会从底层逻辑讲起再给具体的命令示例、实操案例和问题排查尽量做到你看完就能直接用。1. 先搞清楚 Claude Code 引用的底层逻辑1.1 一次对话里 AI 到底能看到什么很多人有个错觉我都在项目目录里启动 Claude Code 了AI 应该知道我这个项目长什么样吧真不是。Claude Code 启动后它手里只有你当前会话里出现的文本以及它通过工具调用读取到的文件内容。项目目录本身不会自动灌进它的脑子它不知道你有哪些文件、哪些目录、哪些依赖除非你告诉它或者让它去扫。这个“告诉它”的过程就是引用。你可以直接在对话里写文件路径也可以用符号显式引用某个文件或目录。引用之后文件内容会作为上下文的一部分传给模型AI 才能真正“看到”这段代码。这就好比你在公司请了一个非常聪明但完全没来过你工位的远程实习生你得明确告诉他你看看桌子上第二摞文件里的第三份或者你先把整个抽屉的目录扫一遍。理解这一点之后很多使用问题就迎刃而解了——AI 答非所问大概率不是模型不行而是你让它看的东西不对或者压根没让它看。1.2 引用不是复制粘贴它是上下文管理有朋友问我自己把代码复制粘贴给 AI 不就行了当然行但问题在于Claude Code 的优势是它可以直接读取文件、修改文件、执行命令形成一个闭环。如果你靠复制粘贴那和用网页版聊天窗口没区别而且粘贴大段代码会迅速消耗你的上下文额度。Claude Code 的上下文窗口是有限的你引用进来的每个文件、每行代码都会占用 token。所以“引用”这个动作的背后是一门上下文管理的学问既要让 AI 看到足够多的信息又不能让它被无关内容淹没。我自己的原则是“最小充分原则”——只引用完成任务最需要的文件先给少的不够再加。这比一次性把整个项目塞给它要高效得多也省钱。2. 引用单个文件的几种方式与选型建议2.1 直接说路径 vs 显式引用在 Claude Code 里引用单个文件最简单的姿势就是在对话里直接写上文件路径。比如帮我看看 src/main.py 这个文件有没有内存泄漏风险这种情况下Claude Code 通常会识别出你提到了一个已有文件并按需读取它。但更稳定、更推荐的做法是用符号显式引用src/main.py 帮我看看这个文件有没有内存泄漏风险显式引用的好处是明确告诉工具“我要把这段文件内容塞进上下文”不依赖模型自己去猜。尤其是当路径比较长、或者文件名容易产生歧义的时候符号基本不会出错。我在实际使用中如果只是简单问答直接写路径就够了但如果要执行的是一系列修改任务我倾向于先用把核心文件引用进来确认 AI 理解之后再让它动手改。这样整个会话的上下文是干净、可控的。2.2 相对路径和绝对路径选哪个更顺手Claude Code 支持相对路径和绝对路径但我的建议很简单尽量用相对路径并且尽量在项目根目录启动 Claude Code。举个例子假设你的项目在D:/work/fastapi-project你在这个目录下启动 Claude Code那么引用app/main.py就是指D:/work/fastapi-project/app/main.py。这样写起来短看着也清楚。如果你在app子目录里启动了 Claude Code再引用main.py就变成相对当前目录了容易搞混。还有个小技巧在对话里输入/pwd或直接问 AI “当前工作目录是哪”让它先确认一下路径再开始干活。我踩过一次坑在错误的目录层级里让它改文件它改了另一个同名文件差点把备份覆盖掉。从那以后我每次进入项目都先确认目录位置再开始引用文件。2.3 同一个会话里批量引用多个文件实际开发任务很少只涉及一个文件。改一个接口可能要同时看路由、模型、数据库连接三个文件。Claude Code 支持在一个问题里引用多个文件比如app/routers/users.py app/models/user.py app/schemas/user.py 请给用户详情接口补充返回手机号字段注意同步调整 schema。一次把相关文件都引用进来AI 就能在它们之间做关联分析而不是只看一个文件瞎猜。这个能力非常实用。不过要注意引用多个文件时上下文消耗是累加的别一口气引用十几个大文件否则可能在 AI 真正开始修改之前上下文就被塞满了。更合理的做法是分批引用——先引用核心业务文件让它给出方案确认方向后再引用辅助文件做具体实现。3. 目录引用、深度控制与多文件批处理3.1 目录引用的真实含义索引而非全量阅读比引用单个文件更强大的操作是引用整个目录。你可以在对话里写app/ 先看一下这个项目的整体结构然后告诉我它是什么类型的项目。这个操作会让 Claude Code 扫描app目录把所有文件名、目录层级、文件大小等组织成一份结构索引喂给模型。注意“索引”这两个字——它不一定会把每个文件的完整内容都读进去而是先让 AI 知道“这个目录里有什么”相当于先给它一张地图。这张地图非常关键。因为 AI 拿到目录结构后就能判断项目类型、技术栈、模块划分然后进一步决定要深入看哪些文件。比如你给它app/目录的索引它看到里面有routers/、models/、schemas/这些子目录基本就能猜出这是一个 FastAPI 项目。接下来你再让它看某个具体文件它的理解会快很多因为它已经有全局认知了。3.2 目录太深时怎么控制读取范围引用目录虽好但不能乱用。如果你的项目目录有几十层嵌套AI 扫描起来会很慢而且生成的上下文会被大量无用的文件名占据。这时候你就需要控制读取深度。我常用的做法是在引用语句里明确说清楚要看哪一层、不看什么。比如app/ 只看第一层子目录和文件不要递归进入 migrations 和 node_modules。或者更精确一点直接指定要看的子目录app/routers app/services app/models 列出这些目录里的文件并说明各自作用。这种做法比app/全量扫描更精准速度也更快。越是老项目、越是依赖繁多的项目越要控制目录引用的范围不然等同于给自己买了一个超大上下文账单。3.3 通配符与批量引用让 AI 处理一批同类型文件除了目录引用Claude Code 还支持一定程度的模式匹配。比如你想让 AI 检查所有测试文件可以这样写tests/test_*.py 帮我看看这些测试有没有断言写得不到位的地方。通配符配合目录引用能非常高效地圈定一批相关文件。我经常用它做重构前的风险排查——把某个模块下所有文件都用通配符引用进来然后让 AI 分析它们之间的依赖关系。这种操作如果靠手动一个个不仅费时间还容易漏文件。需要注意的是通配符匹配的文件越多上下文压力越大。在大型项目里我更建议先引用目录拿到文件清单再挑出真正要深入处理的那几个文件而不是一把梭全塞进去。4. CLAUDE.md 和 .claudeignore长期上下文的双引擎4.1 CLAUDE.md 就是你的项目说明书如果你和我一样每天都在同一个项目里用 Claude Code那你一定会有这种体验每次新开一个会话都要重新跟 AI 解释一遍项目背景、技术栈、目录结构、代码规范。太累了。Claude Code 的解决方案是CLAUDE.md文件——一个放在项目根目录的说明文件每次启动会话时会被自动加载作为背景上下文。简单说它就是你的项目说明书让 AI 从第一句话开始就“知道自己在哪”。我自己的CLAUDE.md一般包含四块内容项目简介、目录结构说明、常用命令、开发规范。目录结构说明那一节会专门写清楚“业务代码在哪个目录、测试代码在哪个目录、新增模块应该放哪里”这正好呼应了我们前面说的目录引用能力——CLAUDE.md 让 AI 不需要每次扫描就知道目录长什么样。4.2 我的 CLAUDE.md 模板可直接抄下面是我当前一个 FastAPI 项目的CLAUDE.md模板做了脱敏你可以直接参考# 项目简介 这是一个基于 FastAPI 的后端服务负责提供用户管理和订单查询接口。 技术栈Python 3.11 / FastAPI / SQLAlchemy / PostgreSQL。 # 目录结构 - app/main.py 应用入口创建 FastAPI 实例并注册路由 - app/routers/ 路由层按业务模块划分 - app/services/ 业务逻辑层 - app/models/ SQLAlchemy 模型 - app/schemas/ Pydantic 请求/响应模型 - tests/ 测试目录使用 pytest # 常用命令 - 启动开发服务uvicorn app.main:app --reload - 运行测试pytest tests/ - 生成迁移alembic revision --autogenerate -m message # 开发规范 - 所有时间字段使用 UTC 存储 - 接口统一返回 {code: 0, data: ..., message: ok} - 模型层禁止写业务逻辑一律放到 services这个文件写好后我每次新开会话AI 自动就了解了项目定位和结构后面引用文件时指哪打哪不用再解释“这个项目是干什么的”“目录怎么组织的”。这一步做完等于给后续所有引用操作铺好了地基。4.3 .claudeignore给上下文装一个防火门有CLAUDE.md还不够你还需要一个.claudeignore文件。它和.gitignore的作用类似用来告诉 Claude Code哪些目录和文件不要读、不要扫、不要出现在上下文里。我见过很多人忽略这个文件结果引用app/目录时AI 连.pyc缓存文件、__pycache__、node_modules、dist这些目录都扫一遍整个上下文瞬间被垃圾文件占满真正重要的代码反而没地方放了。我的.claudeignore长这样__pycache__/ *.pyc node_modules/ dist/ build/ .git/ .venv/ venv/ .DS_Store配好之后引用目录扫描的速度快了一倍不止上下文也干净了。这个文件的优先级很高建议大家项目一初始化就建好别等上下文爆了再想起来。4.4 什么时候该更新 CLAUDE.md 和 .claudeignore两个文件都不是一次写完就完事的。我自己的习惯是每当项目结构发生大的变化新增模块、迁移目录、换技术栈就顺手更新CLAUDE.md每当发现 AI 的上下文里有大量无用文件就补充.claudeignore。另外还有一个细节CLAUDE.md里也可以记录你和 AI 的“约定”。比如你发现 AI 总是用print()调试而我们项目强制用logger就在规范里写死。这个文件本质上是你和 AI 之间的协作契约越写越顺。5. 实操案例让 Claude Code 5 分钟读懂一个 FastAPI 项目5.1 准备一个典型的项目结构为了更直观地说明引用文件和目录的完整流程我拿一个最常见的 FastAPI 项目举例。假设目录结构是这样的fastapi-project/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── routers/ │ │ ├── __init__.py │ │ └── users.py │ ├── models/ │ │ ├── __init__.py │ │ └── user.py │ ├── schemas/ │ │ ├── __init__.py │ │ └── user.py │ └── services/ │ ├── __init__.py │ └── user_service.py ├── tests/ │ └── test_users.py ├── requirements.txt └── CLAUDE.md这个结构很常见但如果你不告诉 Claude Code它也只能从文件名里猜个大概。现在我们要做的是让 AI 不需要猜直接精确理解这个项目并完成一次修改任务。5.2 分步引用流程实录第一步我会先引用根目录建立全局认知fastapi-project/ 先看看这个项目的整体结构。AI 会返回目录树并基于文件名判断这是一个 FastAPI 项目指出routers是路由层、models是模型层、schemas是序列化层。到这里它已经有了一副完整的地图。第二步引用最关键的几个业务文件让它深入理解核心逻辑app/main.py app/routers/users.py app/services/user_service.py 请说明这几个文件的数据流转关系并告诉我用户数据从请求到数据库的完整路径。AI 会结合这几个文件内容画出一条链路路由接收请求 → 服务层处理业务 → 模型层映射数据库。这个理解不是凭空猜的而是基于我们显式喂给它的文件内容。第三步给它一个具体任务app/routers/users.py app/schemas/user.py 给 GET /users/{user_id} 接口增加一个可以缓存 60 秒的响应头 返回体保持现有结构不变。由于前面两步已经把项目结构和数据流讲清楚了AI 可以直接修改users.py引用schemas/user.py是为了让返回结构不被破坏。整个过程下来不需要复制粘贴任何代码所有修改都是基于引用上下文完成的。5.3 这个流程里容易出问题的两个细节第一个细节是“先看功能再动手改”。我见过很多朋友一上来就app/routers/users.py 帮我加个缓存头AI 确实会改但它可能不理解整个项目的代码风格改出来的代码和周边代码风格不一致。先花一分钟引用目录、梳理结构再动手效果完全不一样——这就好比做手术之前先看片子不是看完片子就不做手术了但看了片子做手术才靠谱。第二个细节是“改完必须看 diff”。哪怕前面引用流程很顺畅AI 修改完文件之后你也应该检查改动是否符合预期。我一般会直接用 Git 的 diff 查看改动或者让 Claude Code 自己总结它改了哪些文件、为什么这么改。这一步不属于引用操作但没有它前面的引用全白做。6. 常见问题与排查技巧实录6.1 明明引用了文件AI 还是答非所问这是新手最容易遇到的问题具体表现是你src/main.py把文件引用了AI 却在聊别的内容或者回答得特别泛。我排查这个问题的顺序很固定先确认文件路径是否写对了。src/main.py但实际文件在src/app/main.py引用就直接失败了。再看是不是上下文太乱。同一个会话里聊了太多无关话题早期被清理掉的文件内容可能已经不在上下文里了。如果这两个都没问题我会直接问 AI“刚才我让你看的src/main.py里函数xxx是干什么的”用一个具体问题验证它是否真的“看到”了文件。实测中八成的情况是文件路径写错这倒不是眼神问题而是 AI 自动补全路径时可能把相近文件名张冠李戴。所以我强烈建议路径关键部分自己手工输入别完全依赖自动补全。6.2 引用完整目录时扫描太慢、上下文感觉不够用这种情况常见于老项目。目录一大索引本身就占上下文再加上后续深入看文件很容易在会话进行到一半就感觉 AI “变笨了”。我的解法有三板斧第一.claudeignore里加过滤把node_modules、dist、__pycache__全部排除。第二缩小引用范围用app/routers而不是app/用tests/test_*.py而不是tests/。第三如果上下文还是不够直接在对话里执行清理或压缩操作让会话瘦身然后再重新引用关键文件。说白了上下文就是你的工作台你不能把全公司的文件都堆在桌上堆不下不说找东西也难。6.3 AI 改了文件但本地代码没有变化这种情况通常不是引用问题而是权限或模式问题。先检查你启动 Claude Code 时是不是用了某种只读模式或者 AI 只是给了建议而没有真正执行文件写入。我一般会明确要求它“直接修改文件并把改动后的完整内容展示出来”同时用git status确认本地文件是否真的变了。还有一个隐蔽原因AI 修改了文件但修改的是另一个同名文件。这又回到我们前面说的路径问题——相对路径不一样改的东西就不一样。遇到这种情况先pwd确认目录位置再强调“请修改当前工作目录下的app/routers/users.py”。6.4 AI 误改了不该动的文件这个问题的根源多半是“引用范围过大 权限描述不清”。你让 AI “看着办”它就容易把不相干的文件也顺手改了。解决办法很直接在引用时把改动范围限定死。比如你可以说“只修改app/routers/users.py其他文件不允许改动。”或者更稳妥一点在开始改之前让它先把修改计划列出来你确认后再动手。这种“计划先行”的方式会大幅降低误改的概率。我自己的习惯是在会话开始时就声明“这次任务只涉及哪些文件不涉及哪些目录”。这个声明在长会话里尤其重要因为 AI 的上下文不断滚动早期的约束会被冲淡多强调几次没坏处。6.5 快速排查参考表问题可能原因快速排查方法引用了没反应路径写错 / 文件不存在用ls确认路径再重新上下文不够目录引用范围过大用.claudeignore过滤无关目录缩小引用粒度AI 答非所问上下文被无关内容冲淡/clear开新会话只引用必要文件改了文件没变化只读模式 / 改了另一个文件用git status和pwd双重确认目录扫描太慢大目录未过滤检查.claudeignore拆分引用范围AI 误改文件引用范围太宽缺少边界声明明确告知只改哪些文件先出计划再动手最后再分享一个我自己摸索出来的工作流习惯我会把“引用文件”这个动作前置到每个任务的第一步并且总是先从 CLAUDE.md 里带出的目录结构做一次快速确认再决定引用哪些文件。这套流程看起来多花了几秒钟实际在复杂项目里省下来的时间是以小时计的。如果你试完发现 AI 还是不够聪明回头看看自己是不是太省事连目录都不让它扫、CLAUDE.md 也不写就想让它给你写出完美架构。给它一张地图、几份关键文件它给你的反馈会完全不是一个级别。