Claude-Code 完全指南

从零基础到高效开发者

第一章：快速入门

1.1 什么是 Claude Code

Claude Code 是一个在终端中运行的 AI 编程助手，能读取、搜索、编辑你的代码，运行终端命令，管理 Git 提交。它像一个坐在你旁边的程序员搭档。

1.2 启动与交互

bash 复制代码

cd /path/to/your/project
1、claude

启动后直接对话：

复制代码

你: 这个项目有哪些文件？
你: 帮我看看 UserService.java 里做了什么
你: 给这个文件添加一个根据邮箱查询用户的方法

YOLO模式：

复制代码

claude --dangerously-skip-permissions

-c：显示上次会话

-r：显示历史会话

复制代码

claude --dangerously-skip-permissions -c

1.3 工具权限

Claude 执行操作时会征求同意：

自动允许：读取文件、搜索代码
需要确认：编辑文件、运行命令
需要谨慎：git push、删除文件

不确定时选拒绝并询问 Claude 要做什么。

第二章：常用命令

2.1 Slash 命令

命令	用途
`/help`	查看所有可用命令
`/clear`	清空对话历史
`/fast`	快速模式
`/compact`	压缩上下文，节省 token
`/doctor`	诊断环境
`/cost`	查看花费
`/model`	查看/切换模型
`/plan`	规划模式（先设计再实施）
`/review`	Code Review
`/commit`	辅助提交
`/pr`	创建 PR
`/init`	生成 CLAUDE.md
`/ask`	纯问答
`/edit`	编辑模式
`/diff`	查看差异
`/memory`	管理记忆
`/hooks`	管理 Hooks
`/tools`	列出工具

完整列表见附录。

2.2 工具调用速查

你不需要手动调用工具，自然语言描述即可。了解工具有助于写出精准 Prompt。

你说什么	Claude 用什么
"查看 xxx 文件"	`Read`
"搜索包含 xxx 的代码"	`Grep`
"找所有 .java 文件"	`Glob`
"运行 xxx 命令"	`Bash`
"修改 xxx 文件"	`Edit`
"创建 xxx 文件"	`Write`
"探索代码库"	`Agent(Explore)`
"设计方案"	`Agent(Plan)`

2.3 快捷键

快捷键	作用
`Ctrl+C`	中断当前操作
`Tab`	路径和命令补全
`↑/↓`	浏览历史输入
`! 命令`	直接在 shell 中运行，不经过 Claude

第三章：实战场景

3.1 读取和理解代码

了解一个文件：

复制代码

你: 读一下 src/main/java/com/example/service/UserService.java，告诉我它提供了哪些功能

Claude: [读取文件并总结]
这个文件提供了以下功能：
1. 根据 ID 查询用户
2. 根据邮箱查询用户
3. 创建新用户（含密码加密）
4. 更新用户信息

理解一个方法：

复制代码

你: UserService.java 里的 createUser 方法是怎么实现的？参数和返回值是什么？

Claude: createUser 接收 CreateUserRequest，返回 User。
实现逻辑：
1. 校验邮箱是否已存在
2. 密码 BCrypt 加密
3. 保存到数据库
4. 返回用户对象

了解项目结构：

复制代码

你: 帮我看看这个项目的目录结构，每个目录做什么的

Claude:
├── controller/  # HTTP 接口层
├── service/     # 业务逻辑层
├── repository/  # 数据库访问层
├── entity/      # 数据库实体
└── dto/         # 数据传输对象

3.2 修改现有代码

添加方法：

复制代码

你: 在 UserService.java 中添加一个方法：根据手机号查询用户。
- 方法名 getUserByPhone
- 参数 String phone
- 手机号为空抛异常
- 用户不存在返回 null

Claude: [Read → 找到合适位置 → Edit 添加]

修改已有方法：

复制代码

你: 修改 UserService.java 的 createUser 方法，添加年龄校验：年龄必须在 18-120 之间

Claude: [读取方法 → 添加校验逻辑 → Edit]

重命名方法（含所有调用处）：

复制代码

你: 把 UserService.java 里的 findUserById 改名为 getUserById，同时把所有调用它的地方也改掉

Claude: [Grep 查找所有调用 → 逐个 Edit 修改]

3.3 创建新文件

创建 Service 类：

复制代码

你: 创建一个新的 OrderService.java，放在 src/main/java/com/example/service/
需要包含以下方法：createOrder、getOrderById、listOrdersByUser
参考 UserService.java 的代码风格

