系列文章

本篇是 Claude Code 系列的第 2 篇。系列将从安装入门到高级实战，由浅入深地拆解这个终端原生 Coding Agent 的每一个能力。

🚀 入门篇

1. Claude Code 是什么？从安装到第一次对话
2. 日常开发工作流：用 Claude Code 重塑你的编码习惯（本文）

🔧 核心篇

3. 内置命令全解：从 /compact 到 /doctor 的实战指南
4. CLAUDE.md：项目上下文工程的艺术

⚡ 进阶篇

5. 多文件重构与复杂任务实战
6. Hooks、MCP 与能力扩展

🏗️ 高级篇

7. Headless 模式与 CI/CD 集成
8. 多 Agent 协作：从 Claude Code 到 Codex

🧭 全景总结

9. Claude Code 系列全景总结：从入门到多 Agent 协作的知识地图

💰 成本优化

10. Claude Code 成本优化与 Token 管理实战：让每一分钱都花在刀刃上

一、开篇：从”用工具”到”和工具一起干活”

上一篇我们完成了 Claude Code 的安装和第一次对话。你已经知道它能读文件、写代码、跑测试。但这些只是”能力”，不是”工作流”。

能力 ≠ 生产力。

就像给你一把电钻，你知道它能打孔。但只有当你掌握了”先量尺寸、再定位、再打孔、最后检查”的工作流程，电钻才真正变成生产力工具。

Claude Code 也一样。很多开发者装完之后的使用模式是：遇到问题 → 打开 Claude Code → 问一个问题 → 关掉。这就像用 Google 搜索一样——你只用到了它 10% 的能力。

这篇文章要做的事情是：把 Claude Code 从一个”偶尔用用的问答工具”变成你每天编码节奏的一部分。

我们用 5 个真实场景来拆解：

二、场景一：Bug 修复工作流——从”猜谜”到”诊断”

传统方式的痛点

修 Bug 的典型流程：

1. 看到报错日志
2. 打开出错的文件
3. 猜测原因
4. 修改代码
5. 跑测试
6. 测试失败，回到步骤 2

这个循环可能重复 5-10 次，每次都要重新理解上下文。最大的时间浪费不是写代码，而是在文件之间跳转、重新建立心理模型。

Claude Code 的方式

1
2

cd ~/projects/my-spring-boot-app
claude

启动后，直接描述问题：

1
2

> 用户登录接口报 500 错误，日志显示 NullPointerException at UserService.java:42。
> 帮我定位原因并修复。

Claude Code 会执行以下 Agent Loop：

1
2
3
4
5
6
7

1. 读取 UserService.java 第 42 行附近代码
2. 追踪调用链：UserService → UserRepository → 数据库查询
3. 发现 userRepository.findByUsername() 在用户不存在时返回 null
4. 没有 null 检查，直接调用了 .getPassword()
5. 添加 null 检查 + 抛出有意义的业务异常
6. 跑 UserServiceTest 验证修复
7. 补充一个测试用例覆盖用户不存在的场景

关键区别：你不需要告诉它”去读哪个文件”或”检查 null”。它会自己追踪调用链、分析上下文、找到根因。这就是 Agent Loop 的价值——它不是一个”你问一步它答一步”的问答机，而是一个自主迭代直到问题解决的代理。

提升效率的技巧

技巧 1：直接粘贴错误日志

1
2

> 跑 mvn test 失败了，错误日志如下：
> [粘贴完整的 stack trace]

Claude Code 会从 stack trace 中提取关键信息（类名、行号、异常类型），自动定位到相关代码。

技巧 2：用 @ 引用特定文件

1
2

> @src/main/java/com/example/service/OrderService.java 
> 这个文件的 calculateTotal 方法有并发问题，帮我修复。

@ 前缀会触发文件自动补全，确保 Claude Code 精确定位到目标文件。

技巧 3：让它先分析再修复

1
2

