Claude Code 最佳实践

从配置环境到跨并行会话扩展的技巧和模式，帮助你充分利用 Claude Code。

Claude Code 是一个 Agent 编码环境。与回答问题并等待的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、进行更改，并在你观看、重定向或完全离开时自主地解决问题。

这改变了你的工作方式。不是自己编写代码并让 Claude 审查，而是描述你想要什么，让 Claude 想办法构建它。Claude 探索、规划和实现。

但这种自主性仍然有学习曲线。Claude 在某些约束下工作，你需要理解这些约束。

本指南涵盖了在 Anthropic 内部团队和使用 Claude Code 的各种代码库、语言和环境中被证明有效的模式。关于 Agent 循环在底层如何工作的详细信息，请参阅 Claude Code 的工作原理。

---

大多数最佳实践基于一个约束：Claude 的上下文窗口填满得很快，随着填满性能会下降。

Claude 的上下文窗口包含你的整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。然而，这可能很快填满。一次调试会话或代码库探索可能生成和消耗数万个 Token。

这很重要，因为 LLM 的性能随着上下文填满而下降。当上下文窗口快满时，Claude 可能开始"忘记"早期指令或犯更多错误。上下文窗口是需要管理的最重要资源。要查看会话在实践中如何填满，观看交互式演示，了解启动时加载的内容和每个文件读取的成本。使用自定义状态行持续跟踪上下文使用情况，并查看减少 Token 使用了解减少 Token 使用的策略。

---

给 Claude 一种验证其工作的方式

包含测试、截图或预期输出，让 Claude 可以自我检查。这是你能做的最高杠杆的事情。

当 Claude 可以验证自己的工作时，表现会显著提升，例如运行测试、比较截图和验证输出。

没有明确的成功标准，它可能产生看起来正确但实际上不工作的东西。你成为唯一的反馈循环，每个错误都需要你的关注。

策略	之前	之后
提供验证标准	"实现一个验证电子邮件地址的函数"	"编写一个 validateEmail 函数。测试用例：user@example.com 为 true，invalid 为 false，user@.com 为 false。实现后运行测试"
可视化验证 UI 更改	"让仪表盘更好看"	"[粘贴截图] 实现这个设计。对结果截图并与原图比较。列出差异并修复"
解决根本原因，而非症状	"构建失败了"	"构建失败，错误为：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要压制错误"

UI 更改可以使用 Chrome 中的 Claude 扩展进行验证。它在浏览器中打开新标签页，测试 UI，并迭代直到代码工作。

你的验证也可以是测试套件、linter 或检查输出的 Bash 命令。投入精力使你的验证坚如磐石。

---

先探索，再规划，然后编码

将研究和规划与实现分开，以避免解决错误的问题。

让 Claude 直接跳到编码可能产生解决错误问题的代码。使用计划模式将探索与执行分开。

推荐的工作流有四个阶段：

1. 探索：进入计划模式。Claude 读取文件并回答问题，不做更改。

   read /src/auth and understand how we handle sessions and login.
   also look at how we manage environment variables for secrets.

2. 规划：要求 Claude 创建详细的实现计划。

   I want to add Google OAuth. What files need to change?
   What's the session flow? Create a plan.

   按 Ctrl+G 在文本编辑器中打开计划，在 Claude 继续之前直接编辑。

3. 实现：退出计划模式，让 Claude 编码，根据计划验证。

   implement the OAuth flow from your plan. write tests for the
   callback handler, run the test suite and fix any failures.

4. 提交：要求 Claude 提交并附上描述性消息，创建 PR。

   commit with a descriptive message and open a PR

计划模式很有用，但也会增加开销。对于范围明确且修复较小的任务（如修复拼写错误、添加日志行或重命名变量），直接让 Claude 做。当你不确定方法时、更改涉及多个文件时、或你不熟悉被修改的代码时，规划最有用。如果你能用一句话描述差异，就跳过计划。

---

在提示中提供具体上下文

指令越精确，需要的纠正就越少。

Claude 可以推断意图，但不能读心。引用具体文件、提及约束，并指向示例模式。