Claude: [Read UserService.java 参考风格 → Write 创建新文件]

3.4 搜索和定位问题

搜索关键字：

复制代码

你: 搜索所有包含 "password" 的 Java 文件

Claude: [Grep pattern:"password" type:"java"]
找到以下文件：
1. UserService.java:45
2. UserController.java:23
3. SecurityConfig.java:12

按文件名查找：

复制代码

你: 找所有 Controller 文件

Claude: [Glob "**/*Controller.java"]

3.5 调试和修复 Bug

完整流程：

复制代码

你: 报错了，"NullPointerException at UserService.java:123"

Claude: [Read UserService.java:100-130]
123 行在调用 user.getName()，但 user 可能为 null。

你: 帮我修复

Claude: [Edit 添加 null 检查]

你: 帮我运行测试验证

Claude: [Bash: mvn test] 测试通过！

复杂 Bug 排查：

复制代码

你: 接口返回 500 错误，帮我排查

Claude:
1. 查找对应的 Controller 方法
2. 查看 Service 层逻辑
3. 检查异常堆栈
4. 分析可能的问题点

[Grep 找到 Controller → Read 阅读代码 → 定位问题]
问题：订单 ID 为 null 时没有做校验，直接传给了数据库查询。

第四章：进阶玩法

4.1 批量重构

复制代码

你: 所有 Java 文件中的 System.out.println 替换为 log.info，使用 SLF4J 占位符格式。
先列出需要修改的文件，让我确认后再改

Claude:
1. Grep 找到所有 System.out.println
2. 列出文件清单
你: 确认，开始修改
3. 逐个 Edit 修改
4. 汇总结果

4.2 Agent 多任务协作

并行探索：

复制代码

你: 同时做以下几件事：
1. 研究项目的数据库连接方式
2. 找出所有 API 端点
3. 分析认证机制

Claude: [启动 3 个 Agent 并行执行，完成后汇总]

大项目探索：

复制代码

你: 我刚加入这个项目，请全面介绍一下

Claude: [Agent(Explore): "项目结构、核心模块、技术栈、代码风格"]

4.3 后台任务

复制代码

你: 帮我编译项目，在后台跑就行

Claude: [Bash run_in_background=true: "mvn clean compile"]

[你继续做其他事...]

[编译完成，Claude 通知你]
编译成功！耗时：3 分 42 秒

4.4 定时任务

复制代码

你: 每 10 分钟运行一次构建，如果失败通知我

Claude: [CronCreate: "*/10 * * * *" 执行 mvn compile]

你: 30 分钟后提醒我检查部署状态

Claude: [CronCreate: 一次性的定时提醒]

4.5 工作树隔离

复制代码

你: 我想试一个新的重构方案，但不想影响当前代码

Claude: [EnterWorktree] 创建了一个隔离的工作树，随意修改。
完成后选择合并或丢弃。

4.6 记忆系统

Claude 自动记住：技术栈、代码风格、项目结构、历史决策。

手动记录：

复制代码

你: 请记住，这个项目使用 Hutool 工具库，不要手写工具方法

Claude: [保存记忆] 以后我会优先使用 Hutool。

第五章：项目工作流

5.1 从零开始一个功能

复制代码

你: 我需要添加一个功能：把用户列表导出为 Excel 文件

Claude: 我来规划：1. 添加 POI 依赖 2. 创建 ExcelUtil.java 3. UserController 添加接口 4. UserService 添加业务逻辑 5. 编写测试

你: 先添加 POI 依赖到 pom.xml
Claude: [Read pom.xml → Edit]
你: 创建 ExcelUtil.java，参考现有风格
Claude: [Write]
你: 在 UserController 添加 GET /users/export 接口
Claude: [Read → Edit]
你: 运行测试
Claude: [Bash: mvn test]

5.2 代码审查

复制代码

你: 帮我审查当前未提交的改动

Claude: [git diff → 逐文件分析 → 检查安全性/空指针/性能/规范 → 输出报告]

审查报告格式：

复制代码

代码审查报告
文件：UserService.java
- [OK] 参数校验完整
- [WARN] 第 45 行：可能 N+1 查询
- [WARN] 第 78 行：catch 了 Exception 但没有记录日志
总结：2 个 Warning，建议修复后合并

5.3 Git 提交和 PR

提交：

复制代码

你: 帮我提交代码，message 是 "feat: 添加用户导出功能"

Claude:
1. [git status] 查看改动
2. [git diff] 确认内容
3. [git add 文件列表]
4. [git commit]
5. 验证成功

