cc-best-practices

---

Claude Code 最佳实践

基于 Anthropic 官方文档：https://code.claude.com/docs/en/best-practices。

最重要的约束：Claude 的上下文窗口很快就会被填满，而且随着窗口填满，性能会下降。 所有最佳实践都由此而来。

---

说明

步骤 1：始终为 Claude 提供验证工作的方法

提供可运行的检查（测试套件、构建退出码、代码检查工具、差异脚本），让 Claude 能独立确认是否成功。要求提供证据（测试输出、命令结果），而不只是断言。

步骤 2：对非简单任务使用“探索 → 规划 → 实施”工作流

进入 /plan 模式，让 Claude 先阅读代码库，然后再起草计划，之后再编写代码。退出规划模式后再实施。只有对于小型且显而易见的改动，才跳过此步骤。

步骤 3：编写具体且范围明确的提示词

写明文件名（@filename），描述症状而不是猜测，并参考现有模式。模糊的提示词会产生模糊的结果。

步骤 4：让 CLAUDE.md 保持简短且可执行

只包含 Claude 无法从代码中推断的信息。每一行都应回答：“删掉这条内容会导致 Claude 犯错吗？”如果不会，就删掉。

步骤 5：积极管理上下文

在无关任务之间使用 /clear。针对同一问题连续两次修正失败后，清空上下文并编写更好的提示词。使用 /compact <hint> 进行有重点的上下文压缩。

步骤 6：使用子 Agent 进行调查和审查

让子 Agent 探索不熟悉的代码，或审查你的实现——它们会在全新的上下文中运行，不会对自己刚写的代码抱有偏见。

---

示例

示例 1：正确实现一项功能

用户说：“我让 Claude 实现功能时，结果总是不稳定。”

操作：

1. 在提示词中添加验证步骤：“编写一个 validateEmail 函数——实现后运行现有测试套件，并向我展示输出”
2. 如果没有测试：“编写该函数并为其编写测试，运行测试并展示结果”
3. 设置 Stop 钩子，在测试通过前阻止回合结束

结果：Claude 会持续迭代，直到测试通过，而不是在代码_看起来_完成时就停下。

示例 2：处理复杂的多文件改动

用户说：“跨 10 个文件进行大规模重构时，我该怎么做？”

操作：

1. 进入 /plan 模式——Claude 只进行探索，不做任何改动
2. 提出要求：“阅读受影响的文件，并编写逐步实施计划”
3. 如有需要，使用 Ctrl+G 直接编辑计划
4. 退出规划模式——Claude 按照计划实施并提交
5. 运行一个子 Agent，在全新上下文中审查差异

结果：通过可审查的计划实现有条理的重构，避免在探索和编写交替进行时造成上下文混乱。

示例 3：Claude 一再重复同一个错误

用户说：“我已经针对同一个问题纠正 Claude 3 次了，但它还是做错。”

操作：

1. 运行 /clear——开启全新的上下文
2. 找出原始提示词中缺少的内容（缺少约束、缺少示例、范围模糊）
3. 编写新的初始提示词，明确说明约束：“重要：这些测试中不要使用模拟对象——请使用真实的数据库连接”
4. 如果该约束适用于整个项目，就将其添加到 CLAUDE.md

结果：明确说明要求后的全新会话，效果胜过积累了多次修正的冗长会话。

---

---

1. 让 Claude 能够验证自己的工作

工作_看起来_完成时，Claude 就会停下来。如果没有可运行的检查，你就得负责验证。提供一种 Claude 能读取结果的检查，让它返回通过／失败信号：测试套件、构建退出代码、代码检查工具，或用于比较输出的脚本。

• 在同一个提示词中要求 Claude 运行检查并迭代。
• 为多轮验证设置 /goal 条件。
• 使用 Stop hook，在脚本通过前阻止当前轮次结束。
• 使用 verification subagent，让审查者拥有全新的上下文。

要求 Claude 提供证据（测试输出、命令结果、屏幕截图），而不是只声称成功。

改进示例：

之前："实现一个用于验证电子邮件地址的函数" 之后：*"编写一个 validateEmail 函数。测试用例：[email protected] → true，

invalid → false。实现后运行测试"*

---

2. 先探索，再规划，最后编码

使用规划模式（/plan 或 UI 开关）将阅读与编写分开。

