Claude Code 最佳实践¶

从环境配置到并行扩展，帮你更高效地使用 Claude Code 的技巧和模式。

Claude Code 是一个 Agentic 编码环境，它改变了你的工作方式。 与回答问题后等待的聊天机器人不同，Claude Code 能读取文件、运行命令、做出修改，并在你观察、引导或离开时自主解决问题。

这意味着你不再亲自写代码再让 Claude 审核，而是描述你想要什么，由 Claude 来探索、规划和实现。但这种自主性仍有学习曲线——Claude 在某些约束条件下工作，你需要理解这些约束。

本指南涵盖了 Anthropic 内部团队和各种工程师在不同代码库、语言和环境中证明有效的模式。

绝大多数最佳实践基于一个核心约束：Claude 的上下文窗口会快速填满，且性能随之下降。

Claude 的上下文窗口容纳你的整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。一次调试或代码库探索可能产生数万 token。

当上下文窗口接近满载时，Claude 可能开始"遗忘"早期指令或犯更多错误。上下文窗口是你需要管理的最重要资源。

给 Claude 一个验证机制¶

给 Claude 一个能执行的检查——测试、构建、截图对比——这决定了你能否放心离开。

Claude 在工作"看起来完成"时停止。没有可执行的检查，"看起来完成"就是唯一信号，你自己变成了验证循环。给 Claude 一个能产生通过/失败的检查，循环就自动闭合——Claude 做工作、运行检查、读取结果、迭代直到检查通过。

检查可以是任何能返回 Claude 可读信号的东西：测试套件、构建退出码、linter、对比输出与 fixture 的脚本，或者浏览器截图与设计稿的对比。

检查存在后，决定它对停止的门控程度：

• 在一个 prompt 中：让 Claude 在同一条消息中运行检查并迭代
• 跨会话：将检查设为 /goal 条件。独立的评估器在每轮后重新检查，Claude 持续工作直到条件满足
• 确定性门控：Stop Hook 以脚本运行检查，阻止 turn 结束直到通过（连续 8 次阻塞后 Claude 会覆盖 Hook 结束 turn）
• 第二意见：验证子代理或动态工作流，让新模型尝试反驳结果

让 Claude 展示证据而非仅仅断言成功：测试输出、执行的命令及其返回值、或结果截图。审核证据比自己重新运行验证更快。

先探索，再规划，最后编码¶

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

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

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

第一步：探索¶

进入 plan mode，Claude 读取文件回答问题但不做修改。

# claude (plan mode)
read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

第二步：规划¶

让 Claude 创建详细的实现计划。

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

按 Ctrl+G 在文本编辑器中打开计划进行直接编辑。

第三步：实现¶

退出 plan mode，让 Claude 编码并对照计划验证。

# claude (default mode)
implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

第四步：提交¶

让 Claude 提交并创建 PR。

# claude (default mode)
commit with a descriptive message and open a PR

注意： Plan mode 很有用，但也有开销。对于范围明确、修改小的任务（修复拼写错误、添加日志行、重命名变量），直接让 Claude 执行即可。规划在你不确定方法、修改涉及多文件、或不熟悉被修改代码时最有价值。如果你能用一句话描述 diff，跳过规划。

在 Prompt 中提供具体上下文¶

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

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

模糊的 prompt 在探索时可能有用。像 "what would you improve in this file?" 这样的 prompt 能浮现你没想到要问的东西。

提供丰富内容¶

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

• 用 @ 引用文件，而非描述代码位置。Claude 在响应前读取文件
• 直接粘贴图片。复制/粘贴或拖放图片到 prompt
• 提供 URL 指向文档和 API 参考。用 /permissions 允许常用域名
• 管道传入数据：cat error.log | claude 直接发送文件内容
• 让 Claude 自己获取上下文。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来拉取上下文

配置你的环境¶

几个设置步骤能让 Claude Code 在所有会话中显著更有效。 关于扩展功能的完整概述，参见 Extend 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 每次会话都会加载，所以只包含广泛适用的内容。对于只在特定场景相关的领域知识或工作流，改用 skills——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 文件可以放在多个位置：

配置权限¶

使用 auto mode 让分类器处理审批、/permissions 允许特定命令、或 /sandbox 进行 OS 级隔离——各自在保持控制的同时减少中断。

默认情况下，Claude Code 对可能修改系统的操作请求权限：文件写入、Bash 命令、MCP 工具等。安全但繁琐——第十次审批时你已经不再真正审核了，只是机械点击。

三种减少中断的方式：

使用 CLI 工具¶

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

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

Claude 也善于学习不熟悉的 CLI 工具。尝试这样的 prompt：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 设计、自动化工作流。

设置 Hooks¶

当某个操作必须每次无例外执行时，使用 Hooks。

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

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

创建 Skills¶

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

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

创建 skill：在 .claude/skills/ 添加带 SKILL.md 的目录：

# .claude/skills/api-conventions/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/)

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

# .claude/skills/fix-issue/SKILL.md
---
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，确保只手动触发。

创建自定义子代理¶

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

子代理在自己的上下文中运行，有自己的工具权限集。适合读取大量文件或需要专注而不污染主对话的任务。

# .claude/agents/security-reviewer.md
---
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."

安装插件¶

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

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

有效沟通¶

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

询问代码库问题¶

像问资深工程师一样问 Claude 问题。

接入新代码库时，使用 Claude Code 进行学习和探索。可以问 Claude 你会问另一位工程师的问题：

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