创建 PR：

复制代码

你: 帮我创建一个 PR，标题 "feat: 用户导出 Excel"，描述写清楚功能

Claude:
1. [git push -u origin branch]
2. [gh pr create]
3. PR URL: https://github.com/...

5.4 Plan 模式做架构决策

复制代码

你: /plan

Claude 进入规划模式：
1. 充分了解代码库
2. 探索相关模块
3. 设计多种方案
4. 对比优劣
5. 输出推荐方案
6. 等你确认后实施

示例：

复制代码

你: 需要给项目添加缓存，帮我规划方案

Claude (Plan):
方案 A: Redis 缓存 -- 适合多实例部署
方案 B: Caffeine 本地缓存 -- 适合单实例
方案 C: Spring Cache 抽象层 -- 可切换底层实现

推荐：A + C 结合，Spring Cache 抽象层 + Redis 实现

第六章：Prompt 技巧

6.1 Prompt 模板

万能公式

复制代码

[动作] + [对象] + [约束条件] + [期望输出格式]

示例：

复制代码

读取 UserService.java          ← 动作 + 对象
找出所有可能空指针的地方         ← 约束条件
用表格列出：文件名、行号、原因    ← 输出格式

读代码模板

模板 A：单文件分析

复制代码

读取 {文件路径}，用表格列出：
| 方法名 | 参数 | 返回值 | 主要功能 | 潜在问题 |

模板 B：多文件对比

复制代码

对比 {文件A} 和 {文件B} 的 {方法名} 方法，
用表格列出差异：| 维度 | 文件A | 文件B |

模板 C：项目结构

复制代码

帮我了解这个项目的结构：
1. 列出 src/main/java 下所有包
2. 每个包的作用
3. 核心类有哪些
4. 技术栈是什么

改代码模板

模板 A：添加方法

复制代码

在 {文件路径} 中添加一个方法：
- 方法名：{方法名}
- 参数：{参数列表}
- 返回值：{返回类型}
- 功能：{详细描述}
- 异常处理：{如何处理异常}
- 参考：保持与文件中其他方法相同的代码风格

模板 B：修改方法

复制代码

修改 {文件路径} 中的 {方法名} 方法：
- 当前逻辑：{简述现有行为}
- 需要改成：{描述目标行为}
- 注意：{不能改坏的地方}

模板 C：批量修改

复制代码

找出所有 Java 文件中包含 {关键字} 的地方，
把 {旧写法} 改成 {新写法}
先列出所有需要修改的文件，让我确认后再改

查问题模板

模板 A：搜索

复制代码

在 {范围} 中搜索所有包含 {关键字} 的地方，
列出：文件路径、行号、上下文

模板 B：查找隐患

复制代码

检查 {文件/范围} 中是否存在以下问题：
1. 参数没有做 null 检查
2. 捕获了异常但没有记录日志
3. SQL 拼接使用了字符串 concatenation
4. 日志中可能输出了敏感信息

如果有，列出：文件、行号、问题描述、修复建议

写测试模板

复制代码

为 {文件路径} 中的 {方法名} 方法编写单元测试：
- 测试框架：{JUnit/Mockito}
- 覆盖场景：
  1. 正常流程
  2. 边界条件（空值、null、0、最大值）
  3. 异常情况
- 参考：测试风格参考 {已有测试文件}

做 Review 模板

复制代码

审查 {文件/PR} 的代码质量：
1. 安全性（SQL 注入、XSS、敏感信息泄露）
2. 健壮性（空指针、异常处理、边界条件）
3. 性能（N+1 查询、不必要循环）
4. 可读性（命名清晰、逻辑简洁）
5. 规范性（符合项目代码风格）

对每个问题给出：严重程度、位置、问题描述、修复建议

6.2 组合工具链

工作流 1：定位 → 阅读 → 修改 → 验证

适用场景：修复已知 Bug

复制代码

你: 报错 "NullPointerException at UserService.java:123"，帮我看看
Claude: [Read UserService.java:115-130]
你: 在第 123 行前添加 null 检查，如果 user 为 null 抛出自定义异常
Claude: [Edit 添加 null 检查]
你: 运行 mvn test -Dtest=UserServiceTest 验证
Claude: [Bash: mvn test]

工作流 2：搜索 → 分析 → 批量修改

适用场景：统一代码风格、批量重构

复制代码