1. 探索 — 进入规划模式；Claude 阅读文件，但不做任何修改。
2. 规划 — 要求 Claude 编写详细的实现计划。按 Ctrl+G，在编辑器中打开计划并直接编辑。
3. 实现 — 退出规划模式；Claude 根据计划编写代码并进行验证。
4. 提交 — 要求 Claude 提交更改并创建 PR。

当范围明确且修复较小（拼写错误、重命名、单行更改）时，可以跳过规划。规划模式会增加开销——当更改涉及多个文件或你不熟悉代码时再使用。

---

3. 在提示词中提供具体上下文

Claude 可以推断意图，但无法读懂你的想法。

策略	模糊	具体
界定任务范围	"为 foo.py 添加测试"	"为 foo.py 编写测试，覆盖用户已登出的边缘情况。避免使用模拟对象。"
指明来源	"为什么 ExecutionFactory 的 API 很奇怪？"	"查看 ExecutionFactory 的 git 历史记录，并总结其 API 的演变过程"
参考现有模式	"添加一个日历小组件"	"参考 HotDogWidget.php，并按其模式实现一个日历小组件"
描述症状	"修复登录问题"	"用户报告会话超时后登录失败。检查 src/auth/ 中的令牌刷新逻辑。先编写一个会失败的测试，再修复问题。"

丰富上下文的技巧：

• 使用 @filename 直接引用文件。
• 将屏幕截图粘贴到提示词中，或将图片拖入其中。
• 通过管道传递数据：cat error.log | claude
• 提供文档 URL（通过 /permissions 将域名加入允许列表）。

---

4. 编写有效的 CLAUDE.md

每次会话开始时都会读取 CLAUDE.md。请保持文件简短且易于阅读——臃肿的 CLAUDE.md 会导致 Claude 忽略实际指令。

请包含：

• Claude 无法猜出的 Bash 命令（例如构建／测试命令）
• 有别于语言默认规范的代码风格规则
• 测试说明和首选测试运行器
• 仓库规范（分支命名、PR 约定）
• 项目特有的架构决策
• 开发环境的特殊情况、必需的环境变量
• 常见陷阱或不明显的行为

请排除：

• Claude 通过阅读代码就能弄清楚的内容
• Claude 已经了解的标准语言惯例
• 详细的 API 文档（改为提供链接）
• “编写整洁的代码”这类不言自明的做法

检查每一行：“删除这行会导致 Claude 犯错吗？” 如果不会，就删掉。

使用 /context 确认 Claude 已加载该文件。使用 CLAUDE.md 中的 @path/to/file 导入其他文件的指定内容。

---

5. 积极管理会话上下文

• /clear — 在无关任务之间重置上下文。
• /compact <instructions> — 聚焦压缩内容（例如：/compact Focus on API changes）。
• Esc + Esc / /rewind — 打开回退菜单；恢复到之前任意检查点的对话和／或代码状态。
• /btw — 提出一个快速的旁支问题；答案会显示在浮层中，且不会进入对话历史。

针对同一问题连续两次修正失败后： 运行 /clear，并根据已吸取的经验编写更好的初始提示词。与积累了多次修正的漫长会话相比，使用更好的提示词开启全新会话效果更佳。

在 CLAUDE.md 中自定义压缩行为：

*“压缩时，始终保留完整的已修改文件列表和所有

测试命令”*

---

6. 使用子 Agent 进行调查和审查

子 Agent 在各自的上下文窗口中运行，并汇报摘要，让你的主对话保持简洁。

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

实现后：

use a subagent to review this code for edge cases

使用 /code-review 技能，对当前差异进行以查找 Bug 为重点的对抗式审查。

---

7. 自动化并扩展

非交互模式 — 将 Claude 集成到 CI、提交前钩子和脚本中：

claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json --verbose

分散处理多个文件 — 循环执行任务：

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

并行会话 — 使用 Git worktree 运行多个 Claude 会话，避免编辑冲突。编写者／审查者模式：

• 会话 A 实现一项功能。
• 会话 B 在全新的上下文中审查差异（不会对刚刚编写的代码产生偏袒）。

自动模式 — 通过后台安全检查实现不间断执行：

claude --permission-mode auto -p "fix all lint errors"

---

8. 常见失败模式和快速参考

完整的失败模式表、所有 CLI 命令和非交互模式示例，请参阅 references/commands.md。