原文链接: Claude Code: Best practices for agentic coding

Claude Code 是一款用于智能体编程的命令行工具。本文将介绍一系列实用技巧，这些技巧已在各类代码库、编程语言和开发环境中得到验证，能帮助你更高效地使用 Claude Code。

我们近期发布了 Claude Code，这款命令行工具专为智能体编程打造。作为一项研究项目，它为 Anthropic 的工程师和研究人员提供了一种更原生的方式，将 Claude 集成到日常编程工作流中。

Claude Code 刻意采用底层设计且不强制特定工作模式，能让用户近乎直接访问模型，同时无需遵循固定的工作流程。这种设计理念使其成为一款灵活、可定制、可编写脚本且安全的高效工具。不过，对于刚接触智能体编程工具的工程师而言，这种灵活性意味着需要一定的学习成本 —— 至少在他们形成自己的最佳实践之前是如此。

本文列出的通用模式已被证明行之有效，无论是 Anthropic 的内部团队，还是在各类代码库、语言和环境中使用 Claude Code 的外部工程师，都能从中受益。这些建议并非一成不变或放之四海而皆准，仅作为入门参考。我们鼓励你大胆尝试，找到最适合自己的使用方式！

 

1. 自定义你的设置

Claude Code 是一款智能体编程助手，能自动收集上下文并融入提示词。上下文收集过程会消耗时间和 Token，但你可以通过环境优化来提升效率。

1.1 创建 CLAUDE.md 文件

CLAUDE.md 是一个特殊文件，Claude 在启动对话时会自动将其纳入上下文。因此，它非常适合用来记录以下内容：

• 常用 Bash 命令
• 核心文件和工具函数
• 代码风格指南
• 测试说明
• 代码库使用规范（如分支命名、合并与变基选择等）
• 开发环境配置（如 pyenv 使用方法、兼容的编译器等）
• 项目特有的异常行为或警告信息
• 其他你希望 Claude 记住的信息

CLAUDE.md 没有固定格式要求，建议保持简洁易读。示例如下：

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

• 代码库根目录或运行 claude 命令的任意目录（最常用场景）。命名为 CLAUDE.md 并提交到 git 中，可跨会话与团队共享（推荐）；若命名为 CLAUDE.local.md，可将其加入 .gitignore 忽略提交。
• 运行 claude 命令所在目录的任意父目录。这在单体仓库（monorepos）中尤为实用，例如在 root/foo 目录运行 claude 时，root/CLAUDE.md 和 root/foo/CLAUDE.md 都会被自动纳入上下文。
• 运行 claude 命令所在目录的任意子目录。与上述情况相反，当你操作子目录中的文件时，Claude 会按需加载该子目录下的 CLAUDE.md。
• 你的主目录（~/.claude/CLAUDE.md），适用于所有 Claude 会话。

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

1.2 优化你的 CLAUDE.md 文件

CLAUDE.md 的内容会成为 Claude 提示词的一部分，因此需要像优化常用提示词一样对其进行精炼。常见错误是添加大量内容却不迭代优化效果，建议你花时间尝试不同内容，找到能让模型最准确执行指令的方式。

你可以手动向 CLAUDE.md 添加内容，也可以按下 # 键，向 Claude 发送指令，它会自动将内容整合到相关的 CLAUDE.md 中。许多工程师在编程时会频繁使用 # 键记录命令、文件信息和风格指南，随后将 CLAUDE.md 的修改纳入提交，让团队成员也能受益。

在 Anthropic 内部，我们偶尔会使用提示词优化工具处理 CLAUDE.md，并经常调整指令（例如使用 “IMPORTANT” 或 “YOU MUST” 强调关键内容），以提高模型的遵循度。

 

1.3 筛选 Claude 的允许工具列表

默认情况下，对于可能修改系统的任何操作（如文件写入、多数 Bash 命令、MCP 工具等），Claude Code 都会请求权限。这种刻意保守的设计旨在优先保障安全性。你可以自定义允许列表，批准已知安全的额外工具，或允许易于撤销的潜在不安全工具（如文件编辑、git commit）。

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

• 会话中收到提示时，选择 “始终允许”。
• 启动 Claude Code 后，使用 /permissions 命令添加或移除允许列表中的工具。例如，添加 Edit 可始终允许文件编辑，添加 Bash(git commit:*) 可允许 git 提交，添加 mcp__puppeteer__puppeteer_navigate 可允许通过 Puppeteer MCP 服务器进行导航。
• 手动编辑 .claude/settings.json 或 ~/.claude.json（建议将前者提交到版本控制，以便团队共享）。
• 使用 –allowedTools 命令行参数设置会话专属权限。