你: 找出所有 Java 文件中包含 System.out.println 的地方
Claude: [Grep] 找到 15 处，分布在 5 个文件中
你: 把这些全部替换为 log.info，先改 UserService.java 让我看效果
Claude: [Edit 修改]
你: 确认，改剩下的
Claude: [逐个修改] → [Bash: mvn compile 验证]

工作流 3：探索 → 设计 → 实施

适用场景：从零开发新功能

复制代码

你: 先帮我了解项目现有的用户模块是怎么实现的
Claude: [Glob + Read 探索]
你: 参考现有风格，帮我规划"用户导出 Excel"需要改哪些文件
Claude: [输出方案：pom.xml、ExcelUtil.java、UserController.java、UserService.java]
你: 按方案逐个实现，每完成一个文件告诉我
Claude: [逐个 Write/Edit，每步确认]

工作流 4：审查 → 修复 → 提交

适用场景：Code Review + 自动修复

复制代码

你: 审查当前未提交的改动，找出所有问题
Claude: [git diff → 逐文件审查]
你: 高严重度的全部修复，中等的列出让我选
Claude: [Edit 修复高危 → 列出中危]
你: 修复完成，帮我提交，commit message 按改动分组写
Claude: [git status → git add → git commit]

6.3 常见错误对比

模糊 vs 精确指令

模糊指令（效果差）	精确指令（效果好）
"帮我改改这个文件"	"在 UserService.java 的 createUser 中添加邮箱格式校验"
"项目有哪些接口"	"找出所有 Controller 中 @GetMapping 的方法，用表格列出"
"修好这个 Bug"	"报错 'NullPointerException at UserService.java:123'，分析并修复"

核心原则：指令越具体，结果越准确。

一次做太多 vs 分步进行

错误：同时改日志、补注释、跑测试，中间出错很难定位。

正确：先列出清单 → 确认 → 修改 → 测试验证。

不给上下文 vs 给足上下文

差的："添加一个查询方法"

好的：

复制代码

"参考 getUserById(Long id) 的写法，添加 getUserByEmail(String email)：
- email 为空抛 IllegalArgumentException
- 用户不存在返回 Optional.empty()
- 使用 LambdaQueryWrapper 查询
- 日志风格与 getUserById 一致"

不验证 vs 步步验证

危险：改 10 个文件直接提交，事后发现某个改坏了。

安全：每改一个文件就运行测试，通过再改下一个，全部完成后再提交。

6.4 让 Claude 更自主

分阶段授权

复制代码

阶段 1（只读）: 先不要改代码，帮我看看 UserService.java 有哪些潜在问题
阶段 2（确认后改）: 找出需要加 @Valid 的方法，列清单让我确认
阶段 3（自主完成）: 参考 UserService.java 风格创建 OrderService.java，直接写

设定约束

复制代码

范围：只修改 UserService.java，不要动其他文件
风格：代码风格遵循 CLAUDE.md，方法不超 50 行
依赖：优先使用 Hutool，不要手写工具方法
行为：不要删除任何现有方法，只添加新方法

让 Claude 自检

复制代码

你: 写完自己审查一遍：
1. 有没有空指针风险
2. 有没有 SQL 注入风险
3. 有没有吞掉异常
4. 方法是否超过 50 行
5. 命名是否符合规范
有问题自己修好

利用 Checkpoints 安全回退

复制代码

你: 分三步重构，每步改完 commit 一次
Claude: [Edit → git commit] → [Edit → git commit] → ...
如果改坏了: [git reset --soft HEAD~1] 回退

6.5 CLAUDE.md 配置示例

在项目根目录创建 CLAUDE.md，Claude 每次自动遵守：

markdown 复制代码

# 项目规范
## 技术栈: Java 17 / Spring Boot 3.2 / MyBatis-Plus / Hutool 5.8
## 代码风格: 缩进 4 空格, @Data 注解 DTO, Slf4j 日志, Hutool 优先
## 安全: 参数 @Valid 校验, 密码 BCrypt, 日志禁敏感信息
## 每次修改: 先 Read 再 Edit, 改后 mvn test, 提交前 git diff

6.6 完整实战示例

需求：添加"用户批量导入"功能，上传 CSV 解析后批量创建用户。

复制代码

1. 探索: "帮我看看项目中有没有文件上传或批量操作的现有代码" → [Grep → Read]
2. 设计: "参考现有风格，规划批量导入功能" → [输出方案]
3. 实现: 逐个文件创建/修改 [Read → Write/Edit]，参考已有代码风格
4. 自检: "审查刚才修改的所有文件" → [发现问题 → Edit 修复]
5. 验证: [mvn clean compile → mvn test]
6. 提交: [git status → git diff → git add → git commit]