这样使用 Claude Code 是一种高效的新人上手工作流，缩短熟悉时间并减轻其他工程师的负担。无需特殊 prompting，直接提问。

让 Claude 采访你¶

对于大型功能，让 Claude 先采访你。以简短的 prompt 开始，要求 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.

spec 完成后，开一个新会话来执行。新会话有干净的上下文完全聚焦于实现，你有一份书面 spec 可参考。

最有用的 spec 是自包含的：命名涉及的文件和接口、声明不在范围内的内容、以端到端验证步骤结尾证明功能工作。花在使 spec 精确上的时间比花在观察实现上的时间回报更高。

管理你的会话¶

对话是持久的和可逆的，利用这一点！

及早频繁地纠正方向¶

一注意到 Claude 偏离轨道就纠正。

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

如果在同一会话中对同一问题纠正了 Claude 两次以上，上下文已被失败方法污染。运行 /clear 然后用更具体的 prompt 重新开始，融入你学到的东西。带有更好 prompt 的干净会话几乎总是优于积累了纠正的长会话。

积极管理上下文¶

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

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

长会话期间，上下文窗口可能充满无关的对话、文件内容和命令，降低性能。

• 任务之间频繁使用 /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——答案出现在可关闭的覆盖层中，永远不进入对话历史

使用子代理进行调查¶

委派研究任务："use subagents to investigate X"。它们在独立上下文中探索，保持主对话干净以便实现。

上下文是你的根本约束，子代理因此是最强大的工具之一。Claude 研究代码库时读取大量文件，全部消耗你的上下文。子代理在独立的上下文窗口中运行并返回摘要：

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

子代理探索代码库、读取相关文件、返回发现——全程不会污染你的主对话。

也可以在 Claude 实现后用子代理进行验证：

use a subagent to review this code for edge cases

使用检查点回退¶

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

Claude 在每次修改前自动快照文件。双击 Escape 或运行 /rewind 打开回退菜单。可以只恢复对话、只恢复代码、两者都恢复、或从选定消息总结。

不必谨慎规划每一步，你可以让 Claude 尝试冒险操作。如果不成功，回退并尝试不同方法。检查点跨会话持久化——关闭终端后仍可回退。

注意： 检查点只追踪 Claude 做的修改，不追踪外部进程。这不是 git 的替代品。

恢复对话¶

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

Claude Code 本地保存对话，当任务跨多次坐下时无需重新解释上下文。运行 claude --continue 继续最近的会话，或 claude --resume 从列表中选择。给会话描述性名称如 oauth-migration 以便日后找到。

自动化与规模化¶

一旦你能高效使用一个 Claude，用并行会话、非交互模式和扇出模式成倍增加产出。

到目前为止一切假设一个人、一个 Claude、一次对话。但 Claude Code 可以水平扩展。

运行非交互模式¶

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

claude -p "your prompt" 让你无会话地非交互运行 Claude。非交互模式是你将 Claude 集成到 CI 管道、pre-commit hooks 或任何自动化工作流的方式。

# 一次性查询
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 会话¶

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

选择适合你协调意愿的并行方式：

并行之外，多会话还能实现质量导向的工作流。新鲜的上下文改善代码审查——Claude 不会偏向刚写的代码。

例如，使用 Writer/Reviewer 模式：

类似地可以用测试：一个 Claude 写测试，另一个写代码通过测试。

跨文件扇出¶

循环调用 claude -p 处理各任务。使用 --allowedTools 限制批量操作的权限范围。

对于大规模迁移或分析，可以将工作分发到多个并行的 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

第三步：先在少量文件上测试，再大规模运行

根据前 2-3 个文件的问题优化 prompt，然后在全集上运行。--allowedTools 限制 Claude 的能力——无人值守时这很重要。

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

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

开发时用 --verbose 调试，生产环境关闭。

使用 Auto Mode 自主运行¶

对于无中断执行并有后台安全检查的场景，使用 auto mode。 分类器模型在命令运行前审核，阻止范围升级、未知基础设施和恶意内容驱动的操作，同时让常规工作无需提示即可进行。

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

对于使用 -p 标志的非交互运行，如果分类器反复阻止操作，auto mode 会中止（因为没有用户可以回退）。

添加对抗性审查步骤¶

在将任务视为完成之前，让子代理在新鲜上下文中审查 diff 并报告差距。

Claude 无人值守工作越久，在你将工作视为完成之前独立检查就越重要。运行在新鲜子代理上下文中的审查者只看到 diff 和你给的标准，不看到产生变更的推理过程，因此独立评估结果。

对于正确性检查，运行内置的 /code-review skill。要对照计划检查 diff，自己写审查 prompt。命名要检查的工作、要对照的计划、什么算发现：

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 自己搞清楚——因为任务是探索性的。有时模糊的 prompt 恰好合适——因为你想在约束之前看看 Claude 如何解读问题。

注意什么有效。当 Claude 产出优秀输出时，注意你做了什么：prompt 结构、提供的上下文、所处的模式。当 Claude 挣扎时，问为什么——上下文太嘈杂？Prompt 太模糊？任务对一次处理来说太大？

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

相关资源¶

• Claude Code 工作原理: Agentic 循环、工具和上下文管理
• Extend Claude Code: skills、hooks、MCP、子代理和插件
• Common workflows: 调试、测试、PR 等分步指南
• CLAUDE.md: 存储项目惯例和持久上下文