Press "Enter" to skip to content

精通 Claude Code：代理式编码的最佳实践

Published 2025年8月2日 by admin

本文是对 Anthropic 官方教程 Claude Code: Best practices for agentic coding (原文发布于 2025 年 4 月 18 日) 的翻译与总结，旨在帮助开发者更好地利用 Claude Code 这一强大的代理式编码工具，并作为个人的学习笔记。

引言

Claude Code 是 Anthropic 推出的一款用于代理式编码 (agentic coding) 的命令行工具。作为一个研究项目，它为 Anthropic 的工程师和研究人员提供了一种更原生的方式，将 Claude 集成到他们的编码工作流中。

Claude Code 的设计理念是底层、无固定范式 (low-level and unopinionated)，提供近乎原始的模型访问能力，而不强制用户遵循特定的工作流程。这使得它成为一个灵活、可定制、可编写脚本且安全的强大工具。然而，这种灵活性也给初次接触代理式编码工具的工程师带来了一定的学习曲线。

本文旨在分享一些在 Anthropic 内部团队和外部开发者中被证明行之有效的通用模式和技巧。请将这些建议视为起点，并鼓励你亲自尝试，找到最适合自己的方法！

想了解更多？ 请访问官方文档 claude.ai/code，获取更详细的功能介绍、示例和高级技巧。

1. 自定义你的设置

Claude Code 会自动将上下文信息整合到提示中。这个过程会消耗时间和 Token，但你可以通过调整环境来优化它。

a. 创建 CLAUDE.md 文件

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

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

CLAUDE.md 没有固定的格式要求，建议保持其简洁和人类可读性。例如：

# Bash 命令
- npm run build: 构建项目
- npm run typecheck: 运行类型检查器

# 代码风格
- 使用 ES 模块 (import/export) 语法，而不是 CommonJS (require)
- 尽可能解构导入 (例如: import { foo } from 'bar')

# 工作流程
- 在完成一系列代码更改后，请务必进行类型检查
- 为了性能，优先运行单个测试，而不是整个测试套件

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

  • 仓库根目录（最常见）：命名为 CLAUDE.md 并提交到 Git，以便团队共享。如果想本地私有，可命名为 CLAUDE.local.md 并加入 .gitignore。
  • 任何父目录：这对于 monorepo 项目很有用。例如，你在 root/foo 目录下运行 claude，那么 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会被自动加载。
  • 任何子目录：当你处理子目录中的文件时，Claude 会按需加载这些子目录中的 CLAUDE.md。
  • 用户主目录 (~/.claude/CLAUDE.md)：适用于所有 claude 会话的全局配置。

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

b. 调优你的 CLAUDE.md 文件

CLAUDE.md 是提示（Prompt）的一部分，因此需要像优化常用提示一样对其进行迭代。一个常见的错误是添加大量内容却不验证其效果。花时间试验，看看哪些内容能让模型更好地遵循指令。

你可以手动编辑，也可以在对话中按 # 键，给 Claude 一个指令，它会自动将这条指令整合到相关的 CLAUDE.md 文件中。

提示：在 Anthropic，我们有时会使用“提示词改进器”来优化 CLAUDE.md，并通过添加 "IMPORTANT" 或 "YOU MUST" 等词来强调指令，以提高遵循度。
6961243cc6409e41ba93895faded4f4bc1772366-1600x1231

c. 管理 Claude 的工具白名单

默认情况下，Claude Code 对任何可能修改你系统的操作都会请求许可，如文件写入、bash 命令等。这种保守的设计是为了安全。你可以自定义白名单，允许你确认安全的工具，或允许易于撤销的潜在危险操作（如文件编辑、git commit）。

管理白名单有四种方式：

  1. 在会话中被询问时选择 "总是允许" (Always allow)。
  2. 使用 /permissions 命令添加或移除工具。例如，Edit 允许文件编辑，Bash(git commit:*) 允许 git commit。
  3. 手动编辑 .claude/settings.json 或 ~/.claude.json 文件。
  4. 使用 --allowedTools 命令行标志进行会话级别的权限设置。

d. 如果使用 GitHub，请安装 gh CLI

Claude 知道如何使用 gh CLI 与 GitHub 交互，例如创建 issue、发起 PR、读取评论等。

2. 为 Claude 提供更多工具

Claude 可以使用你 shell 环境中的工具，也可以通过 MCP (Multi-Claude Protocol) 和 REST API 使用更复杂的工具。

a. 结合使用 bash 工具

Claude 继承了你的 bash 环境，但对于你的自定义工具，你需要通过以下方式告诉它如何使用：

  • 直接告知工具名称和用法示例。
  • 让 Claude 运行 --help 查看工具文档。
  • 在 CLAUDE.md 中记录常用工具。

b. 结合使用 MCP

Claude Code 既是 MCP 服务器也是客户端，可以连接到任意数量的 MCP 服务器来访问它们的工具。

c. 使用自定义斜杠命令

对于重复性工作流（如调试循环、日志分析），你可以将提示模板存储在 .claude/commands 文件夹的 Markdown 文件中。这些模板将通过 / 菜单作为斜杠命令可用。