工作流总结：

复制代码

探索 → 设计 → 分步实现 → 自检 → 验证 → 提交
 Grep   方案     Edit      Read    Bash    Git
 Read            Write

你下了 6 条指令，Claude 完成了全流程。

附录：命令参考速查表

A. Slash 命令

常用命令见第二章，以下为补充：

命令	作用
`/shell`	切换 shell 模式
`/config`	查看配置
`/commands`	列出所有命令
`/context`	查看上下文
`/history`	命令历史
`/stats`	统计信息
`/skills`	列出技能
`/mcp`	管理 MCP
`/changelog`	版本更新日志
`/feedback`	提交反馈

B. 工具速查

工具	能力	自动允许
Read / Glob / Grep	读文件 / 匹配文件名 / 搜索内容	是
Edit / Write	编辑文件 / 创建覆盖文件	否
Bash	运行终端命令	否
WebFetch / WebSearch	获取网页 / 搜索网页	否
Agent	启动子任务	视情况
CronCreate / NotebookEdit	定时任务 / 编辑 Notebook	否
EnterWorktree / ExitWorktree	git 工作树隔离	否

C. Glob 模式速查

模式	匹配
`*.java`	当前目录所有 .java
`*/.java`	递归所有子目录 .java
`src/*/.java`	src 下所有 .java
`Service.java`	文件名含 Service 的 Java
`/test//*Test.java`	test 目录下所有测试类

D. Grep 常用参数

参数	作用	示例
`pattern`	正则表达式	`"public.*createUser"`
`path`	搜索目录	`path: "src/main/java"`
`glob` / `type`	文件过滤	`glob: "*.java"`
`context`	上下文行数	`context: 3`
`-i`	忽略大小写	`-i: true`
`head_limit`	限制结果数	`head_limit: 20`

E. Git 命令速查

你说什么	Claude 执行
"看看状态/改动"	`git status` / `git diff`
"提交代码"	`git add . && git commit`
"推送/拉取"	`git push` / `git pull`
"切换/创建分支"	`git checkout xxx` / `-b xxx`
"撤销改动"	`git checkout -- xxx`
"暂存/恢复"	`git stash` / `pop`
"合并分支"	`git merge xxx`
"回退提交（保留改动）"	`git reset --soft HEAD~1`

F. 编辑注意事项

必须先 Read 再 Edit
old_string 必须完全且唯一匹配
大文件分段 Read，每次约 100 行

G. 配置文件位置

文件	作用
`CLAUDE.md`（项目根目录）	项目级指令和规范
`~/.claude/settings.json`	全局配置
`~/.claude/projects/*/memory/`	项目记忆

H. 性能优化

简单任务 /fast，对话长了 /compact
大任务 Agent 分发，耗时操作后台运行
分阶段 commit 避免大改动

把 Claude Code 当作一个聪明但需要明确指令的实习生，你说得越清楚，它做得越好。

多任务执行

让 Claude 同时处理多个任务，大幅提升效率。

方式一：自然语言多任务（小任务组合）

直接在一条消息里描述多个任务，Claude 会自动并行执行：

复制代码

你：帮我做三件事：
1. 读一下 UserService.java，总结有哪些方法
2. 搜索所有包含 password 的文件
3. 看看当前 git 状态

Claude: [并行执行 Read + Grep + Bash git status，完成后汇总结果]

适用场景：读文件、搜索、运行命令等小任务组合。

方式二：Agent 并行（大任务）

启动多个子 Agent 同时研究不同方向，不阻塞主对话：

复制代码

你：同时做以下几件事，互不干扰：
- 研究项目的数据库连接方式
- 找出所有 API 端点
- 分析认证机制

Claude: [启动 3 个 Agent(Explore) 并行执行，完成后汇总]

适用场景：全面探索代码库、复杂分析、互相独立的大任务。

方式三：后台任务（耗时操作）

耗时操作放后台，你做别的事，完成后通知你：

复制代码

你：帮我编译项目，这个比较慢，在后台跑就行

Claude: [Bash run_in_background=true: "mvn clean compile"]
[你在做其他事情...]
[编译完成，Claude 通知你] 编译成功！耗时：3 分 42 秒

方式对比

方式	适用场景	优势
自然语言多任务	小任务组合	简单直接
Agent 并行	大任务（代码探索、复杂分析）	不阻塞主对话，结果独立
后台任务	耗时操作（编译、构建、测试）	不阻塞，完成后通知