> 先分析一下这个 NullPointerException 的所有可能原因，
> 列出你的诊断思路，然后再修复。

这个”先诊断后治疗”的模式，特别适合复杂的、原因不明显的 Bug。Claude Code 会列出所有可能的原因，你确认方向后再动手。

三、场景二：新功能开发——从”手工作坊”到”流水线”

传统方式的痛点

写一个新功能（比如”给订单模块加一个分页查询接口”），你需要：

1. 创建 Controller 方法
2. 创建 Service 方法
3. 创建 Mapper 方法 + XML
4. 写 DTO/VO
5. 写单元测试
6. 写集成测试
7. 更新 API 文档

7 个文件，每个文件都要遵循项目的现有模式。真正的痛苦不是写代码，而是保持一致性——你的新代码必须和现有代码风格一致、命名规范一致、异常处理一致。

Claude Code 的方式

1
2
3
4
5
6
7

> 给 OrderController 加一个分页查询接口。
> 要求：
> 1. 参考 UserController 的 findByPage 方法的模式
> 2. 支持按订单状态和创建时间范围筛选
> 3. 使用 PageHelper 分页
> 4. 返回统一的 Result<PageInfo<OrderVO>> 格式
> 5. 写对应的单元测试

Claude Code 会：

1. 先读 UserController.java，理解 findByPage 的代码模式
2. 再读 OrderController.java、OrderService.java、OrderMapper.java，理解现有结构
3. 然后读 项目的 Result、PageInfo 等公共类，确保返回类型正确
4. 生成代码：Controller → Service → ServiceImpl → Mapper → XML → VO → 测试
5. 展示 diff，等待你确认
6. 跑测试，如果有失败自动修复

这就是”上下文工程”的威力。Claude Code 不是在真空中写代码，而是在理解了你的整个项目之后，生成符合项目风格的代码。

为什么它能做到一致性？

因为它在生成代码之前，会读取：

• 相邻的同类文件（从 Controller 学 Controller 的写法）
• 项目的公共组件（Result、PageInfo、异常处理）
• 配置文件（MyBatis-Plus 的配置、分页插件的配置）
• 测试文件（理解测试的写法和断言风格）

这就像一个新入职的高级工程师——他不会上来就写代码，而是先看项目里现有的代码是怎么写的，然后按照同样的模式来写新功能。

渐进式开发：拆分大任务

如果功能比较复杂（比如”实现完整的订单支付流程”），不要一次性扔给 Claude Code。拆分成小任务，每完成一个就验证一次：

1
2
3
4
5
6
7
8
9
10
11

# 任务 1：创建支付订单接口
> 先创建 PaymentController 和 createPayment 方法，只做接口定义和参数校验。

# 任务 2：实现支付逻辑
> 现在实现 PaymentService.processPayment，集成支付宝 SDK。

# 任务 3：处理支付回调
> 加一个 /payment/notify 回调接口，处理支付宝的异步通知。

# 任务 4：写测试
> 给上面三个接口写完整的单元测试和集成测试。

为什么要拆分？

1. 上下文窗口有限——Claude Code 的上下文窗口虽然有 200K token，但复杂任务的中间状态会快速消耗它。拆分任务可以让每个子任务都在”干净”的上下文中执行。
2. 验证频率更高——每完成一步就跑测试，发现问题立刻修，而不是写完 10 个文件才发现根本方向错了。
3. 你可以插入决策点——在任务之间，你可以审查代码、调整方向、补充需求。

四、场景三：代码审查——从”人肉 diff”到”AI 助审”

传统方式的痛点

代码审查是必要的，但也是痛苦的。你需要：

• 逐行看 diff
• 检查逻辑正确性
• 检查安全性
• 检查性能问题
• 写评审意见

一个中等规模的 PR（200-500 行改动），认真审查至少需要 30 分钟。

Claude Code 的方式

快速审查（Print 模式）：

1
2
3
4
5
6
7
8

