文件读写与目录

Claude Code 干活的核心，就是读文件、改文件、找文件。这几件事全靠五个基础工具。理解它们的分工与边界，你才不会在大项目里被卡住。

五个基础工具

Claude Code 处理磁盘文件靠五个内建工具。它们是 Read、Edit、Write、Glob、Grep。每一个只做一件事，组合起来能覆盖几乎所有的文件操作场景。理解它们的分工，你才能预判 Claude Code 下一步会怎么动作，也才能在结果不对时准确说出该改哪一环。

• Read：按绝对路径读一个文件，输出带行号的文本。默认最多读两千行，可以带 offset 和 limit 精确读某一段。图片、PDF、Jupyter notebook 都支持。
• Edit：对已读过的文件做精确替换，改的是一个具体的字符串片段，不覆盖整个文件。有一条硬约束，old_string 在文件里必须唯一，否则报错。
• Write：新建文件或者整体重写。有一个隐含规则，改动现有文件必须先 Read，Claude Code 才允许 Write，这是防误覆盖的最后一道锁。
• Glob：按文件名 pattern 找文件，比如 **/*.ts。结果按修改时间排序，你不用自己 ls -lt。
• Grep：按正则搜文件内容。底层跑的是 ripgrep，速度比原生 grep 快一个数量级，还能自动跳过被 gitignore 排除的目录。

一次典型的调查流程通常是这样：Glob 或 Grep 定位到相关文件 → Read 挑重点段落 → Edit 做小改动或者 Write 整体重写。

大文件怎么处理

日志、生成物、大 JSON 是最常见的大文件类型。硬读整个文件既费上下文又慢。正确的做法是分段读。

Read tools/dump.json 从第 500 行读 200 行

或者更直接地跟 Claude Code 说：

这个日志文件几十兆，别一次全读。先 tail 最后两百行看有没有异常，
再按关键词定位到出错那段前后各五十行贴给我。

Claude Code 会自动使用 Read 的 offset 和 limit 参数分段拉取。想搜关键词就用 Grep，它对大目录也很快。

小提示

只要能靠 Grep 定位就别靠 Read 硬扫，一个查关键词的操作可能比一次全文读快几十倍，还省上下文。

@file 语法与路径规则

在 REPL 里输入 @ 会触发文件补全。这是把某个文件塞进本轮上下文的最快方式，比让 Claude Code 自己搜要精准得多，也省掉一次工具调用。

@src/routes/auth.ts 帮我加个刷新 token 的接口

@file 的路径按当前项目根解析，写相对路径最方便。你也可以传绝对路径，跨项目引用文件时用得上。

关于绝对路径 vs 相对路径有几条经验值得记住：

• Claude Code 的工具调用大多要求绝对路径，例如 Read 的 file_path 参数。你在 Prompt 里说相对路径没关系，模型会自己拼。
• 跨会话或者 -p 模式下，相对路径的基准可能不是你想的那个目录，写绝对路径最稳。
• Windows 上尤其要注意，见下面这一节。

Windows 路径避坑

Windows 用户最常见的坑是反斜杠。Claude Code 内部大量工具走 POSIX 风格的路径解析，尤其是 Bash 工具。

• Bash 工具跑的是 Git Bash 或者 WSL 的 shell，语法完全按 POSIX 来。路径必须用正斜杠，D:/video/day31/foo.md 是合法的，D:\video\day31\foo.md 在双引号里会被当成转义序列。
• 想保留反斜杠又不出错，就套单引号 'D:\video\day31\foo.md'，单引号里不做转义。
• Read、Edit、Write 这些非 Bash 工具能识别 Windows 路径，但混合到 shell 命令里就出问题。稳妥做法是所有路径都写正斜杠。
• PowerShell 环境下变量前缀是 $，$env:USERPROFILE 才是家目录，不要写 %USERPROFILE%。

注意

你在 Prompt 里贴带反斜杠的路径，Claude Code 一般能理解，但一旦这个路径被塞进它生成的 bash 命令里，就极可能拼错。看到路径相关的报错第一反应就是换成正斜杠。

Grep 和 ripgrep 的关系

Grep 工具是 Claude Code 的封装，底层跑的是 ripgrep 二进制。ripgrep 支持完整正则、自动跳过 .gitignore 里排除的目录、支持按文件类型过滤（--type py）、支持多行匹配、支持只输出文件名或者只输出匹配数量。你 Prompt 里让它 grep 什么它就搜什么，速度和准确度基本可以放心。

如果你想让搜索限定在某种文件里，直接说文件类型就行：

在所有 ts 文件里搜 processOrder 的所有调用点

Claude Code 会自动加 --type ts，你不用记参数。文件类型识别覆盖了绝大多数主流语言，冷门的比如 zig、nim 也支持。想搜跨行的正则也可以直接说：

在 src 下搜所有 struct 定义体里包含 UserId 字段的类型，跨行也算

它会自动开启 ripgrep 的多行模式。这类进阶用法不用你去背命令，把需求说清楚，工具会自己选参数。