跳转至

最佳实践

Claude Code 不只是一个"会写代码的聊天窗口"——它更像一个拥有完整工具链的编程搭档。但搭档再强，也需要你给出清晰的指令和合理的工作方式。这篇文章把官方推荐的使用技巧、常见工作流、成本控制和排错方法，整理成一份可以直接上手操作的指南。

本文你会学到：

  • 怎样写出让 Claude Code 高效执行的指令
  • 三种高频工作流的实战套路（代码审查、Bug 修复、功能开发）
  • Token 成本的构成与 10+ 种节省策略
  • 常见反模式与正确做法的对照清单
  • 验证闭环：如何确保 Claude 的输出确实正确
  • 遇到问题时快速定位根因的方法
  • 版本更新要点与升级建议

→ 反模式清单和验证闭环是避免踩坑的关键，建议重点关注。

⚙️ 高效使用技巧

把 CLAUDE.md 用成"团队交接文档"

想象你加入一个新团队，第一天坐下来，桌上放着一份"项目规范速查卡"——数据库用哪个端口、代码风格是什么、部署流程怎么走。你读完后立刻就能干活，不用每次都问同事。

CLAUDE.md 就是 Claude Code 的那份速查卡。

每层级的职责：

层级 文件位置 适用范围 典型内容
全局 ~/.claude/CLAUDE.md 所有项目 你的角色、输出语言、编码习惯
项目 项目根目录 CLAUDE.md 当前项目 技术栈、常用命令、架构约定
目录 子目录 CLAUDE.md 特定模块 模块专属的约束和约定

💡 关键原则：写 Claude Code 能直接执行的指令，而不是写给人类看的描述。

1
2
❌ "项目使用 Java 17 和 Spring Boot"
✅ "Java 17 + Spring Boot 3.5.0，构建命令：mvn clean package -DskipTests"

后者明确到可以直接复制粘贴去执行，Claude Code 不需要"猜测"构建命令是什么。

指令要具体，别让 Claude 猜

Claude Code 的能力和普通对话模型的最大区别，是它能直接操作你的文件系统和终端。这意味着**模糊的指令会直接变成错误的文件修改**。

⚠️ 反面例子 → "优化一下这个模块的性能"

正面做法 → 指明三要素：改哪里、改成什么样、不改什么：

1
2
3
4
请优化 src/service/OrderService.java 中的 queryOrders() 方法：
1. 将 N+1 查询改为批量查询（使用 IN 条件）
2. 不要修改方法的入参和返回值类型
3. 不要改动同文件中的其他方法

用 Plan Mode 先探路，再动手

Plan Mode（规划模式）是 Claude Code 的"安全沙盒"——它可以在不修改任何文件的前提下，帮你分析代码、评估影响、规划方案。按 Shift+Tab 切换。

这就像装修前先让设计师出方案图，你看完确认了再让施工队进场，而不是直接给工人一把锤子说"你觉得哪里不好就砸哪里"。

适合用 Plan Mode 的场景：

  • 不熟悉的代码库，需要先了解再动手
  • 修改可能影响多个文件，想先评估风险
  • 不确定最佳实现方案，需要先讨论

⚡ Auto Mode：让 Claude 自主执行

按 Shift+Tab 循环切换三种交互模式：Ask → Plan → Auto。

模式 行为
Ask（默认） 每次工具调用都询问是否确认
Plan 只读探索，不修改文件
Auto 直接执行，不询问确认

Auto Mode 适合对任务和代码库都非常熟悉、希望 Claude 完全自主完成的场景——比如运行你已经验证过的标准重构流程、或者在 CI 环境中批量处理任务。

⚠️ Auto Mode 当前需要 Max / Teams / Enterprise 计划，并配合 Opus 4.7 模型使用（普通订阅用户敬请关注后续开放）。在不熟悉的代码库中不建议直接使用 Auto Mode。

🧠 Effort 级别：控制思考深度

Claude Code 支持通过 /effort 命令控制每次回复的思考深度：

级别 适用场景
low 简单问答、格式化、命名建议
medium 一般代码修改（默认）
high 复杂设计、架构决策
xhigh 深度推理任务（Opus 4.7 新增）
max 最高质量输出，速度最慢