例如，创建一个 fix-github-issue.md 文件来自动修复 GitHub issue：

请分析并修复 GitHub issue: $ARGUMENTS.

遵循以下步骤:

1. 使用 `gh issue view` 获取 issue 详情
2. 理解 issue 中描述的问题
3. 在代码库中搜索相关文件
4. 实现必要的代码更改以修复问题
5. 编写并运行测试以验证修复
6. 确保代码通过 lint 和类型检查
7. 创建一个描述性的 commit message
8. 推送代码并创建一个 PR

记住，所有 GitHub 相关任务都使用 GitHub CLI (`gh`)。

将上述内容保存到 .claude/commands/fix-github-issue.md 后，你就可以在 Claude Code 中使用 /project:fix-github-issue 1234 来让 Claude 修复编号为 1234 的 issue。

3. 尝试常见的工作流

Claude Code 不强制特定工作流，以下是一些社区中涌现出的成功模式：

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

这是一个适用于许多问题的通用流程：

  1. 探索：让 Claude 阅读相关文件、图片或 URL，但明确告诉它先不要写代码。在这个阶段，可以鼓励 Claude 使用子代理（subagents）来调查具体问题。
  2. 规划：让 Claude 制定解决问题的计划。建议使用 "think"（思考）来触发扩展思考模式，它会给予 Claude 更多的计算时间来评估方案。思考预算级别依次为: "think" < "think hard" < "think harder" < "ultrathink"。
  3. 编码：让 Claude 根据计划实现代码。
  4. 提交：让 Claude 提交结果、创建 PR，并更新相关的 README 或 changelog。

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

这是 Anthropic 内部最推崇的 TDD (测试驱动开发) 流程：

  1. 编写测试：让 Claude 基于预期的输入/输出编写测试用例。明确告知它这是 TDD，避免它创建模拟实现。
  2. 运行并确认失败：让 Claude 运行测试，确认它们会失败。
  3. 提交测试：对测试满意后，提交它们。
  4. 编码以通过测试：指示 Claude 编写能通过测试的代码，并告诉它不要修改测试。它会进行几次“编码 -> 运行测试 -> 调整代码”的迭代。
  5. 提交代码：一旦对更改满意，就提交代码。

c. 编码、截图、迭代

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

  1. 为 Claude 提供截图能力（例如，通过 Puppeteer MCP 服务器或手动粘贴截图）。
  2. 通过粘贴或拖拽图片，为 Claude 提供一个视觉设计稿。
  3. 让 Claude 编码实现设计，截图比对，并迭代直到结果与设计稿匹配。
  4. 满意后提交代码。
    6ea59a36fe82c2b300bceaf3b880a4b4852c552d-1600x1143

d. 安全的 YOLO 模式

使用 claude --dangerously-skip-permissions 可以跳过所有权限检查，让 Claude 不间断地工作直到完成。这非常适合修复 lint 错误或生成样板代码等任务。

⚠️ 警告：让 Claude 运行任意命令是有风险的。为了降低风险，请在没有互联网访问的容器（如 Docker Dev Containers）中使用此模式。

e. 代码库问答 (Q&A)

在熟悉新代码库时，你可以像和同事结对编程一样向 Claude 提问。它能代理式地搜索代码库来回答问题，例如：

  • 日志系统是如何工作的？
  • 如何创建一个新的 API 端点？
  • foo.rs 文件第 134 行的 async move { ... } 是做什么的？
  • CustomerOnboardingFlowImpl 处理了哪些边界情况？

这已成为 Anthropic 新员工入职的核心流程，大大缩短了上手时间。
a08ea13c2359aac0eceacebf2e15f81e8e8ec8d2-1600x1278

f. 使用 Claude 与 Git/GitHub 交互

Claude 能高效地处理许多 Git 和 GitHub 操作：

  • Git：
    • 搜索 git 历史回答问题（例如，“v1.2.3 版本包含了哪些改动？”）。
    • 编写 commit messages。
    • 处理复杂操作，如文件恢复、解决 rebase 冲突等。
  • GitHub：
    • 创建 PR（它能理解 "pr" 这样的缩写）。
    • 根据 code review 的评论进行一次性修复。
    • 修复失败的 CI 构建或 linter 警告。
    • 对 open issues 进行分类和分流。

g. 使用 Claude 处理 Jupyter Notebooks

Claude 可以读写 Jupyter Notebooks，并能理解图表等输出，是探索和交互数据的快捷方式。一个推荐的工作流是在 VS Code 中并排打开 Claude Code 和 .ipynb 文件。你还可以让 Claude “美化”你的 notebook，使其在展示给同事时更具美感。

4. 优化你的工作流

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

a. 指令要具体

指令越具体，Claude 的成功率就越高。

差的指令 好的指令
为 foo.py 添加测试 为 foo.py 写一个新的测试用例，覆盖用户未登录的边界情况。避免使用 mock。
ExecutionFactory 的 API 为什么这么奇怪？ 查阅 ExecutionFactory 的 git 历史，总结其 API 是如何演变至今的。
添加一个日历组件 查看现有组件（如 HotDogWidget.php）的实现模式。然后，遵循该模式实现一个新的日历组件，允许用户选择月份并前后翻页选择年份。不要使用新库。

