Read 是 Claude Code 的"眼睛"——它通过读取文件内容来理解你的代码库。 不同于 cat 命令的暴力输出，Read 支持 分段读取，可以精准读取大文件的某一部分， 还能解析图片、PDF 和 Jupyter Notebook。

参数一览

使用示例

# 基础用法: 读取整个文件
> 读一下 src/index.ts
# Claude 调用 Read(file_path="/abs/path/src/index.ts")
# 返回 cat -n 格式，带行号

# 大文件分段读取: 只读中间部分
> 读 src/utils.ts 的第 200 到 250 行
# Claude 调用 Read(file_path="...", offset=199, limit=51)

# 读取图片 (多模态能力)
> 看看 docs/screenshot.png 里面是什么
# Claude 会视觉解析图片内容并描述

# 读取 PDF (大 PDF 必须指定页码)
> 读一下 paper.pdf 的前 5 页
# Claude 调用 Read(file_path="...", pages="1-5")

# 读取 Jupyter Notebook
> 分析 analysis.ipynb 的内容
# 返回所有 cell 及其输出

Edit 是 Claude Code 最精密的工具——它执行精确字符串替换。 不是重写整个文件，而是像外科手术一样，只替换需要改变的部分。 这让代码审查变得容易：你能清楚看到 Claude 到底改了什么。

参数一览

工作机制

# Edit 的核心逻辑: 精确字符串替换
# 1. Claude 先 Read 文件，获取当前内容
# 2. 在内容中找到 old_string 的精确匹配
# 3. 替换为 new_string
# 4. 写回文件

# 示例: 修改函数名
Edit(
  file_path: "/project/src/utils.ts",
  old_string: "function getCwd()",
  new_string: "function getCurrentWorkingDirectory()"
)

# 示例: 批量替换变量名
Edit(
  file_path: "/project/src/app.ts",
  old_string: "userName",
  new_string: "currentUser",
  replace_all: true
)

Write 是最直接的工具——给一个路径和内容，整个文件被覆盖。 它是创建新文件的首选，但对已有文件来说，通常是 Edit 用不了时的备选方案。

参数一览

Edit vs Write 决策

# ✅ 用 Write 的场景:
# 1. 创建全新文件
> 创建一个 src/helpers/format.ts

# 2. 文件需要完全重写 (改动超过 50%)
> 把这个文件从 JavaScript 重写为 TypeScript

# 3. 生成配置文件
> 生成一个 .eslintrc.json 配置文件


# ❌ 不用 Write 的场景:
# 1. 只改几行 → 用 Edit
> 把第 42 行的 bug 修掉
# Claude 应该用 Edit，不是 Write 整个文件

# 2. 重命名变量 → 用 Edit + replace_all
> 把所有 userName 改成 currentUser

# 3. 添加一个导入语句 → 用 Edit
> 在文件顶部加上 import dayjs

Bash 是 Claude Code 的"双手"——它能执行任何 shell 命令。 从 git status 到 npm test， 从 curl 到 python script.py， 只要终端能跑的，Bash 工具都能执行。

参数一览

常见用法

# 基础: 查看目录结构
> 列出项目的目录结构
# Claude 执行: ls -la 或 find . -type f

# 运行测试
> 跑一下测试看看有没有通过
# Claude 执行: npm test 或 pytest

# 搜索代码
> 在项目里搜索所有用到 getUserId 的地方
# Claude 执行: grep -rn "getUserId" .

# Git 操作
> 查看最近 5 条提交记录
# Claude 执行: git log --oneline -5

# 链式命令 (用 && 连接顺序依赖)
# Claude 执行: npm install && npm run build

# 后台执行 (长时间运行的任务)
# Claude 执行: npm run dev (run_in_background: true)
# 你可以继续工作，完成后 Claude 会通知你

工作目录与状态

# 工作目录在命令之间持久化
> 进入 src 目录
# Claude 执行: cd src
# 之后的 Bash 命令都在 src/ 下执行

# 但 shell 状态不持久化 (环境变量、别名等)
# 每次 Bash 调用都是新的 shell 环境
# 如果需要设置环境变量，要在同一条命令中使用:
Bash("export NODE_ENV=test && npm test")
# ✅ 正确: 同一条命令

Bash("export NODE_ENV=test")
Bash("npm test")
# ❌ 错误: NODE_ENV 在第二条中不存在

掌握工具不只是知道每个工具能做什么——更重要的是知道 什么时候用哪个。 下面的决策树帮你建立直觉。

四大工具对比总表

每个工具配一个练习——观察 Claude 如何选择工具， 思考为什么它选择了这个而不是那个。

Lab 1 — Read 的分段读取

选一个大文件（100+ 行），测试 offset / limit 参数。

# 找一个大文件
> 项目里最长的源码文件是哪个？有多少行？
# Claude 会用 Bash: find + wc -l 来查找

# 分段读取
> 只读那个文件的第 50 到 80 行
# 观察: Claude 使用 Read 的 offset 和 limit 参数

# 对比: 读取整个文件 vs 分段读取的 token 消耗
> /usage

Lab 2 — Edit 的精确替换

创建一个测试文件，练习 Edit 的精确替换和 replace_all。

# 先创建一个测试文件
> 创建 test-edit.js，内容包含三个函数: getUserName、getUserAge、getUserEmail

# 精确替换一个函数名
> 把 getUserName 改成 fetchUserName
# 观察: Claude 用 Edit，只改了一个函数名

# 批量替换
> 把所有 getUser 开头的函数都改成 fetchUser 开头
# 观察: Claude 可能用多次 Edit 或 Edit + replace_all

# 故意测试唯一性约束
> 把所有 return 改成 return /* modified */
# 观察: 如果有多个 return，Claude 如何处理

Lab 3 — Write vs Edit 的边界

让 Claude 做一个大改动，观察它选择 Write 还是 Edit。

# 小改动: 应该用 Edit
> 在 test-edit.js 的顶部加一行注释 "// Created for learning"
# 预期: Claude 用 Edit

# 大改动: 可能用 Write
> 把 test-edit.js 从 JavaScript 完全重写为 TypeScript，加上类型注解
# 预期: 如果改动超过 50%，Claude 可能用 Write

# 新建文件: 一定用 Write
> 创建一个 test-edit.test.ts 测试文件
# 预期: Claude 用 Write (新文件)

Lab 4 — Bash 的进阶用法

测试 Bash 工具的超时控制和后台执行。

# 基础: 查看 Git 状态
> 查看 git 状态和最近的提交
# Claude 可能并行调用 git status 和 git log

# 链式命令
> 安装依赖然后运行测试
# Claude 执行: npm install && npm test

# 搜索代码 (grep)
> 在项目里搜索所有 TODO 注释
# Claude 执行: grep -rn "TODO" . --include="*.ts"

# 清理测试文件
> 删除我们刚创建的 test-edit.js 和 test-edit.test.ts
# 观察: Claude 会使用 Bash rm，并且要求你确认

1. Read 工具的 offset 和 limit 参数分别控制什么？为什么分段读取比读取整个文件更好？
2. Edit 工具要求 old_string 必须唯一——如果不唯一，有哪两种解决方案？
3. 在什么场景下应该用 Write 而不是 Edit？列举至少三种情况。
4. Bash 工具的 run_in_background 参数适用于什么场景？它和 timeout 参数的关系是什么？
5. 说出"专用工具优先于 Bash"这条原则的三个具体例子（哪些操作应该用专用工具而不是 Bash）。