# 审查当前分支相对于 main 的所有改动
git diff main...feature-branch | claude -p "仔细审查这个 diff，检查：
1. 逻辑错误和边界条件
2. 安全漏洞（SQL 注入、XSS、权限绕过）
3. 性能问题（N+1 查询、大对象拷贝）
4. 代码风格一致性
5. 缺失的测试用例
请用中文给出具体的修改建议。" --max-turns 3

深度审查（交互模式）：

1
2
3
4
5
6
7

claude
> 审查当前分支相对于 main 的所有改动。
> 重点关注：
> 1. 新增的 API 接口是否有权限控制
> 2. 数据库操作是否有事务保护
> 3. 是否有遗漏的异常处理
> 给出具体的行号和修改建议。

审查自己的代码

在提交之前，先让 Claude Code 审查一遍：

1
2

> 我刚改完 UserService 的密码重置逻辑。帮我 review 一下，
> 重点关注安全性，看看有没有我遗漏的问题。

这是一个非常好的习惯。Claude Code 会以”第二双眼睛”的视角审视你的代码，经常能发现你自己忽略的问题：

• 密码重置 token 是否有过期机制？
• 是否有重放攻击的风险？
• 错误信息是否泄露了敏感信息（比如”用户不存在”vs”密码错误”）？

五、场景四：重构——从”牵一发动全身”到”安全手术”

传统方式的痛点

重构是开发中最危险的操作之一。把 UserService 的认证逻辑抽到独立的 AuthService，你需要：

1. 创建 AuthService 类
2. 从 UserService 中提取认证相关的方法
3. 修改 UserService 中对这些方法的调用
4. 修改 UserController 中直接调用认证逻辑的地方
5. 更新依赖注入
6. 更新测试
7. 确保没有遗漏的引用

遗漏任何一个调用点，线上就会报错。

Claude Code 的方式

1
2
3
4
5
6
7

> 把 UserService 中的认证相关逻辑（login、register、resetPassword、
> validateToken）抽到独立的 AuthService。
> 要求：
> 1. 保持所有现有功能不变
> 2. 更新所有调用方（Controller、其他 Service）
> 3. 更新对应的测试
> 4. 完成后跑全部测试确认没有破坏

Claude Code 的 Agent Loop 在这里的优势是它能追踪整个调用链。它会：

1. 读取 UserService，识别哪些方法属于”认证”逻辑
2. 用 Grep 工具搜索整个项目中对这些方法的引用
3. 创建 AuthService，移动方法
4. 逐个修改所有调用方
5. 更新测试文件
6. 跑 mvn test 验证
7. 如果有测试失败，分析原因并修复

关键：它不会遗漏调用点。因为它不是靠”记忆”来找引用，而是用 Grep 工具实际搜索整个代码库。

重构的安全网

在开始重构之前，先确保测试是绿色的：

1
2

> 先跑一下全部测试，确认当前状态是绿色的。
> 然后开始重构。重构完成后再次跑测试，确保没有回归。

如果项目没有测试怎么办？先让 Claude Code 补测试：

1
2

> UserService 目前没有单元测试。先帮我写一套完整的测试，
> 覆盖所有公开方法。测试写完后跑一下确认都是绿色的。

然后再重构。没有测试的重构就是在裸奔。

六、场景五：上下文管理——长对话的秘密武器

为什么需要上下文管理？

Claude Code 的对话是有状态的。你在对话中读过的文件、写过的代码、跑过的命令，都会累积在上下文中。这带来两个问题：

1. Token 消耗——上下文越大，每次交互消耗的 token 越多，费用越高
2. 上下文污染——旧的对话内容可能干扰新的任务

/compact：智能压缩

1
2
3

> /compact
Compacted conversation (180K → 22K tokens)
Saved approximately $1.58

/compact 会保留关键信息（CLAUDE.md、最近的代码修改、当前任务状态），丢弃中间过程。就像一个聪明的秘书帮你整理会议纪要——保留决策和结论，丢弃讨论过程。

