Claude Code 最佳实践

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

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

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

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

本指南涵盖了在 Anthropic 内部团队以及在各种代码库、语言和环境中的工程师使用 Claude Code 时已被证明有效的模式。有关智能体循环如何在底层工作的信息，请参阅 Claude Code 如何工作。

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

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

这很重要，因为 LLM 性能会随着上下文填充而下降。当上下文窗口即将满时，Claude 可能开始"遗忘"之前的指令或犯更多错误。上下文窗口是最重要的资源。要了解会话在实践中如何填充，请观看关于启动时加载什么以及每次文件读取成本的交互式演练。使用自定义状态行持续跟踪上下文使用情况，并参阅减少 Token 用量了解减少 Token 用量的策略。

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

Claude 在工作看起来完成时就会停止。如果没有可以运行的检查，"看起来完成"就是唯一的可用信号，你就成了验证循环：每个错误都等着你发现。给 Claude 一个能产生通过或失败结果的东西，循环就会自动关闭。Claude 完成工作，运行检查，读取结果，并迭代直到检查通过。

这个检查可以是任何能在对话中返回 Claude 可以读取的信号的东西：测试套件、构建退出码、linter、将输出与固定装置对比的脚本，或与设计对比的浏览器截图。

一旦检查存在，决定它如何严格地控制停止：

• 在一条提示中：要求 Claude 在同一条消息中运行检查并迭代，如上表所示。
• 跨会话：将检查设置为 /goal 条件。一个单独的评估器在每次轮次后重新检查它，Claude 会持续工作直到满足条件。
• 作为确定性关卡：一个 Stop 钩子 将你的检查作为脚本运行，并在通过之前阻止轮次结束。Claude Code 在 8 次连续阻塞后会覆盖钩子并结束轮次。
• 通过第二意见：一个验证子代理或一个检查自身发现的动态工作流，让一个全新的模型尝试反驳结果，这样执行工作的代理不是给它打分的代理。

每一步都在用设置换取注意力。提示版本适用于今天的任何任务。/goal 和 Stop 钩子版本是让无人值守运行正确完成的条件。

让 Claude 展示证据而非断言成功：测试输出、它运行的命令及其返回结果，或结果的截图。审阅证据比你自己重新运行验证更快，而且适用于你没盯着的会话。

先探索，再计划，再编码

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

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

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

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

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

commit with a descriptive message and open a PR

在提示中提供具体上下文

Claude 可以推断意图，但它无法读心。引用特定文件，提及约束，并指向示例模式。

模糊的提示在你正在探索且可以承受修正时很有用。像 "这个文件有什么可以改进的？" 这样的提示可以引出你不会想到要问的东西。

提供丰富的内容

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

• 用 @ 引用文件，而不是描述代码在哪里。Claude 会在回复前读取文件。
• 直接粘贴图像。复制/粘贴或拖放图像到提示中。
• 给出 URL 用于文档和 API 参考。使用 /permissions 将常用域名加入允许列表。
• 通过管道输入数据，运行 cat error.log | claude 直接发送文件内容。
• 让 Claude 自行获取所需内容。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来拉取上下文。

配置你的环境

几个设置步骤可以让 Claude Code 在所有会话中显著更有效。有关扩展功能及其使用场景的全面概述，请参阅扩展 Claude Code。

编写有效的 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 尽管有规则禁止但仍持续做你不想要的事情，文件可能太长，规则被淹没了。如果 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 文件

配置权限

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

• 自动模式：一个单独的分类器模型审阅命令，只阻止看起来有风险的东西：范围升级、未知基础设施或敌对内容驱动的操作。最适合你信任任务的大方向但不想点击每一步时
• 权限允许列表：允许你已知安全的特定工具，如 npm run lint 或 git commit
• 沙盒：启用限制文件系统和网络访问的操作系统级隔离，让 Claude 在定义好的边界内更自由地工作

阅读更多关于权限模式、权限规则和沙盒的信息。

使用 CLI 工具

CLI 工具是与外部服务交互最高效上下文的方式。如果你使用 GitHub，安装 gh CLI。Claude 知道如何使用它来创建 issue、打开 PR 和读取评论。没有 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 服务器

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

设置钩子

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

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

创建技能

技能用特定于你项目、团队或领域的信息扩展 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。

创建自定义子代理

子代理在自己的上下文中运行，拥有自己允许的工具集。它们适用于读取大量文件或需要专业专注而不 clutter 你主对话的任务。

---
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 使用子代理："Use a subagent to review this code for security issues."

安装插件

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

有关在技能、子代理、钩子和 MCP 之间选择的指导，请参阅扩展 Claude Code。

有效沟通

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

询问代码库问题

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

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