1.4 若使用 GitHub，请安装 gh 命令行工具

Claude 可通过 gh 命令行工具与 GitHub 交互，完成创建议题、发起拉取请求、读取评论等操作。若未安装 gh，Claude 仍可通过 GitHub API 或 MCP 服务器（需安装）实现上述功能。

2. 为 Claude 配备更多工具

Claude 可访问你的 Shell 环境，你可以像为自己配置工具一样，为它构建一套便捷脚本和函数。它还能通过 MCP 和 REST API 利用更复杂的工具。

2.1 让 Claude 搭配 Bash 工具使用

Claude Code 会继承你的 Bash 环境，从而获取所有工具的访问权限。虽然 Claude 熟悉 Unix 工具、gh 等常见工具，但若无相关说明，它无法知晓你的自定义 Bash 工具

• 告知 Claude 工具名称及使用示例。
• 让 Claude 运行 –help 查看工具文档。
• 在 CLAUDE.md 中记录常用工具。

2.2 让 Claude 搭配 MCP 使用

Claude Code 兼具 MCP 服务器和客户端功能。作为客户端，它可通过三种方式连接多个 MCP 服务器以使用其工具：

• 项目配置中（仅在该目录运行 Claude Code 时生效）。
• 全局配置中（所有项目均生效）。
• 已提交的 .mcp.json 文件中（代码库的所有使用者均可使用）。例如，在 .mcp.json 中添加 Puppeteer 和 Sentry 服务器，团队每位工程师都能开箱即用这些工具。

使用 MCP 时，可添加 –mcp-debug 参数启动 Claude，这有助于排查配置问题。

2.3 使用自定义斜杠命令

对于重复工作流（如调试循环、日志分析等），可将提示词模板存储在 .claude/commands 文件夹的 Markdown 文件中。输入 / 时，这些模板会显示在斜杠命令菜单中，你可将其提交到 git，方便团队共享。

自定义斜杠命令可包含特殊关键字 $ARGUMENTS，用于传递命令调用时的参数。

例如，以下斜杠命令可自动拉取并修复 GitHub 议题：

将上述内容保存到 .claude/commands/fix-github-issue.md 后，即可在 Claude Code 中使用 /project:fix-github-issue 命令。例如，输入 /project:fix-github-issue 1234，Claude 就会修复编号为 1234 的议题。同样，你可在 ~/.claude/commands 文件夹中添加个人专属命令，使其在所有会话中可用。

3. 尝试常见工作流

Claude Code 不强制特定工作流，让你可灵活选择使用方式。在这种灵活性下，用户社区已形成多种高效使用模式：

3.1 探索→规划→编码→提交

这一通用工作流适用于多种场景：

1. 让 Claude 读取相关文件、图片或 URL，可提供大致指引（如 “读取处理日志的文件”）或具体文件名（如 “读取 logging.py”），但需明确告知它暂不编写代码。
2. 对于复杂问题，建议在此步骤充分使用子智能体。在对话初期或任务启动时，让 Claude 借助子智能体验证细节或调研特定问题，既能保留上下文可用性，又不会显著影响效率。
3. 让 Claude 制定解决特定问题的方案。建议使用 “think” 一词触发扩展思考模式，为 Claude 分配更多计算时间，使其更全面地评估备选方案。以下短语对应递增的思考资源分配：“think”＜“think hard”＜“think harder”＜“ultrathink”，级别越高，分配的思考资源越多。
4. 若方案合理，可让 Claude 将其整理为文档或 GitHub 议题。这样一来，若后续实现（第三步）未达预期，可回溯到该节点重新开始。
5. 让 Claude 按方案编写代码。同时，可要求它在实现过程中逐段验证方案的合理性。
6. 让 Claude 提交代码并创建拉取请求。若有必要，可在此阶段让它更新 README 或变更日志，说明所做修改。

步骤 1-2 至关重要 —— 若省略，Claude 可能直接跳过分析编写代码。虽然有时这正是你需要的，但对于需要前期深入思考的问题，先让 Claude 调研规划能显著提升效果。

3.2 编写测试→提交；编码→迭代→提交

这是 Anthropic 团队青睐的工作流，适用于可通过单元测试、集成测试或端到端测试验证的变更。智能体编程让测试驱动开发（TDD）更加强大：

