Claude Code 最佳实践

Claude Code 最佳实践

翻译自：Claude Code: Best practices for agentic coding

Claude Code 是一款用于代理式编程的命令行工具，为工程师提供了一种更原生的方式，将 Claude 集成到编码工作流中。本文概述了一些已被证明有效的通用模式和最佳实践。

1. 自定义你的设置

Claude Code 是一款代理式编程助手，会自动将上下文拉入提示中。通过环境调优，可以优化时间和 token 消耗。

a. 创建 CLAUDE.md 文件

CLAUDE.md 是一个特殊文件，Claude 在开始对话时会自动将其拉入上下文。这使其成为记录以下内容的理想场所：

• 常用 bash 命令
• 核心文件和工具函数
• 代码风格指南
• 测试说明
• 仓库规范（如分支命名、合并 vs. rebase 等）
• 开发环境设置（如 pyenv 使用、可用编译器等）
• 项目中特有的异常行为或警告
• 你希望 Claude 记住的其他信息

CLAUDE.md 文件没有固定格式。建议保持简洁且易读。例如：

# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md 文件位置

你可以将 CLAUDE.md 文件放在多个位置：

• 仓库根目录，或你运行 claude 的地方（最常见）
  • 命名为 CLAUDE.md 并提交到 git，以便在会话间和团队成员间共享（推荐）
  • 或命名为 CLAUDE.local.md 并加入 .gitignore
• 父级目录：你运行 claude 目录的任意父级，特别适合 monorepo
• 子级目录：你运行 claude 目录的任意子级，Claude 会在处理子目录文件时按需拉入
• home 文件夹：~/.claude/CLAUDE.md，适用于所有 claude 会话

运行 /init 命令时，Claude 会自动为你生成一个 CLAUDE.md。

b. 调优你的 CLAUDE.md 文件

CLAUDE.md 文件会成为 Claude 提示的一部分，因此应像常用提示一样不断优化。常见错误是添加了大量内容却没有迭代其有效性。

优化技巧：

• 手动添加内容，也可以按 # 键给 Claude 下指令自动写入
• 许多工程师在编码时频繁用 # 记录命令、文件和风格指南
• 在 Anthropic，会用提示优化器处理 CLAUDE.md 文件
• 经常调整指令（如用”IMPORTANT”或”YOU MUST”加重语气）以提升遵循度

c. 管理 Claude 的允许工具列表

默认情况下，Claude Code 对任何可能修改系统的操作都会请求权限。你可以自定义允许列表：

管理允许工具的四种方式：

1. 在会话中被提示时选择”Always allow”
2. 会话中使用 /permissions 命令添加或移除允许的工具
3. 手动编辑 .claude/settings.json 或 ~/.claude.json（推荐将前者提交到源码管理）
4. 用 --allowedTools CLI 标志为会话指定权限

d. 安装 gh CLI

Claude 能用 gh CLI 与 GitHub 交互，如创建 issue、打开 PR、读取评论等。没有安装 gh 时，Claude 仍可用 GitHub API 或 MCP 服务器。

2. 给 Claude 更多工具

a. 用 bash 工具配合 Claude

Claude Code 继承你的 bash 环境，能访问所有工具。对于自定义 bash 工具：

• 告诉 Claude 工具名并举例用法
• 告诉 Claude 运行 --help 查看工具文档
• 在 CLAUDE.md 记录常用工具

b. 用 MCP 配合 Claude

Claude Code 既是 MCP 服务器也是客户端。作为客户端，它可通过三种方式连接任意数量的 MCP 服务器：

• 项目配置中（在该目录运行 Claude Code 时可用）
• 全局配置中（所有项目可用）
• 提交到 .mcp.json 文件（任何在你代码库工作的成员都可用）

用 MCP 时，建议用 --mcp-debug 标志帮助排查配置问题。

c. 用自定义斜杠命令

对于重复性工作流，可将提示模板存储在 .claude/commands 文件夹下的 Markdown 文件中。自定义斜杠命令可用特殊关键字 $ARGUMENTS 传递参数。

示例：自动拉取并修复 GitHub issue 的斜杠命令

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:
1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

将上述内容放入 .claude/commands/fix-github-issue.md 后，即可通过 /project:fix-github-issue 1234 命令调用。

3. 尝试常见工作流

a. 探索、规划、编码、提交

适用于多种问题的通用工作流：

1. 探索：让 Claude 阅读相关文件、图片或 URL，明确告知暂时不要写代码
2. 规划：让 Claude 制定解决特定问题的计划，建议用”think”一词触发扩展思考模式
3. 编码：让 Claude 实现解决方案代码，可在实现过程中显式验证方案
4. 提交：让 Claude 提交结果并创建 PR

第 1-2 步至关重要——否则 Claude 往往会直接跳到编码。

b. 写测试、提交；编码、迭代、提交

适合测试驱动开发（TDD）的工作流：

1. 让 Claude 根据预期输入/输出对写测试，明确说明你在做 TDD
2. 让 Claude 运行测试并确认失败
3. 对测试满意后让 Claude 提交测试
4. 让 Claude 编写通过测试的代码，告知不要修改测试
5. 持续迭代直到所有测试通过
6. 对更改满意后让 Claude 提交代码

c. 编码、截图结果、迭代

类似测试工作流，提供可视化目标：