什么时候用 /compact？

• 完成一个子任务，准备开始下一个
• 对话超过 30 分钟
• /context 显示上下文使用率超过 70%

**带焦点的 /compact**：

1

> /compact focus on the authentication refactoring we just did

这会告诉 Claude Code 在压缩时重点保留认证重构相关的信息，丢弃其他不相关的内容。

/clear：彻底清空

1

> /clear

/clear 比 /compact 更激进——它完全清空对话历史，只保留 CLAUDE.md。适合：

• 切换到一个完全不同的任务
• 对话已经严重”跑偏”，想重新开始
• 上下文使用率超过 85%，压缩已经不够了

会话恢复：-c 和 -r

继续上一次会话：

1

claude -c

这会恢复当前目录下最近一次会话。适合：下班前关掉终端，第二天继续。

恢复特定会话：

1

claude -r <session-id>

适合：你同时在多个任务之间切换，每个任务有不同的会话。

查看会话历史：

1

claude sessions list

上下文健康的黄金法则

你可以用 /context 命令查看当前的上下文使用情况，它会显示一个彩色网格图。

七、模型选择策略：不是所有任务都需要最强大脑

为什么要选模型？

Claude Code 支持多个模型，它们的能力和价格差异很大：

实战策略

日常开发用 Sonnet：

1

claude --model sonnet

Sonnet 是大多数场景的最佳选择。它足够聪明来理解你的项目、写出高质量的代码，同时速度和成本都在可接受范围内。

复杂任务切 Opus：

1

> /model opus

当你遇到需要深度推理的任务（比如重构一个有 10 年历史的遗留系统），在会话中切换到 Opus。

简单任务用 Haiku：

1

claude --model haiku -p "把这个 JSON 文件格式化一下" --max-turns 1

格式化文件、简单查找、生成 boilerplate 这些任务，用 Haiku 就够了，省钱又快。

自动降级

1

claude --fallback-model haiku -p "分析这个错误日志"

当默认模型过载（Anthropic 的 API 偶尔会繁忙）时，自动降级到 Haiku，避免请求失败。

八、权限模式：速度与安全的平衡

三种权限模式

Claude Code 有三种权限模式，决定了它在执行操作前是否征求你的同意：

默认模式（Normal）：

• 读取文件：自动执行
• 编辑文件：展示 diff，等你确认
• 执行命令：需要确认
• Git 操作：需要确认

自动接受编辑（Accept Edits）：

• 读取文件：自动执行
• 编辑文件：自动执行
• 执行命令：需要确认
• Git 操作：需要确认

完全自动（Auto-Accept）：

• 所有操作自动执行，不征求同意

如何切换

在交互模式中，按 Shift+Tab 循环切换三种模式。

或者在启动时指定：

1
2

claude --permission-mode acceptEdits  # 自动接受编辑
claude --permission-mode auto         # 完全自动

实战建议

写新功能时：用 acceptEdits 模式。你已经明确了需求，让 Claude Code 直接写代码，不要每改一个文件都要确认。

修 Bug 时：用默认模式。你需要审查它的诊断思路和修复方案，确保方向正确。