1. 让 Claude 根据预期输入 / 输出对编写测试。明确告知它正在进行测试驱动开发，避免其为代码库中尚未存在的功能创建模拟实现。
2. 让 Claude 运行测试并确认测试失败。明确要求它在此阶段不编写实现代码通常会很有帮助。
3. 若对测试满意，让 Claude 提交测试代码。
4. 让 Claude 编写能通过测试的代码，并告知它不得修改测试。要求它持续迭代，直至所有测试通过 —— 通常需要多次编写代码、运行测试、调整代码、再运行测试的循环。
5. 此阶段可让独立子智能体验证实现是否未过度拟合测试用例。
6. 对代码修改满意后，让 Claude 提交代码。

当 Claude 有明确的迭代目标（如视觉原型、测试用例或其他输出形式）时，表现最佳。通过提供测试等预期输出，Claude 可不断修改、评估结果并逐步优化，直至达成目标。

3.3 编写代码→截取结果→迭代优化

与测试工作流类似，你也可以为 Claude 提供视觉目标：

1. 为 Claude 配置浏览器截图功能（如通过 Puppeteer MCP 服务器、iOS 模拟器 MCP 服务器，或手动复制粘贴截图到 Claude）。
2. 通过复制粘贴、拖拽图片文件或提供文件路径的方式，将视觉原型提供给 Claude。
3. 让 Claude 根据设计编写代码、截取结果截图，并反复迭代，直至输出与原型一致。
4. 满意后让 Claude 提交代码。

和人类一样，Claude 的输出通过迭代会显著改善。第一版可能已不错，但经过 2-3 次迭代后，效果通常会好得多。为 Claude 提供查看自身输出的工具，能帮助它达到最佳效果。

3.4 安全 YOLO 模式

若无需监督 Claude，可使用 claude –dangerously-skip-permissions 跳过所有权限检查，让它不间断工作直至完成任务。这种模式适用于修复代码检查错误、生成样板代码等工作流。

允许 Claude 运行任意命令存在风险，可能导致数据丢失、系统损坏甚至数据泄露（如通过提示词注入攻击）。为降低风险，建议在无网络访问的容器中使用 –dangerously-skip-permissions。你可参考 Docker 开发容器的实现示例。

3.5 代码库问答

加入新项目时，可使用 Claude Code 进行学习和探索。你可以像与项目其他工程师结对编程时那样向它提问，Claude 会主动搜索代码库，解答各类问题，例如：

• 日志系统如何工作？
• 如何创建新的 API 端点？
• foo.rs 第 134 行的 async move { … } 作用是什么？
• CustomerOnboardingFlowImpl 处理哪些边界情况？
• 为什么第 333 行调用 foo() 而非 bar()？
• baz.py 第 334 行的 Java 等效代码是什么？

在 Anthropic，这种使用方式已成为核心入职流程，大幅缩短了上手时间，同时减轻了其他工程师的负担。无需特殊提示词，直接提问即可，Claude 会自行探索代码寻找答案。

3.6 让 Claude 操作 Git

Claude 能高效处理多种 Git 操作，Anthropic 许多工程师 90% 以上的 Git 交互都通过它完成：

• 搜索 Git 历史，解答 “哪些变更纳入了 v1.2.3 版本？”“谁负责这个功能？”“这个 API 为何如此设计？” 等问题。明确提示 Claude 查看 Git 历史，能帮助它更准确地回答这类查询。
• 编写提交信息。Claude 会自动分析你的修改和近期历史，整合相关上下文生成提交信息。
• 处理复杂 Git 操作，如还原文件、解决变基冲突、比较和合并补丁等。

3.7 让 Claude 操作 GitHub

Claude Code 可管理多种 GitHub 交互：

• 创建拉取请求：Claude 理解 “pr” 缩写，会根据代码差异和周边上下文生成合适的提交信息。
• 一键解决简单代码审查评论：只需告知它修复拉取请求中的评论（可提供更具体的指令），完成后它会将修改推回拉取请求分支。
• 修复构建失败或代码检查警告。
• 分类和筛选开放议题：让 Claude 遍历 GitHub 开放议题并进行分类。

这无需你记忆 gh 命令行语法，同时实现了常规任务的自动化。

3.8 让 Claude 处理 Jupyter 笔记本

Anthropic 的研究人员和数据科学家常用 Claude Code 读取和编写 Jupyter 笔记本。Claude 能解读输出内容（包括图片），提供快速探索和交互数据的方式。无需遵循特定提示词或工作流，但我们推荐在 VS Code 中同时打开 Claude Code 和 .ipynb 文件。

你还可以让 Claude 在与同事分享 Jupyter 笔记本前进行整理或美化。明确要求它让笔记本或数据可视化 “美观易读”，能提醒它优化人类阅读体验。

4. 优化你的工作流