75e1b57a0b696e7aafeca1ed5fa6ba7c601a5953-1360x1126

b. 给 Claude 提供图片

通过粘贴、拖拽或提供文件路径，让 Claude 查看图片、图表或设计稿。这对于 UI 开发和数据分析非常有用。
7372868757dd17b6f2d3fef98d499d7991d89800-1450x1164

c. 提及你想让 Claude 查看或处理的文件

使用 Tab 键可以快速引用仓库中的任何文件或文件夹，帮助 Claude 准确定位。
e071de707f209bbaa7f16b593cc7ed0739875dae-1306x1088

d. 给 Claude 提供 URL

直接粘贴 URL，Claude 会抓取并阅读其内容。可以使用 /permissions 将常用域名加入白名单，避免重复授权。

e. 尽早且频繁地纠正路线

与其让 Claude 完全自主工作，不如成为一个积极的合作者。

  • 先规划后编码：要求 Claude 先出计划，你确认后再开始编码。
  • 按 Escape 中断：随时中断 Claude 的当前操作，然后给出新的指示。
  • 双击 Escape 编辑历史：返回并编辑之前的提示，从一个不同的方向重新探索。
  • 要求撤销：让 Claude 撤销之前的更改。

f. 使用 /clear 保持上下文清晰

在长会话中，上下文可能会被无关信息填满。在任务之间频繁使用 /clear 来重置上下文窗口。

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

对于多步骤的大型任务（如代码迁移、修复大量 lint 错误），可以让 Claude 使用一个 Markdown 文件作为清单和工作草稿纸。

h. 向 Claude 传递数据

有多种方式可以向 Claude 提供数据：

  • 直接复制粘贴到提示中。
  • 通过管道传入（如 cat foo.txt | claude）。
  • 让 Claude 通过工具（bash, MCP 等）拉取数据。
  • 让 Claude 读取文件或抓取 URL。

5. 使用无头模式 (Headless Mode) 实现自动化

无头模式专为非交互式环境设计，如 CI、pre-commit 钩子、构建脚本等。使用 -p 标志和提示来启用它。

claude -p "你的提示词" --output-format stream-json

应用场景：

  • Issue 分流：在 GitHub action 中触发，自动为新 issue 添加标签。
  • 作为 Linter：进行主观代码审查，发现传统 linter 无法检测的问题，如拼写错误、过时的注释、误导性的变量名等。

6. 通过多 Claude 工作流提升效率

一些最强大的应用场景涉及并行运行多个 Claude 实例。

a. 一个 Claude 写代码，另一个来验证

一个简单的模式是让一个 Claude 写代码，另一个来审查或测试。

  1. Claude A 写代码。
  2. 启动 Claude B（或在 A 中 /clear），审查 A 的工作。
  3. 启动 Claude C，阅读代码和审查反馈，并根据反馈修改代码。

b. 使用多个代码库副本

在不同文件夹中创建 3-4 个 git checkout，然后在每个文件夹中启动一个 Claude 实例处理不同任务，循环检查进度。

c. 使用 git worktrees

这是一个比多个副本更轻量级的替代方案。git worktree 允许你从同一个仓库中将多个分支检出到不同目录。这样，你就可以在不同的 worktree 中同时运行多个 Claude 会话，处理独立任务。

d. 使用无头模式和自定义工具链

claude -p 可以将 Claude Code 编程式地集成到大型工作流中。主要有两种模式：

  1. 扇出 (Fanning out)：处理大规模迁移或分析。例如，编写一个脚本，循环调用 claude -p "将 foo.py 从 React 迁移到 Vue..." 来处理数千个文件。
  2. 管道 (Pipelining)：将 Claude 集成到现有的数据处理管道中。例如：claude -p "<你的提示>" --json | your_next_command。

博客总结

这篇官方指南为我们展示了 Claude Code 的巨大潜力。总结起来，核心的最佳实践可以归纳为以下几点：

  1. 上下文是王道：通过 CLAUDE.md、文件、URL 和图像，为 Claude 提供丰富、准确的上下文是成功的关键。
  2. 视 Claude 为协作者：不要把它当作一个简单的命令执行器。通过“规划-执行-反馈”的循环，与它积极互动、迭代和纠正，才能获得最佳结果。
  3. 善用工具生态：充分利用 Claude 对 shell、gh CLI、MCP 和自定义命令的支持，可以极大地扩展其能力边界。
  4. 结构化工作流更有效：采用 TDD、先规划后编码等结构化方法，能引导 Claude 产出更可靠、更高质量的代码。
  5. 自动化与规模化：通过无头模式和多 Claude 实例，可以将代理式编码的能力从单点任务扩展到大规模的自动化流程中。

希望这篇笔记能帮助你更好地在日常开发中运用 Claude Code，提升编码效率和体验。

Published in 计算机

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注