策略	之前	之后
限定任务范围。 指定文件、场景和测试偏好。	"为 foo.py 添加测试"	"为 foo.py 编写测试，覆盖用户登出的边缘情况。避免使用 mock。"
指向来源。 将 Claude 引导到可以回答问题的来源。	"为什么 ExecutionFactory 的 API 这么奇怪？"	"查看 ExecutionFactory 的 git 历史，总结它的 API 是如何形成的"
引用现有模式。 将 Claude 指向代码库中的模式。	"添加日历组件"	"查看主页上现有组件的实现方式以了解模式。HotDogWidget.php 是一个好例子。遵循模式实现一个新的日历组件，让用户选择月份并前后翻页选择年份。从头构建，不使用代码库中已有库之外的库。"
描述症状。 提供症状、可能的位置和"修复"的样貌。	"修复登录 bug"	"用户报告会话超时后登录失败。检查 src/auth/ 中的认证流程，特别是 token 刷新。编写一个重现问题的失败测试，然后修复"

模糊的提示在你探索且有时间调整方向时很有用。像 "what would you improve in this file?" 这样的提示可以浮现出你想不到要问的东西。

提供丰富内容

使用 @ 引用文件，粘贴截图/图片，或直接管道传入数据。

你可以通过多种方式向 Claude 提供丰富数据：

• 使用 @ 引用文件而非描述代码位置。Claude 在回复前读取文件。
• 直接粘贴图片。复制/粘贴或拖放图片到提示中。
• 提供文档和 API 参考的 URL。使用 /permissions 将常用域名加入白名单。
• 管道传入数据，运行 cat error.log | claude 直接发送文件内容。
• 让 Claude 获取所需内容。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件自行拉取上下文。

---

配置你的环境

几个设置步骤可以使 Claude Code 在所有会话中显著更有效。有关扩展功能的完整概述及使用时机，请参阅扩展 Claude Code。

编写有效的 CLAUDE.md

运行 /init 基于当前项目结构生成初始 CLAUDE.md 文件，然后随时间完善。

CLAUDE.md 是 Claude 在每次对话开始时读取的特殊文件。包含 Bash 命令、代码风格和工作流规则。这为 Claude 提供了仅从代码无法推断的持久上下文。

/init 命令分析你的代码库以检测构建系统、测试框架和代码模式，为你提供完善的基础。

CLAUDE.md 文件没有必需的格式，但要保持简短且人类可读。例如：

# 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 按需加载它们，不会膨胀每个对话。

保持简洁。对于每一行，问："删除这个会导致 Claude 犯错吗？" 如果不会，就删掉。臃肿的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令！

包含	排除
Claude 无法猜到的 Bash 命令	Claude 通过读代码就能弄清楚的任何东西
与默认不同的代码风格规则	Claude 已经知道的标准语言规范
测试指令和首选测试运行器	详细的 API 文档（改为链接到文档）
仓库规范（分支命名、PR 约定）	频繁变化的信息
项目特定的架构决策	长篇解释或教程
开发环境特殊要求（必需的环境变量）	代码库的逐文件描述
常见陷阱或非显而易见的行为	不言自明的做法如"写干净的代码"

如果 Claude 尽管有规则但仍然做你不想要的事，文件可能太长了，规则被淹没了。如果 Claude 问你 CLAUDE.md 中已回答的问题，措辞可能有歧义。把 CLAUDE.md 当代码对待：出错时审查，定期精简，通过观察 Claude 行为是否实际改变来测试更改。

你可以通过添加强调（例如"IMPORTANT"或"YOU MUST"）来调整指令以提高遵循度。将 CLAUDE.md 提交到 git，以便团队贡献。文件的价值会随时间复合增长。

CLAUDE.md 文件可以使用 @path/to/import 语法导入额外文件：

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

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

• 主文件夹（~/.claude/CLAUDE.md）：适用于所有 Claude 会话
• 项目根目录（./CLAUDE.md）：提交到 git 与团队共享
• 项目根目录（./CLAUDE.local.md）：个人项目特定笔记；将此文件添加到 .gitignore 以便不与团队共享
• 父目录：适用于 monorepo，root/CLAUDE.md 和 root/foo/CLAUDE.md 会自动拉入
• 子目录：Claude 在处理子目录中的文件时按需拉入子 CLAUDE.md 文件

配置权限

使用自动模式让分类器处理批准，/permissions 将特定命令加入白名单，或 /sandbox 进行操作系统级隔离。每种方式都能减少中断，同时保持你的控制。

默认情况下，Claude Code 会为可能修改系统的操作请求许可：文件写入、Bash 命令、MCP 工具等。这是安全的但很繁琐。第十次批准后你不再真正审查，只是在点击通过。有三种方式减少这些中断：