以下建议适用于所有工作流：

4.1 指令要具体

更具体的指令能显著提高 Claude Code 的成功率，尤其是首次尝试时。提前给出明确指引，可减少后续调整的需求。 示例对比：

不佳示例	优质示例
为 foo.py 添加测试	为 foo.py 编写新测试用例，覆盖用户未登录的边界情况，不使用模拟对象
为什么 ExecutionFactory 的 API 这么奇怪？	查看 ExecutionFactory 的 Git 历史，总结其 API 的演变过程
添加日历组件	参考首页现有组件的实现模式，尤其是代码与接口的分离方式（HotDogWidget.php 是不错的起点）。遵循该模式从零实现一个日历组件，支持用户选择月份，并可前后翻页选择年份。仅使用代码库中已有的依赖库，不引入新库

Claude 能推断意图，但无法读懂你的想法。具体的指令能让结果更符合预期。

4.2 向 Claude 提供图片

Claude 擅长处理图片和图表，可通过以下方式提供：

• 粘贴截图（实用技巧：macOS 中按 cmd+ctrl+shift+4 截取屏幕并保存到剪贴板，然后按 ctrl+v 粘贴 —— 注意这与 macOS 常规粘贴快捷键 cmd+v 不同，且远程环境下不适用）。
• 将图片直接拖拽到提示词输入框。
• 提供图片文件路径。

这在 UI 开发中参考设计原型，或通过可视化图表进行分析调试时特别有用。即使不添加视觉素材，明确告知 Claude 结果的视觉美观度重要性，也能起到帮助作用。

4.3 指明希望 Claude 查看或操作的文件

使用制表符自动补全功能，可快速引用代码库中任意位置的文件或文件夹，帮助 Claude 准确找到或更新目标资源。

4.4 向 Claude 提供 URL

在提示词中粘贴具体 URL，Claude 会获取并读取内容。若需避免同一域名（如 docs.foo.com）的重复权限提示，可使用 /permissions 将域名添加到允许列表。

4.5 尽早并频繁调整方向

虽然自动确认模式（按 shift+tab 切换）能让 Claude 自主工作，但作为主动协作者引导其方向，通常能获得更好的结果。你可以在开始时详细说明任务，也可随时调整 Claude 的工作方向。

以下四种工具可辅助调整方向：

• 让 Claude 在编码前制定方案，明确告知它需经你确认方案后再开始编码。
• 在任意阶段（思考、工具调用、文件编辑）按 Escape 键中断 Claude，保留上下文以便重新引导或扩展指令。
• 双击 Escape 键回溯历史，编辑之前的提示词，探索其他解决方向。可反复编辑提示词直至获得满意结果。
• 让 Claude 撤销修改，通常与第二种方式配合使用，尝试其他方案。

尽管 Claude Code 偶尔能一次完美解决问题，但使用这些调整工具通常能更快得到更优解决方案。

4.6 使用 /clear 保持上下文聚焦

长时间会话中，Claude 的上下文窗口可能会充斥无关对话、文件内容和命令，导致性能下降或分散注意力。建议在任务之间频繁使用 /clear 命令重置上下文窗口。

4.7 复杂工作流使用清单和草稿本

对于包含多个步骤或需要全面解决方案的大型任务（如代码迁移、修复大量代码检查错误、运行复杂构建脚本），可让 Claude 使用 Markdown 文件（甚至 GitHub 议题）作为清单和工作草稿本，以提升效率：

例如，修复大量代码检查错误可按以下步骤操作：

1. 让 Claude 运行代码检查命令，并将所有错误（含文件名和行号）写入 Markdown 清单。
2. 指示 Claude 逐一处理每个问题，修复并验证后勾选完成，再进入下一个问题。

4.8 向 Claude 传递数据

提供数据给 Claude 的多种方式：

• 直接复制粘贴到提示词（最常用方式）。
• 管道输入 Claude Code（如 cat foo.txt | claude），特别适用于日志、CSV 和大型数据。
• 让 Claude 通过 Bash 命令、MCP 工具或自定义斜杠命令获取数据。
• 让 Claude 读取文件或获取 URL（同样适用于图片）。

大多数会话会结合多种方式。例如，你可以管道输入日志文件，再让 Claude 使用工具获取额外上下文来调试日志。

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

Claude Code 包含无头模式，适用于 CI、预提交钩子、构建脚本和自动化等非交互场景。使用 -p 参数搭配提示词即可启用无头模式，通过 –output-format stream-json 可获取流式 JSON 输出。

注意，无头模式不会在会话间持久化，每次会话都需单独触发。