1. 为 Claude 提供截图工具
2. 通过粘贴、拖拽或文件路径提供视觉 mock
3. 让 Claude 实现设计、截图结果并迭代，直到结果与 mock 匹配
4. 满意后让 Claude 提交

d. 安全 YOLO 模式

用 claude --dangerously-skip-permissions 跳过所有权限检查，让 Claude 一次性完成任务。适合修复 lint 错误或生成样板代码。

注意：有风险，建议在无网络访问的容器中使用。

e. 代码库问答

新成员入职时，可用 Claude Code 学习和探索代码库：

• 日志是如何工作的？
• 如何新增 API 端点？
• foo.rs 第 134 行的 async move { ... } 有什么作用？
• CustomerOnboardingFlowImpl 处理了哪些边界情况？

f. 用 Claude 操作 git

Claude 能高效处理许多 git 操作：

• 搜索 git 历史
• 编写提交信息
• 处理复杂 git 操作（回滚文件、解决 rebase 冲突等）

g. 用 Claude 操作 GitHub

Claude Code 可管理许多 GitHub 交互：

• 创建 PR
• 解决代码审查评论
• 修复构建失败或 linter 警告
• 分类和整理 open issues

h. 用 Claude 处理 Jupyter notebook

Claude 能解读输出（包括图片），快速探索和交互数据。建议在 VS Code 并排打开 Claude Code 和 .ipynb 文件。

4. 优化你的工作流

a. 指令要具体

Claude Code 在收到更具体指令时成功率显著提升。明确指令能减少后续修正。

示例：

参考首页现有 widget 的实现，了解模式，尤其是代码与接口如何分离。HotDogWidget.php 是很好的例子。然后，按此模式实现一个新日历 widget，支持选择月份和前后翻页选择年份。只用代码库已有的库，从零实现。

b. 给 Claude 图片

Claude 通过多种方式善于处理图片和图表：

• 粘贴截图（macOS 下 cmd+ctrl+shift+4 截图到剪贴板，ctrl+v 粘贴）
• 拖拽图片到输入框
• 提供图片文件路径

c. 明确提及要处理的文件

用 tab 补全快速引用仓库中任意文件或文件夹，帮助 Claude 找到或更新正确资源。

d. 给 Claude URL

在提示中粘贴具体 URL，Claude 会自动拉取和阅读。为避免同一域名反复请求权限，用 /permissions 添加域名到允许列表。

e. 及时纠正

主动协作和引导 Claude 通常效果更好。四种纠正工具：

• 让 Claude 先制定计划，明确告知未确认前不要编码
• 按 Escape 中断 Claude 任意阶段
• 双击 Escape 回到历史记录，编辑前一个提示
• 让 Claude 撤销更改

f. 用 /clear 保持上下文聚焦

长会话中，每完成一个任务，建议用 /clear 重置上下文窗口。

g. 用清单和草稿本处理复杂工作流

对于多步骤或需穷举解决方案的大型任务，建议让 Claude 用 Markdown 文件做清单和草稿本。

h. 向 Claude 传递数据

多种方式向 Claude 提供数据：

• 直接复制粘贴到提示（最常用）
• 管道传入 Claude Code（如 cat foo.txt | claude）
• 让 Claude 通过 bash 命令、MCP 工具或自定义斜杠命令拉取数据
• 让 Claude 读取文件或拉取 URL

5. 用无头模式自动化基础设施

Claude Code 提供无头模式，适用于 CI、pre-commit 钩子、构建脚本和自动化等非交互场景。用 -p 标志加提示启用无头模式，--output-format stream-json 可流式输出 JSON。

a. 用 Claude 处理 issue 分拣

无头模式可驱动由 GitHub 事件触发的自动化，如新 issue 创建时的标签分配。

b. 用 Claude 做 linter

Claude Code 可做主观代码审查，发现传统 linter 检查不到的问题，如拼写错误、过时注释、误导性函数或变量名等。

6. 多 Claude 协作提升效率

a. 一个 Claude 写代码，另一个 Claude 审查

简单高效的协作方法：

1. 用 Claude 写代码
2. 用 /clear 或在另一个终端启动第二个 Claude
3. 让第二个 Claude 审查第一个 Claude 的工作
4. 再启动一个 Claude，读取代码和审查反馈
5. 让这个 Claude 根据反馈修改代码

b. 多仓库检出

许多工程师的做法：

1. 创建 3-4 个 git 检出，放在不同文件夹
2. 分别在不同终端标签页打开每个文件夹
3. 在每个文件夹启动 Claude，分配不同任务
4. 轮流检查进度，批准/拒绝权限请求

c. 用 git worktree

适合多个独立任务，是多检出的轻量替代方案：

# 创建 worktree
git worktree add ../project-feature-a feature-a

# 在每个 worktree 启动 Claude
cd ../project-feature-a && claude

# 完成后清理
git worktree remove ../project-feature-a

d. 用无头模式配合自定义脚本

两种主要模式：

批量处理：

1. 让 Claude 写脚本生成任务列表
2. 循环处理任务，程序化调用 Claude
3. 多次运行脚本，迭代优化提示

流水线：

claude -p "<你的提示>" --json | your_command

总结

Claude Code 不强加特定工作流，给你充分的灵活性。关键是：

• 充分利用 CLAUDE.md 文件和工具允许列表
• 明确具体的指令
• 善用图片、文件引用和URL
• 及时纠正和引导
• 考虑多 Claude 协作处理复杂任务

通过这些最佳实践，可以显著提升 Claude Code 的效率和准确性。