💡 日常开发中使用默认的 medium 即可。只有在做架构设计或者排查疑难 Bug 时才需要提升 Effort 级别。xhigh 和 max 会显著增加响应时间和成本。

📋 Recaps 与 Focus Mode

Recaps（会话回顾）：当你离开一段时间后回到一个长会话，Claude Code 会自动生成一段摘要，告诉你"这段时间发生了什么"。

  • 可通过 /config 开关此功能
  • 也可以随时手动触发：输入 /recap
  • 对禁用遥测的用户（Bedrock、Vertex、Foundry）同样可用

Focus Mode：输入 /focus 进入专注模式。在这个模式下，Claude Code 只展示最终结果，隐藏所有中间步骤的工具调用和思考过程。

💡 适合你只想看结论、不关心过程的场景（比如批量重命名、格式化整个项目）。

💬 /btw：不打断当前任务的旁问

在 Claude 正在执行任务时，如果你临时想问一个不相关的问题，使用 /btw 前缀：

1
/btw 这个项目用的是什么许可证？

Claude 会快速回答这个问题，然后继续手头的任务，不会让你的旁问干扰当前工作流。

善用 Subagent 分而治之

当一个任务需要查阅大量文件时，主对话的上下文窗口会被迅速填满。Subagent（子代理）就像你派出去的侦察兵——它在独立的上下文中完成任务，只把结果汇报回来。

💡 比如你想了解项目中所有 API 接口的设计模式，与其让主对话逐个打开 30 个 Controller 文件，不如启动一个 Subagent 去做这件事，它会把分析结果整理好交给你。

会话管理：该续就续，该断就断

Claude Code 的会话（Session）可以随时恢复，这意味着你不需要在一次对话中完成所有工作。

操作 命令 说明
恢复上次会话 claude --continue 直接接着聊
恢复指定会话 claude --resume 从列表中选择
重命名当前会话 /rename 方便日后查找
回退到某个节点 /rewind 撤销之后的操作

🔄 推荐节奏：一个会话聚焦一个任务（比如"修复登录 Bug"），做完就结束，下一个任务开新会话。不要在一个会话里做完全不相关的事情。

验证结果，别盲目信任

Claude Code 能生成代码，但**验证是你的责任**。推荐三步验证法：

  1. 跑测试 → 让 Claude Code 执行相关测试，确认通过
  2. 看改动 → 用 git diff 审查它实际改了什么
  3. 手动验证 → 对关键逻辑做一次人工走查

💡 经验之谈：要求 Claude Code "先写测试，再改代码"，比改完代码再补测试要可靠得多——测试就是你的安全网。

🔄 常用工作流

HANDOFF.md：跨会话传递进度

当任务较大需要跨多个会话完成时，推荐使用 HANDOFF.md 模式：在当前会话结束前，让 Claude 写一份交接文档，记录进展、尝试过的方案、成功/失败的路径和下一步计划。下一个会话只需读取这个文件就能无缝衔接。

💡 详见「上下文工程」中对 HANDOFF.md 模式的详细介绍。

📌 PR 工作流：小而精，可追溯

根据实际 Claude Code 使用经验，以下 PR 工作流实践效果最好：

  • 始终 Squash Merge：将一个功能分支的所有 commit 压缩成一个，保持主分支的提交历史干净可追溯
  • 保持 PR 小：平均 PR 建议控制在 100-200 行以内（经验中位数约 118 行）。PR 越小，审查越快，出错越少
  • 一个 PR 只做一件事：不要把"修 Bug + 重构 + 加新功能"放在同一个 PR 里
  • 任务完成后立即提 PR：不要攒着多个功能一起提，这样冲突最少

💡 Claude Code 配合 /batch 可以批量并行处理多个独立的小改动：它会创建多个 Git Worktree，在各自独立的分支上并行完成任务，最后你再逐个 review 提 PR。

代码审查工作流

代码审查（Code Review）的核心目标是快速发现潜在问题，而不是逐行重读代码。

推荐步骤：

  1. 让 Claude Code 先分析 → 给它一个 PR diff 或文件路径，让它识别潜在问题
  2. 聚焦关键发现 → 让它按严重程度排序，先看高优先级的问题
  3. 要求具体建议 → 不只说"这里有问题"，而是给出修复方案

