Claude Code 最佳实践

充分发挥 Claude Code 价值的技巧和模式，从环境配置到并行会话扩展。

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

这改变了你的工作方式。不再是你自己写代码然后让 Claude 审核，而是你描述想要什么，Claude 思考如何构建。Claude 会探索、规划并实现。

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

本指南涵盖在 Anthropic 内部团队以及各类代码库、语言和环境中使用 Claude Code 的工程师们验证过的有效模式。

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

Claude 的上下文窗口保存整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。但这会很快填满。单次调试会话或代码库探索可能产生和消耗数万个 token。

这很重要，因为 LLM 性能随上下文填充而下降。当上下文窗口快满时，Claude 可能开始"忘记"早期指令或犯更多错误。上下文窗口是需要管理的最重要资源。

给 Claude 验证工作的方法

提供测试、截图或预期输出，让 Claude 能自我检查。这是你能做的杠杆率最高的一件事。

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

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

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

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

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

将研究和规划与实现分离，避免解决错误的问题。使用 Plan Mode 将探索与执行分离。

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

1. 探索

进入 Plan Mode。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. 实现

切回 Normal Mode，让 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

Plan Mode 很有用，但也增加开销。对于范围明确、修复很小的任务（如修复拼写错误、添加日志行、重命名变量），让 Claude 直接做。规划在你不确定方法、修改涉及多个文件、或不熟悉被修改代码时最有用。

在提示词中提供具体上下文

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

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

策略	之前	之后
划定任务范围	"为 foo.py 添加测试"	"为 foo.py 写一个测试，覆盖用户登出的边缘情况。避免使用 mock。"
指向来源	"为什么 ExecutionFactory 的 API 这么奇怪？"	"查看 ExecutionFactory 的 git 历史，总结其 API 是如何形成的"
引用现有模式	"添加一个日历组件"	"查看首页现有组件的实现方式来理解模式。HotDogWidget.php 是个好例子。遵循该模式实现新的日历组件"
描述症状	"修复登录 bug"	"用户报告会话超时后登录失败。检查 src/auth/ 中的认证流程，特别是 token 刷新。写一个复现问题的失败测试，然后修复它"

提供丰富内容

用 @ 引用文件 而非描述代码位置
直接粘贴图片 — 复制/粘贴或拖放图片到提示词
提供 URL 用于文档和 API 参考
管道输入数据 通过运行 cat error.log | claude
让 Claude 获取所需内容 — 让 Claude 自己使用 Bash 命令、MCP 工具或读取文件来拉取上下文

配置你的环境

编写有效的 CLAUDE.md

运行 /init 根据当前项目结构生成初始 CLAUDE.md 文件，然后随时间优化。

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时读取。包含 Bash 命令、代码风格和工作流规则。

markdown

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible

# 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 猜不到的 Bash 命令	Claude 通过读代码能弄清楚的任何东西
不同于默认值的代码风格规则	Claude 已知的标准语言约定
测试说明和首选测试运行器	详细的 API 文档（改为链接到文档）
仓库礼仪（分支命名、PR 约定）	频繁变化的信息
项目特有的架构决策	长解释或教程
开发环境 quirks（必需的环境变量）	代码库的逐文件描述
常见陷阱或不明显的行为	显而易见的实践如"写干净的代码"

CLAUDE.md 文件可以使用 @path/to/import 语法导入其他文件。你可以将 CLAUDE.md 文件放在多个位置：主文件夹、项目根目录、父目录和子目录。

配置权限

使用 /permissions 将安全命令加入允许列表，或使用 /sandbox 进行操作系统级隔离。

使用 CLI 工具

告诉 Claude Code 在与外部服务交互时使用 CLI 工具如 gh、aws、gcloud 和 sentry-cli。CLI 工具是与外部服务交互时最高效的上下文方式。

连接 MCP 服务器

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

设置钩子

使用钩子处理必须每次无例外执行的操作。钩子在 Claude 工作流的特定点自动运行脚本。与仅作为建议的 CLAUDE.md 指令不同，钩子是确定性的，保证操作发生。

创建技能

在 .claude/skills/ 中创建 SKILL.md 文件，给 Claude 领域知识和可复用工作流。技能用项目、团队或领域特有的信息扩展 Claude 的知识。

创建自定义子代理