5.1 用 Claude 进行议题分类

无头模式可驱动由 GitHub 事件触发的自动化流程，例如代码库新增议题时。例如，Claude Code 公共代码库会使用 Claude 检查新提交的议题，并自动分配相应标签。

5.2 用 Claude 作为代码检查工具

Claude Code 能提供传统代码检查工具无法实现的主观性代码审查，识别拼写错误、过时注释、易混淆的函数或变量名等问题。

6. 借助多 Claude 工作流提升效率

除单独使用外，运行多个 Claude 实例并行工作能实现更强大的功能：

6.1 一个 Claude 编写代码，另一个进行验证

一种简单有效的方式是让一个 Claude 编写代码，另一个进行审查或测试。与多位工程师协作类似，分离的上下文有时能带来更好的效果：

1. 让 Claude 编写代码。
2. 运行 /clear 或在另一个终端启动第二个 Claude。
3. 让第二个 Claude 审查第一个 Claude 的工作成果。
4. 启动第三个 Claude（或再次运行 /clear），让它读取代码和审查反馈。
5. 让这个 Claude 根据反馈修改代码。

测试工作也可采用类似方式：让一个 Claude 编写测试，另一个编写代码以通过测试。你甚至可以让多个 Claude 实例通过独立草稿本通信，指定它们的读写对象。

这种分离模式通常比单个 Claude 处理所有任务的效果更好。

6.2 多代码库检出

无需等待 Claude 完成单个步骤，Anthropic 许多工程师会采用以下方式：

1. 在不同文件夹中创建 3-4 个 Git 检出版本。
2. 在每个文件夹对应的终端标签中打开该目录。
3. 在每个文件夹中启动 Claude，分配不同任务。
4. 循环查看各终端标签，确认进度并批准 / 拒绝权限请求。

6.3 使用 Git 工作树

这种方式适用于多个独立任务，是多检出版本的轻量替代方案。Git 工作树允许将同一代码库的多个分支检出到不同目录，每个工作树有独立的工作目录和文件，同时共享相同的 Git 历史和引用日志。

通过 Git 工作树，你可以在项目的不同部分同时运行多个 Claude 会话，每个会话专注于独立任务。例如，一个 Claude 重构认证系统，另一个构建完全无关的数据可视化组件。由于任务无重叠，每个 Claude 都能全速工作，无需等待其他修改或处理合并冲突：

• 创建工作树：git worktree add ../project-feature-a feature-a。
• 在每个工作树中启动 Claude：cd ../project-feature-a && claude。
• 按需创建更多工作树（在新终端标签中重复步骤 1-2）。

实用技巧：

• 使用统一的命名规范。
• 每个工作树对应一个终端标签。
• 若使用 macOS 的 iTerm2，可设置 Claude 需要关注时的通知。
• 为不同工作树打开独立的 IDE 窗口。
• 完成后清理：git worktree remove ../project-feature-a。

6.4 结合自定义工具使用无头模式

claude -p（无头模式）可将 Claude Code 以编程方式集成到更大的工作流中，同时利用其内置工具和系统提示词。无头模式的两种主要使用模式：

1. 扇出模式（处理大规模迁移或分析）

适用于分析数百条日志的情感倾向、处理数千个 CSV 文件等场景：

• 让 Claude 编写脚本生成任务列表。例如，生成需从框架 A 迁移到框架 B 的 2000 个文件列表。
• 循环处理任务，通过编程方式为每个任务调用 Claude 并提供相关工具。例如：claude -p “将 foo.py 从 React 迁移到 Vue。完成后必须返回字符串 OK（成功）或 FAIL（失败）。” –allowedTools Edit Bash(git commit:*)。
• 多次运行脚本并优化提示词，直至获得理想结果。

2. 流水线模式（集成到现有数据 / 处理流水线）

通过 claude -p “<你的提示词>” –json | your_command 调用，其中 your_command 是处理流水线的下一步操作。

JSON 输出（可选）能提供结构化数据，便于自动化处理。

对于这两种场景，使用 –verbose 参数可调试 Claude 调用过程。建议在生产环境中关闭该模式以获得更简洁的输出。

你在使用 Claude Code 时有哪些技巧和最佳实践？欢迎标记 @AnthropicAI，让我们看到你的创造！

鸣谢

本文作者为 Boris Cherny。内容借鉴了广大 Claude Code 用户社区的最佳实践，他们富有创意的使用方式和工作流持续为我们带来启发。特别感谢 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 以及其他多位 Anthropic 工程师，他们的宝贵见解和实践经验为这些建议的形成奠定了基础。