💡 实际操作中，你可以直接把 GitHub PR 的 diff 内容粘贴给 Claude Code，或者用 gh pr diff 123 的输出。

如果想将代码审查自动化到 CI 流程中，可以通过 GitHub Actions 配置自动审查——每个 PR 提交后自动触发 Claude Code 进行代码审查，并将结果以评论形式发布到 PR 中。详见「GitHub Actions」中的集成说明。

Bug 修复工作流

修 Bug 最忌讳"凭直觉改一行试试看"——这种改法经常引入新 Bug。

推荐步骤：

  1. 复现优先 → 先写一个能稳定复现 Bug 的测试（即使是通过的测试，也要能展示"期望行为"）
  2. 缩小范围 → 用 Plan Mode 分析可能的根因范围，不要一上来就改
  3. 最小修改 → 只改必要的代码，不做"顺便"的重构
  4. 验证修复 → 运行测试确认 Bug 已修复，且没有引入新问题

⚠️ 常见误区：修了一个 Bug 但没写测试覆盖它 → 同样的 Bug 将来还会出现。

功能开发工作流

开发新功能时，最关键的是**先对齐需求，再动手编码**。

推荐步骤：

  1. 用 Plan Mode 讨论方案 → 描述你要做的功能，让 Claude Code 帮你规划实现步骤
  2. 确认边界 → 明确哪些在范围内、哪些不在
  3. 分步实现 → 每一步都是一个小的、可验证的改动
  4. 持续验证 → 每完成一步就跑测试

💡 如果功能涉及多个文件（比如加一个新的 API 端点 + Service + DTO），可以先用 Plan Mode 画出完整的改动清单，然后逐步执行。

💰 成本管理

Token 是什么？为什么它很重要？

每一次你和 Claude Code 的交互——包括你输入的指令、它读取的文件内容、它生成的回复——都消耗 Token。可以把 Token 想象成"对话燃料"，用完了就需要等待或付费补充。

具体来说，1 个 token 约等于 4 个英文字符或 0.75 个英文单词。中文的情况更复杂——一个常用汉字通常消耗 1-2 个 token，生僻字可能需要更多。所以一段 1000 字的中文大约需要 1000-2000 个 token。

成本构成

消耗来源 占比 说明
文件读取 较高 读取大文件会占用大量上下文
代码生成 中等 Claude Code 生成的代码也计入 Token
工具调用 较低 执行命令、搜索等操作的额外开销
重复读取 浪费 同一文件在对话中被多次读取

10+ 种节省 Token 的策略

以下策略按效果从高到低排列：

高收益策略：

  1. 保持 CLAUDE.md 精简 → CLAUDE.md 在每次对话开头都会加载，越长越费 Token。只放最关键的指令，删掉冗余说明
  2. 使用 .claudeignore 排除无关文件 → 像 .gitignore 一样，排除 node_modules、build、dist 等目录，避免 Claude Code 误读大文件
  3. 善用 Subagent → 让 Subagent 在独立上下文中处理文件密集型任务，避免污染主对话的上下文窗口
  4. 指定精确的文件路径 → 别说"看看数据库相关的代码"，直接说"看 src/main/java/com/example/repository/UserRepository.java"

中收益策略：

  1. 拆分任务到多个会话 → 一个会话做一件事，别把"修 Bug + 重构 + 加新功能"混在一起
  2. 使用 /compact 命令 → 当对话变长时，手动触发上下文压缩，保留关键信息、丢弃冗余
  3. 避免让 Claude Code 读大文件 → 如果只需要文件的一小部分，用行号范围指定
  4. 用 grep 代替全文搜索 → 搜索特定模式时，用 grep 精准定位，比让 Claude Code 逐个打开文件高效

低收益但值得养成习惯的策略：

  1. 指令简洁有力 → 不需要铺垫和客套，直接说目标
  2. 利用 Git Worktree 并行工作 → 多个独立任务可以开多个 Worktree，每个有自己的 Claude Code 会话
  3. 选择合适的模型 → 简单任务可以用更轻量的模型，复杂任务再用旗舰模型

  4. 调整 Prompt 缓存 TTL → Claude Code 支持自定义 Prompt 缓存的生存时间（TTL）。默认情况下订阅用户享受 1 小时缓存 TTL，你也可以通过 settings.json 的 env 字段设置环境变量来调整：ENABLE_PROMPT_CACHING_1H=1 启用 1 小时缓存，FORCE_PROMPT_CACHING_5M=1 强制 5 分钟缓存。更长的缓存 TTL 意味着重复对话的成本更低（2.1.108 新增）。配置方式：

    settings.json
    1