以这种方式使用 Claude Code 是一种有效的入职工作流，可以缩短上手时间并减少对其他工程师的负载。无需特殊提示：直接提问。

让 Claude 采访你

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 偶尔会在第一次尝试时就完美解决问题，但快速纠正通常能产生更好更快的解决方案。

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

如果你在一个会话中就同一问题纠正了 Claude 超过两次，上下文已经充满了失败的方法。运行 /clear 并用一个更具体的提示重新开始，纳入你学到的东西。一个带有更好提示的干净会话，几乎总是优于一个积累了修正的长会话。

积极地管理上下文

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

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

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

使用子代理进行调查

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

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

子代理探索代码库，读取相关文件，并报告发现，所有这些都不会 clutter 你的主对话。

你也可以在 Claude 实现某些东西后使用子代理进行验证：

use a subagent to review this code for edge cases

使用检查点回退

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

与其仔细规划每一步，你可以告诉 Claude 尝试一些有风险的东西。如果不行，回退并尝试不同的方法。检查点跨会话持久化，因此你可以关闭终端，稍后仍然可以回退。

恢复对话

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

自动化和扩展

一旦你有效地使用一个 Claude，通过并行会话、非交互模式和扇出模式来倍增你的产出。

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

运行非交互模式

使用 claude -p "your prompt"，你可以非交互地运行 Claude，无需会话。非交互模式是你将 Claude 集成到 CI 流水线、pre-commit 钩子或任何自动化工作流的方式。输出格式让你可以程序化解析结果：纯文本、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 --verbose

运行多个 Claude 会话

选择适合你想要的协调量的并行方法：

• Worktrees：在隔离的 git 检出中运行单独的 CLI 会话，这样编辑不会冲突
• 桌面应用：直观地管理多个本地会话，每个会话在自己的 worktree 中
• Web 上的 Claude Code：在 Anthropic 管理的云基础设施上的隔离 VM 中运行会话
• 代理团队：多个会话的自动协调，共享任务、消息传递和团队负责人

除了并行化工作，多个会话还支持以质量为中心的工作流。全新的上下文可以改善代码审阅，因为 Claude 不会偏向它刚写的代码。

例如，使用编写者/审阅者模式：

你可以用测试做类似的事情：让一个 Claude 编写测试，然后另一个编写代码来通过它们。

跨文件扇出

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

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

你也可以将 Claude 集成到现有的数据/处理流水线中：

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

在开发期间使用 --verbose 进行调试，在生产环境中关闭它。

使用自动模式自主运行

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

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

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

添加对抗性审阅步骤

Claude 无人值守工作的时间越长，在将工作视为完成之前进行独立检查就越重要。一个在全新的子代理上下文中运行的审阅者只看到差异和你给它的标准，而不是产生变更的推理，因此它以自己的标准评估结果。

对于正确性检查，运行捆绑的 /code-review 技能，它在全新的子代理中审阅当前差异以查找 bug，并将发现返回给会话。要根据你的计划检查差异，自己编写审阅提示。命名要检查的工作、要对照检查的计划，以及什么算作发现：

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

由于审阅者作为子代理运行，实现会话直接收到差距并可以修复它们并重新审阅，无需你在窗口之间复制发现。对于更长的自主运行，一个代理团队可以在许多任务中保持这个循环，而你抽查记录的发现。

避免常见的失败模式

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

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

  修复：在无关任务之间使用 /clear。

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

  修复：两次失败的纠正后，使用 /clear 并写一个更好的初始提示，纳入你学到的东西。

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

  修复：无情地修剪。如果 Claude 没有指令也能正确做某事，删除它或将其转换为钩子。

• 信任-验证差距。 Claude 产生了一个看起来合理的实现，但不处理边界情况。

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

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

  修复： narrowly 限定调查范围，或使用子代理，这样探索不会消耗你的主上下文。

培养你的直觉

本指南中的模式不是一成不变的。它们是通常有效的起点，但可能不适用于每种情况。

有时你应该让上下文积累，因为你深入一个复杂的问题，历史是有价值的。有时你应该跳过计划，让 Claude 自己搞清楚，因为任务是探索性的。有时一个模糊的提示正是你需要的，因为你想看看 Claude 如何解释问题，然后再约束它。

注意什么有效。当 Claude 产生出色的输出时，注意你做了什么：提示结构、你提供的上下文、你所在的模式。当 Claude 挣扎时，问问为什么。上下文太嘈杂了吗？提示太模糊了吗？任务对于一次通过来说太大了吗？

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

相关资源

• Claude Code 如何工作：智能体循环、工具和上下文管理
• 扩展 Claude Code：技能、钩子、MCP、子代理和插件
• 常见工作流：调试、测试、PR 等的逐步方案
• CLAUDE.md：存储项目约定和持久上下文