在 .claude/agents/ 中定义专门助手，Claude 可以委托给它们执行隔离任务。子代理在自己的上下文中运行，拥有自己的一组允许工具。

安装插件

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

有效沟通

询问代码库问题

问 Claude 你会问资深工程师的问题：

日志是怎么工作的？
如何创建新的 API 端点？
foo.rs 第 134 行的 async move { ... } 做什么？
CustomerOnboardingFlowImpl 处理哪些边缘情况？

让 Claude 采访你

对于较大功能，先让 Claude 采访你：

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.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

管理你的会话

尽早且频繁地纠偏

Esc：中途停止 Claude
Esc + Esc 或 /rewind：恢复之前的对话和代码状态
"Undo that"：让 Claude 撤销其更改
/clear：在不相关任务间重置上下文

如果在一次会话中对同一问题纠正 Claude 超过两次，上下文已被失败尝试污染。运行 /clear 重新开始。

激进地管理上下文

在任务间频繁使用 /clear
运行 /compact <instructions> 进行可控压缩
使用 /btw 处理不需要留在上下文中的快速问题
使用子代理将调查排除在主上下文之外

使用子代理进行调查

用"使用子代理调查 X"委托研究。它们在单独的上下文中探索，保持主对话干净。

用检查点回退

Claude 的每个操作都创建检查点。双击 Escape 或运行 /rewind 打开回退菜单。

恢复对话

bash

claude --continue    # 恢复最近的对话
claude --resume      # 从最近对话中选择

使用 /rename 给会话描述性名称。

自动化和扩展

运行非交互模式

bash

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 Code 桌面应用：多个本地会话，隔离的 worktree
Claude Code 网页版：隔离 VM 中的安全云基础设施
代理团队：自动化协调，共享任务和消息

写作者/审核者模式：

会话 A（写作者）	会话 B（审核者）
为我们的 API 端点实现限流器
	审核限流器实现。查找边缘情况、竞态条件和一致性。
处理审核反馈

跨文件分发

bash

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

避免常见失败模式

杂烩会话：在一个会话中处理不相关任务 → 修复：任务间用 /clear
反复纠正：失败的纠正污染上下文 → 修复：两次失败后，/clear 并写更好的提示词
过度指定的 CLAUDE.md：太长，Claude 忽略一半 → 修复：无情修剪
信任后验证差距：看似合理但破损的代码 → 修复：始终提供验证
无限探索：无范围调查填满上下文 → 修复：缩小范围或使用子代理

培养你的直觉

注意什么有效。当 Claude 产出优秀结果时，注意你做了什么：提示词结构、提供的上下文、使用的模式。当 Claude 挣扎时，问为什么。

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

Claude Code 最佳实践 ​

给 Claude 验证工作的方法 ​

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

1. 探索 ​

2. 规划 ​

3. 实现 ​

4. 提交 ​

在提示词中提供具体上下文 ​

提供丰富内容 ​

配置你的环境 ​

编写有效的 CLAUDE.md ​

配置权限 ​

使用 CLI 工具 ​

连接 MCP 服务器 ​

设置钩子 ​

创建技能 ​

创建自定义子代理 ​

安装插件 ​

有效沟通 ​

询问代码库问题 ​

让 Claude 采访你 ​

管理你的会话 ​

尽早且频繁地纠偏 ​

激进地管理上下文 ​

使用子代理进行调查 ​

用检查点回退 ​

恢复对话 ​

自动化和扩展 ​

运行非交互模式 ​

运行多个 Claude 会话 ​

跨文件分发 ​

避免常见失败模式 ​

培养你的直觉 ​

相关资源 ​

Claude Code 最佳实践

给 Claude 验证工作的方法

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

1. 探索

2. 规划

3. 实现

4. 提交

在提示词中提供具体上下文

提供丰富内容

配置你的环境

编写有效的 CLAUDE.md

配置权限

使用 CLI 工具

连接 MCP 服务器

设置钩子

创建技能

创建自定义子代理

安装插件

有效沟通

询问代码库问题

让 Claude 采访你

管理你的会话

尽早且频繁地纠偏

激进地管理上下文

使用子代理进行调查

用检查点回退

恢复对话

自动化和扩展

运行非交互模式

运行多个 Claude 会话

跨文件分发

避免常见失败模式

培养你的直觉

相关资源