2
3
4
5
    {
  "env": {
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}

团队使用建议

如果你的团队多人共用 Claude Code，需要注意 API 速率限制（Rate Limit）。以下是官方给出的参考值：

团队规模 建议 RPM（每分钟请求数） 建议 TPM（每分钟 Token 数）
1-3 人 50-100 40,000-100,000
4-10 人 100-200 100,000-200,000
11-50 人 200-500 200,000-500,000
50+ 人 500+ 500,000+

💡 如果经常遇到限流错误，说明需要提升速率限制了。

🔧 故障排除

常见问题与解决方案

问题现象 可能原因 解决方案
安装后 claude 命令找不到 Node.js 未安装或版本过低 安装 Node.js 18+，重新运行 npm install -g @anthropic-ai/claude-code
认证失败 / 登录超时 网络问题或 API Key 过期 检查网络连接，运行 claude auth status 确认状态
上下文窗口满导致截断 对话过长或读取了大文件 使用 /compact 压缩上下文，或开新会话
Claude Code 响应变慢 上下文过大或 API 负载高 使用 Subagent 分担任务，检查 API 状态页
文件修改不符合预期 CLAUDE.md 指令不够明确 优化 CLAUDE.md，给出更具体的约束
IDE 集成不生效 插件未正确安装或配置 检查 VS Code / JetBrains 插件是否已启用
Git 操作失败 工作区有未提交的更改 先 git stash 或 git commit，再执行操作
MCP 服务器连接失败 服务器进程未启动或配置错误 检查 MCP 配置文件，确认服务器可访问
Shift+Tab Plan Mode 无响应 终端不支持或快捷键被占用 在支持的终端中使用，或用 /plan 命令替代
Hook 执行报错 Hook 脚本语法错误或权限不足 检查 Hook 脚本的语法和执行权限
非交互模式（-p）输出异常 输出包含非文本内容 确保提示词和输出都是纯文本
Auto-accept 模式下出现意外修改 权限过于宽松 仅在可信环境中使用 --dangerously-skip-permissions
Mermaid 图表不渲染 缺少 custom_fences 配置 在 Markdown 扩展配置中添加 Mermaid fence 支持
深色模式下 Mermaid 文字模糊 CSS 变量未适配 Shadow DOM 通过 CSS 变量覆盖 Mermaid 颜色（CSS 变量可穿透 Shadow DOM）

排错方法论

遇到问题时，按以下顺序排查：

  1. 看错误信息 → Claude Code 的错误提示通常包含明确的根因
  2. 检查配置 → CLAUDE.md、.claudeignore、MCP 配置是否正确
  3. 检查环境 → Node.js 版本、网络连接、API Key 状态
  4. 查看日志 → 运行 claude --verbose 获取详细日志
  5. 搜索更新日志 → 新版本可能已修复你遇到的问题

🚫 反模式清单

以下是在使用 Claude Code 过程中常见的一些错误做法。对照检查，能帮你避免大量踩坑。

CLAUDE.md 反模式

❌ 反模式 ✅ 正确做法 为什么
写了大段背景介绍和项目历史 只放构建命令、架构边界、禁止事项 背景信息 Claude 可以通过读代码推断，CLAUDE.md 应该放「每次都要成立的事」
写空泛原则如「写高质量代码」 写具体可执行的约束如「Service 层不允许注入 HttpServletRequest」 模糊指令等于没有指令，Claude 无法判断什么是"高质量"
把完整 API 文档塞进 CLAUDE.md 放到 Skills 的辅助文件中按需加载 每 token 都要花成本，低频参考文档不该占固定上下文
CLAUDE.md 越写越长 定期审查，过时的条目删掉，低频内容移到 Skills Anthropic 官方自己的 CLAUDE.md 大约只有 2.5K tokens

Skills 反模式

❌ 反模式 ✅ 正确做法 为什么
description 太模糊：「help with backend」 精准描述触发场景：「Use for PR reviews with focus on correctness」 模糊描述会频繁误触发，浪费上下文
一个 Skill 覆盖 review、deploy、debug、docs 五件事 每个 Skill 聚焦一个职责 单一职责，否则 Skill 正文会膨胀到不可维护
有副作用的 Skill 允许模型自动调用 设 disable-model-invocation: true 你不会希望 Claude 看到代码改好了就自动部署
几百行工作手册全塞进 SKILL.md 正文 拆到辅助文件中，SKILL.md 只放导航和核心约束 SKILL.md 应控制在 500 行以内

Sub-agents 反模式

❌ 反模式 ✅ 正确做法 为什么
子代理权限和主线程一样宽 显式限制 tools 和 disallowedTools 隔离没有意义
子任务之间强依赖，频繁共享中间状态 这种场景不用 Subagent，在主线程做 Subagent 适合独立任务
没有设定 maxTurns 设置合理的轮数上限 防止子代理跑飞

通用反模式

❌ 反模式 ✅ 正确做法 为什么
结果不稳定时反复调 prompt 检查上下文加载顺序，考虑开新会话 大概率是上下文污染，不是 prompt 问题
被纠偏两次以上还在同一会话里调 /clear 开新会话 长会话的质量衰减很难逆转
说不清「什么叫做完」就丢给 Claude 自动执行 先定义验收标准再开始 没有验证标准，Claude 再聪明也跑不出正确答案
依赖 CLAUDE.md 规则代替 Hooks 做硬性校验 关键路径用 Hook 强制执行 CLAUDE.md 是建议，Hook 是机制

✅ 验证闭环

「Claude 说完成了」其实没啥用——你得能知道它做没做对、出了问题能退回来、过程还能查。这就是**验证闭环**。

验证层级

验证不是跑一次测试就算完了，而是一个分层体系：

层级 验证什么 怎么做 谁来做
最低层 语法、类型、格式 typecheck、lint、编译检查 Hook 自动触发
中间层 功能正确性 单元测试、集成测试、contract test Claude 执行，你确认
更高层 生产级验证 截图对比、日志验证、监控指标 你手动确认
最高层 业务正确性 人工审查清单 你亲自做

在 CLAUDE.md 中定义验证标准

让 Claude 在完成任务前就知道怎么才算"做完了"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
## Verification

For backend changes:
- Run `mvn test` and `mvn verify`
- For API changes, update contract tests under `tests/contracts/`

For UI changes:
- Capture before/after screenshots if visual

Definition of done:
- All tests pass
- Lint passes
- No TODO left behind unless explicitly tracked

💡 简单判断标准：假如你都说不清楚「Claude 怎么才算做对了」，那这个任务大概率不适合直接丢给 Claude 自主完成。

📋 版本更新要点

Claude Code 保持高频更新，以下是近期一些值得关注的功能改进：

功能增强

  • Subagent 上下文隔离 → 子代理在独立上下文中工作，完成后只返回结果摘要，大幅减少主对话的上下文消耗
  • Plan Mode → 按 Shift+Tab 进入规划模式，探索代码但不做修改
  • Git Worktree 支持 → 多个会话并行开发不同功能，互不干扰
  • Hook 系统 → 在工具调用前后插入自定义脚本，实现确定性的自动化流程
  • Skills 系统 → 按需加载知识模块，避免一次性加载所有上下文
  • Auto-compaction → 上下文接近满时自动压缩，减少手动干预
  • 会话恢复 → --continue、--resume 命令支持跨会话 continuity

稳定性改进

  • IDE 集成的连接稳定性提升，减少了断连和超时
  • 大型仓库的文件搜索性能优化
  • Token 计数更精确，成本预估更可靠
  • 通过按需加载语言语法，减少文件读取、编辑和语法高亮的内存占用（2.1.108 改进）
  • v2.1.121 修复了多个内存泄漏问题：/usage 命令可能泄漏约 2GB 内存、处理大量图片时的无界内存增长、长时间运行工具的内存泄漏。如果你在长会话中遇到内存持续增长，升级到最新版本应该能显著改善

💡 建议：保持 Claude Code 更新到最新版本，新版本通常包含性能改进和 Bug 修复。使用 npm update -g @anthropic-ai/claude-code 更新。