• 自动模式：独立的分类器模型审查命令，只阻止看起来有风险的操作：范围升级、未知基础设施或恶意内容驱动的操作。最适合你信任任务大方向但不想逐步点击通过的情况
• 权限白名单：允许你知道安全的特定工具，如 npm run lint 或 git commit
• 沙箱：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

了解更多关于权限模式、权限规则和沙箱。

使用 CLI 工具

告诉 Claude Code 在与外部服务交互时使用 gh、aws、gcloud 和 sentry-cli 等 CLI 工具。

CLI 工具是与外部服务交互的最节省上下文的方式。如果你使用 GitHub，安装 gh CLI。Claude 知道如何用它来创建 issue、打开拉取请求和读取评论。没有 gh，Claude 仍可使用 GitHub API，但未认证的请求通常会遇到速率限制。

Claude 也善于学习它还不了解的 CLI 工具。尝试这样的提示：Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

连接 MCP 服务器

运行 claude mcp add 连接 Notion、Figma 或数据库等外部工具。

通过 MCP 服务器，你可以让 Claude 从 issue 跟踪器实现功能、查询数据库、分析监控数据、集成 Figma 设计以及自动化工作流。

设置 Hook

使用 Hook 来处理必须每次都发生、零例外的操作。

Hook 在 Claude 工作流的特定点自动运行脚本。与建议性的 CLAUDE.md 指令不同，Hook 是确定性的，保证操作会发生。

Claude 可以为你编写 Hook。尝试这样的提示："Write a hook that runs eslint after every file edit" 或 "Write a hook that blocks writes to the migrations folder." 直接编辑 .claude/settings.json 来手动配置 Hook，运行 /hooks 浏览已配置的内容。

创建技能

在 .claude/skills/ 中创建 SKILL.md 文件，为 Claude 提供领域知识和可复用工作流。

技能通过项目、团队或领域的特定信息扩展 Claude 的知识。Claude 在相关时自动应用它们，或者你可以直接用 /skill-name 调用。

通过在 .claude/skills/ 中添加包含 SKILL.md 的目录来创建技能：

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

技能也可以定义你直接调用的可重复工作流：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

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

运行 /fix-issue 1234 来调用。对于有副作用的工作流，使用 disable-model-invocation: true 以手动触发。

创建自定义子 Agent

在 .claude/agents/ 中定义专门的助手，Claude 可以委托给它们处理隔离的任务。

子 Agent在自己的上下文中运行，拥有一组自己的允许工具。它们适用于读取许多文件或需要专门关注而不混乱主对话的任务。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

明确告诉 Claude 使用子 Agent："Use a subagent to review this code for security issues."

安装插件

运行 /plugin 浏览市场。插件无需配置即可添加技能、工具和集成。

插件将技能、Hook、子 Agent 和 MCP 服务器捆绑成一个可安装单元，来自社区和 Anthropic。如果你使用类型化语言，安装代码智能插件为 Claude 提供精确的符号导航和编辑后的自动错误检测。

有关在技能、子 Agent、Hook 和 MCP 之间选择的指南，请参阅扩展 Claude Code。

---

有效沟通

你与 Claude Code 沟通的方式显著影响结果质量。

提问代码库问题

向 Claude 提问你会问高级工程师的问题。

入职新代码库时，使用 Claude Code 进行学习和探索。你可以向 Claude 提问你向其他工程师提问的同类问题：

• 日志是如何工作的？
• 如何创建新的 API 端点？
• foo.rs 第 134 行的 async move { ... } 做了什么？
• CustomerOnboardingFlowImpl 处理了哪些边缘情况？
• 为什么这段代码在第 333 行调用 foo() 而不是 bar()？

以这种方式使用 Claude Code 是一种有效的入职工作流，加快上手速度并减少其他工程师的负担。无需特殊提示：直接提问。

让 Claude 采访你

对于较大的功能，先让 Claude 采访你。从最小提示开始，让 Claude 使用 AskUserQuestion 工具采访你。

Claude 会问你可能还没想到的事情，包括技术实现、UI/UX、边缘情况和权衡。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

规范完成后，启动新会话来执行。新会话有干净的上下文，完全专注于实现，你有书面规范可以参考。

---

管理会话

对话是持久且可逆的。利用这一点！

尽早且经常纠正方向

一旦发现 Claude 偏离轨道就纠正它。

最好的结果来自紧密的反馈循环。虽然 Claude 偶尔第一次就完美解决问题，但快速纠正通常能更快产生更好的解决方案。