跑测试/构建时：可以设置自动批准安全命令。在 .claude/settings.json 中配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "permissions": {
    "allow": [
      "Bash(mvn test *)",
      "Bash(mvn clean compile *)",
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

这样，mvn test 会自动执行，但 git commit 和 git push 还是需要你确认。

九、自定义命令：把重复劳动变成一键操作

什么是自定义命令？

如果你发现自己反复输入相同的指令（比如”跑测试、构建、部署”），可以把它们定义为自定义命令。

创建自定义命令

在项目根目录创建 .claude/commands/ 目录：

1

mkdir -p .claude/commands

测试命令 .claude/commands/test.md：

1
2
3
4
5
6

运行项目的完整测试流程：
1. 执行 `mvn clean test`
2. 如果有测试失败，分析失败原因
3. 尝试修复失败的测试
4. 重新跑测试确认全部通过
5. 最后给出测试结果摘要

部署命令 .claude/commands/deploy.md：

1
2
3
4
5
6
7

执行部署流程：
1. 先跑全部测试，确认绿色
2. 执行 `mvn clean package -DskipTests`
3. 检查构建是否成功
4. 如果 $ARGUMENTS 是 staging，部署到测试环境
5. 如果 $ARGUMENTS 是 production，部署到生产环境
6. 验证部署是否成功

Code Review 命令 .claude/commands/review.md：

1
2
3
4
5
6
7
8

审查当前分支相对于 main 的改动：
1. 执行 `git diff main...HEAD` 获取所有改动
2. 逐个文件审查，重点关注：
   - 逻辑错误和边界条件
   - 安全漏洞
   - 性能问题
   - 代码风格一致性
3. 给出具体的修改建议和优先级

使用自定义命令

1
2
3

> /test
> /deploy staging
> /review

$ARGUMENTS 会被替换为你输入的内容。比如 /deploy staging 中的 staging。

全局命令 vs 项目命令

• 项目命令（.claude/commands/）：和项目绑定，可以提交到 Git，团队共享
• 全局命令（~/.claude/commands/）：个人所有项目通用

十、一天的 Claude Code 工作流

把上面的场景串起来，一个典型的 Java 开发者的一天可能是这样的：

早上：开始编码

1
2
3
4
5
6

# 进入项目目录，启动 Claude Code
cd ~/projects/my-spring-boot-app
claude

# 恢复昨天的会话（如果需要）
# 或者直接开始新任务

1

> 早上好。先帮我看看有没有未提交的改动，然后我们开始今天的任务。

上午：开发新功能

1
2
3

> 今天的任务是给订单模块加一个批量导出功能。
> 先帮我分析一下现有的 OrderController 和 OrderService 的结构，
> 然后我们分步实现。

Claude Code 分析完后，你分步下达指令：

1
2

> 第一步：创建 ExportService，定义 exportOrders 方法的接口。
> 先不实现，只定义接口和参数。

审查接口设计，确认没问题后：

1
2

> 第二步：实现 exportOrders，使用 Apache POI 生成 Excel 文件。
> 参考项目中已有的 ExportUtil 的写法。

1

> 第三步：给 ExportService 写单元测试。

1

> 跑一下测试。

中午：快速修复

午餐前收到一个线上 Bug 报告：

1
2

> 线上报了一个 NPE，在 OrderService.java 的 calculateDiscount 方法。
> 帮我快速定位修复，然后跑一下相关测试。

下午：代码审查

同事提交了一个 PR，你用 Print 模式快速审查：

1
2

git fetch origin
git diff main...origin/feature-payment | claude -p "审查这个 PR 的改动，重点关注安全性和边界条件。" --max-turns 3

审查完毕，继续开发：

1
2

> 继续上午的任务。现在给批量导出加上分批处理逻辑，
> 避免一次性加载太多数据导致 OOM。

下午：重构

1
2

> 我发现 ExportService 和 ReportService 有很多重复的 Excel 生成代码。
> 帮我把公共逻辑抽到一个 ExcelGenerator 工具类中。

下班前：整理

1

> /compact

压缩上下文，为明天的会话做准备。或者直接用 /cost 看看今天的花费：

1
2
3
4
5

> /cost
Session cost: $3.42
  Input tokens: 245,000 ($2.45)
  Output tokens: 18,200 ($0.91)
  Cache read: 180,000 ($0.18)

十一、效率提升的本质：减少上下文切换

回顾这 5 个场景，Claude Code 提升效率的核心机制不是”帮你写代码”（虽然它确实能写），而是减少上下文切换的成本。

传统开发中，你在这些角色之间频繁切换：

• 读者：读代码、读文档、读报错日志
• 思考者：分析问题、设计方案
• 写手：写代码
• 测试者：跑测试、验证结果
• 审查者：review 代码、检查质量

每次切换，你的大脑都需要重新加载上下文。这就是为什么你一天写了 200 行代码却觉得精疲力尽——不是写代码累，是切换累。

Claude Code 的 Agent Loop 把”读 → 思考 → 写 → 测试 → 审查”这个循环自动化了。你只需要在关键决策点介入：

• 确认方向：”对，就是这个思路”
• 调整方案：”不要用 HashMap，用 ConcurrentHashMap”
• 审查结果：”这里有个边界条件没处理”

你从”执行者”变成了”指挥者”。

这不是偷懒，这是更高级的工作方式。就像将军不需要亲自扛枪一样——你的价值在于决策和方向，不在于一行一行地敲代码。

十二、新手常犯的 5 个错误

错误 1：一次给太多任务

1
2
3
4
5
6
7

# ❌ 错误
> 帮我实现完整的用户管理系统，包括注册、登录、权限管理、
> 角色管理、菜单管理、日志管理，用 Spring Security + JWT。

# ✅ 正确
> 先实现用户注册接口，只需要用户名、密码、邮箱。
> 用 BCrypt 加密密码，写单元测试。

原因：任务太大，Claude Code 的上下文会被中间过程占满，后面的代码质量会下降。

错误 2：不审查就提交

Claude Code 生成的代码通常是高质量的，但不是 100% 正确的。特别是：

• 并发场景（它可能用错锁的类型）
• 业务逻辑（它不理解你的业务规则）
• 安全敏感代码（认证、授权、加密）

永远要审查，至少要审查关键路径的代码。

错误 3：不用 CLAUDE.md

没有 CLAUDE.md，Claude Code 每次启动都要”重新认识”你的项目。它会：

• 用错分页方案（用了 Spring Data Pageable 而不是 PageHelper）
• 返回格式不对（没用 Result 包装）
• 命名风格不对（驼峰 vs 下划线）

花 10 分钟写一个 CLAUDE.md，能节省未来 10 小时的纠正时间。

错误 4：不在项目目录启动

1
2
3
4
5
6
7

# ❌ 错误：在 home 目录启动
cd ~
claude

# ✅ 正确：在项目目录启动
cd ~/projects/my-spring-boot-app
claude

Claude Code 会读取当前目录作为工作目录。在错误的目录启动，它会读到错误的文件。

错误 5：忽略 /compact

长对话不压缩，token 消耗会指数级增长。更严重的是，上下文过大会导致输出质量下降——模型的注意力被分散了。

完成一个子任务后，习惯性地 /compact 一下。

十三、和 AI Agent 系列的关联

如果你读过我们的 AI Agent 系列，你会发现 Claude Code 的工作流和 ReAct 模式是同构的：

Claude Code 本质上就是一个特化的 AI Agent——它的”行动空间”被限定在了软件开发领域（读写文件、执行命令、搜索代码），但底层的 Agent Loop 和通用 AI Agent 是一样的。

理解这一点，你就能用 AI Agent 的思维方式来优化你和 Claude Code 的协作：

• 任务分解：大任务拆成小步骤，每步都有明确的完成标准
• 反馈循环：让 Claude Code 在每一步都验证自己的输出
• 上下文管理：定期压缩/清空，保持 Agent 的”注意力”集中

总结

Claude Code 不是一个”问一下就完事”的工具。它是一个需要你学会”协作”的 Agent。

核心要点：

1. Bug 修复：直接粘贴错误日志，让 Agent 自主诊断+修复+验证
2. 新功能开发：参考现有代码模式，分步实现，每步验证
3. 代码审查：用 git diff | claude -p 快速审查，提交前自己先过一遍
4. 重构：让 Agent 追踪整个调用链，确保不遗漏任何引用点
5. 上下文管理：/compact 压缩、/clear 清空、-c 恢复会话

参考资料

• learn-claude-code：从零构建 Claude Code Agent Harness 的 20 章教程
• Anthropic - Claude Code Best Practices