• Esc：按 Esc 键在 Claude 操作中途停止。上下文保留，你可以重定向。
• Esc + Esc 或 /rewind：按两次 Esc 或运行 /rewind 打开回退菜单，恢复之前的对话和代码状态，或从选定消息总结。
• "Undo that"：让 Claude 撤销更改。
• /clear：在不相关任务之间重置上下文。包含不相关信息的长会话会降低性能。

如果在同一会话中对同一问题纠正 Claude 超过两次，上下文已被失败方法污染。运行 /clear 并用包含你所学的更具体提示重新开始。干净会话加更好的提示几乎总是胜过积累纠正的长会话。

积极管理上下文

在不相关任务之间运行 /clear 重置上下文。

Claude Code 在接近上下文限制时自动压缩对话历史，保留重要代码和决策同时释放空间。

在长会话中，Claude 的上下文窗口可能充满无关对话、文件内容和命令。这会降低性能，有时会分散 Claude 的注意力。

• 在任务之间频繁使用 /clear 完全重置上下文窗口
• 当自动压缩触发时，Claude 总结最重要的内容，包括代码模式、文件状态和关键决策
• 要更多控制，运行 /compact <instructions>，如 /compact Focus on the API changes
• 要只压缩部分对话，使用 Esc + Esc 或 /rewind，选择消息检查点，选择从此处总结或总结到此处。前者从该点向前压缩消息同时保持早期上下文完整；后者压缩早期消息同时保持最近消息完整。查看恢复 vs 总结
• 在 CLAUDE.md 中自定义压缩行为，添加如 "When compacting, always preserve the full list of modified files and any test commands" 的指令，确保关键上下文在总结中存活
• 对于不需要留在上下文中的快速问题，使用 /btw。答案出现在可关闭的叠加层中，永远不会进入对话历史，这样你可以在不增长上下文的情况下查看细节

使用子 Agent 进行调查

用 "use subagents to investigate X" 委托研究。它们在单独的上下文中探索，保持主对话干净用于实现。

由于上下文是根本约束，子 Agent 是最强大的工具之一。当 Claude 研究代码库时，它读取大量文件，所有这些都消耗你的上下文。子 Agent 在单独的上下文窗口中运行并报告摘要：

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

子 Agent 探索代码库，读取相关文件并报告发现，完全不会混乱你的主对话。

你也可以在 Claude 实现后使用子 Agent 进行验证：

use a subagent to review this code for edge cases

使用检查点回退

你发送的每个提示都创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。

Claude 在每次更改前自动快照文件，以便检查点可以恢复它们。双击 Escape 或运行 /rewind 打开回退菜单。你可以仅恢复对话、仅恢复代码、两者都恢复，或从选定消息总结。详见检查点。

你可以让 Claude 尝试有风险的事情。如果不行，回退尝试不同方法。检查点跨会话持久，所以你可以关闭终端稍后仍然回退。

检查点只跟踪 Claude 做的更改，不跟踪外部进程。这不是 git 的替代品。

恢复对话

用 /rename 命名会话，像分支一样对待：每个工作流都有自己的持久上下文。

Claude Code 在本地保存对话，因此当任务跨越多个时间段时，你不必重新解释上下文。运行 claude --continue 接续最近的会话，或 claude --resume 从列表中选择。给会话起描述性名称如 oauth-migration 以便稍后找到。查看管理会话了解恢复、分支和命名控制的完整集合。

---

自动化和扩展

一旦你在一个 Claude 上有效，可以通过并行会话、非交互模式和扇出模式来倍增产出。

到目前为止的一切都假设一个人、一个 Claude 和一个对话。但 Claude Code 水平扩展。本节中的技术展示如何完成更多工作。

运行非交互模式

在 CI、pre-commit hook 或脚本中使用 claude -p "prompt"。添加 --output-format stream-json 获得流式 JSON 输出。

通过 claude -p "your prompt"，你可以非交互地运行 Claude，无需会话。非交互模式是你将 Claude 集成到 CI 管道、pre-commit hook 或任何自动化工作流的方式。输出格式让你以编程方式解析结果：纯文本、JSON 或流式 JSON。

# 一次性查询
claude -p "Explain what this project does"

# 脚本的结构化输出
claude -p "List all API endpoints" --output-format json

# 实时处理的流式输出
claude -p "Analyze this log file" --output-format stream-json

运行多个 Claude 会话

并行运行多个 Claude 会话以加速开发、运行隔离实验或启动复杂工作流。

选择适合你想要多少协调工作的并行方法：

• Worktrees：在隔离的 git 检出中运行单独的 CLI 会话，使编辑不会冲突
• 桌面应用：可视化管理多个本地会话，每个在自己的 worktree 中
• Claude Code 网页版：在 Anthropic 管理的云基础设施上的隔离 VM 中运行会话
• Agent 团队：自动化协调多个会话，共享任务、消息和团队领导

除了并行化工作，多个会话还能实现质量导向的工作流。干净的上下文改善代码审查，因为 Claude 不会偏向它刚写的代码。

例如，使用 Writer/Reviewer 模式：

会话 A（Writer）	会话 B（Reviewer）
Implement a rate limiter for our API endpoints
	Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.
Here's the review feedback: [Session B output]. Address these issues.

你也可以对测试做类似的事情：让一个 Claude 写测试，另一个写代码通过它们。

跨文件扇出

循环任务调用 claude -p 处理每个文件。使用 --allowedTools 限定批量操作的权限。

对于大型迁移或分析，你可以将工作分配到多个并行的 Claude 调用中：

1. 生成任务列表：让 Claude 列出所有需要迁移的文件（例如 list all 2,000 Python files that need migrating）

2. 编写脚本循环处理列表：

   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

3. 在几个文件上测试，然后大规模运行：根据前 2-3 个文件出错的情况完善提示，然后在整个集合上运行。--allowedTools 标志限制 Claude 可以做的事情，这在无人值守运行时很重要。

你也可以将 Claude 集成到现有的数据/处理管道中：

claude -p "<your prompt>" --output-format json | your_command

开发时使用 --verbose 调试，生产中关闭。

使用自动模式自主运行

要获得不间断执行和后台安全检查，使用自动模式。分类器模型在命令运行前审查它们，阻止范围升级、未知基础设施和恶意内容驱动的操作，同时让常规工作无需提示即可进行。

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

对于带 -p 标志的非交互运行，如果分类器反复阻止操作，自动模式会中止，因为没有用户可以回退。查看自动模式何时回退了解阈值。

---

避免常见的失败模式

这些是常见错误。及早识别可以节省时间：

• 大杂烩会话。 你从一个任务开始，然后问 Claude 不相关的事情，然后回到第一个任务。上下文充满了不相关信息。

  修复：在不相关任务之间 /clear。

• 反复纠正。 Claude 做错了，你纠正它，它还是错的，你再纠正。上下文被失败方法污染。

  修复：两次纠正失败后，/clear 并用包含你所学的更好初始提示重新开始。

• 过度指定的 CLAUDE.md。 如果你的 CLAUDE.md 太长，Claude 会忽略一半，因为重要规则在噪音中丢失了。

  修复：无情精简。如果 Claude 没有指令也能正确做某事，删除它或转换为 Hook。

• 信任后验证的差距。 Claude 产生了看起来合理的实现但没有处理边缘情况。

  修复：始终提供验证（测试、脚本、截图）。如果你无法验证，就不要发布。

• 无限探索。 你让 Claude "调查"某事但不限定范围。Claude 读取数百个文件，填满上下文。

  修复：将调查范围收窄或使用子 Agent，这样探索不会消耗你的主上下文。

---

培养你的直觉

本指南中的模式不是一成不变的。它们是普遍有效的起点，但可能不是每种情况下的最优解。

有时你应该让上下文积累，因为你深入一个复杂问题，历史很有价值。有时你应该跳过规划，让 Claude 自己弄清楚，因为任务是探索性的。有时模糊提示恰好正确，因为你想在限制之前看看 Claude 如何解读问题。

注意什么有效。当 Claude 产出好的结果时，注意你做了什么：提示结构、你提供的上下文、你所在的模式。当 Claude 遇到困难时，问为什么。是上下文太嘈杂？提示太模糊？任务太大一次无法完成？

随着时间的推移，你会培养出任何指南都无法捕捉的直觉。你会知道何时具体、何时开放，何时规划、何时探索，何时清除上下文、何时让其积累。

相关资源

• Claude Code 的工作原理：Agent 循环、工具和上下文管理
• 扩展 Claude Code：技能、Hook、MCP、子 Agent 和插件
• 常见工作流：调试、测试、PR 等的分步指南
• CLAUDE.md：存储项目约定和持久上下文