Claude Code 最佳实践

Posted on 三月 6, 2026

Claude Code 最佳实践

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

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

核心约束：上下文窗口

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

Claude 的上下文窗口保存你的整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。当上下文窗口即将满时，Claude 可能会开始”遗忘”早期的指令或犯更多错误。

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

当 Claude 能够验证自己的工作时，例如运行测试、比较屏幕截图和验证输出，它的表现会显著提高。

策略示例

策略	之前	之后
提供验证标准	“实现一个验证电子邮件地址的函数”	“编写一个 validateEmail 函数。示例测试用例：[email protected] 为真，invalid 为假。实现后运行测试”
以视觉方式验证 UI 更改	“让仪表板看起来更好”	“[粘贴屏幕截图] 实现此设计。对结果进行屏幕截图并与原始设计进行比较。列出差异并修复它们”
解决根本原因，而不是症状	“构建失败”	“构建失败，出现此错误：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要抑制错误”

先探索，再规划，再编码

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

1. 探索

进入 Plan Mode。Claude 读取文件并回答问题，不进行任何更改。

2. 规划

要求 Claude 创建详细的实现计划。按 Ctrl+G 在文本编辑器中打开计划进行直接编辑。

3. 实现

切换回 Normal Mode 并让 Claude 编码，根据其计划进行验证。

4. 提交

要求 Claude 使用描述性消息进行提交并创建 PR。

在提示中提供具体上下文

有效提示示例

策略	之前	之后
限定任务范围	“为 foo.py 添加测试”	“为 foo.py 编写测试，涵盖用户已注销的边界情况。避免使用 mocks。”
指向来源	“为什么 ExecutionFactory 有这样奇怪的 api？”	“查看 ExecutionFactory 的 git 历史记录并总结其 api 是如何演变的”
引用现有模式	“添加日历小部件”	“查看主页上现有小部件的实现方式以了解模式。HotDogWidget.php 是一个很好的例子。遵循该模式实现一个新的日历小部件”
描述症状	“修复登录错误”	“用户报告会话超时后登录失败。检查 src/auth/ 中的身份验证流程，特别是令牌刷新。编写一个失败的测试来重现问题，然后修复它”

提供丰富的内容

使用 @ 引用文件，而不是描述代码的位置
直接粘贴图像。将图像复制/粘贴或拖放到提示中
提供 URL 用于文档和 API 参考
管道数据，通过运行 cat error.log | claude 直接发送文件内容

配置你的环境

编写有效的 CLAUDE.md

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时都会读取。运行 /init 根据你当前的项目结构生成一个启动 CLAUDE.md 文件。

包括内容

Claude 无法猜测的 Bash 命令
与默认值不同的代码风格规则
测试指令和首选测试运行器
存储库礼仪（分支命名、PR 约定）
特定于你项目的架构决策
开发者环境怪癖（必需的环境变量）
常见陷阱或非显而易见的行为

排除内容

Claude 可以通过阅读代码找出的任何东西
Claude 已经知道的标准语言约定
详细的 API 文档（改为链接到文档）
经常变化的信息
长解释或教程
自明的实践，如”编写干净代码”

配置权限

使用 /permissions 将安全命令加入白名单或使用 /sandbox 进行操作系统级隔离。

使用 CLI 工具

告诉 Claude Code 使用 CLI 工具，如 gh、aws、gcloud 和 sentry-cli。

连接 MCP 服务器

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

设置 hooks

对必须每次发生且没有例外的操作使用 hooks。

创建 skills

在 .claude/skills/ 中创建 SKILL.md 文件，为 Claude 提供特定于项目的域知识和可重用工作流。

创建自定义 subagents

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

有效沟通

提出代码库问题

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

日志如何工作？
我如何创建新的 API 端点？
某行代码做什么？
为什么这段代码调用 foo() 而不是 bar()？

让 Claude 采访你

对于更大的功能，让 Claude 先采访你，然后编写规范。

管理你的会话

尽早且经常改正方向

Esc：使用 Esc 键在 Claude 执行中途停止
Esc + Esc 或 /rewind：恢复之前的对话和代码状态
“撤销那个”：让 Claude 恢复其更改
/clear：重置不相关任务之间的上下文

积极管理上下文

在任务之间频繁使用 /clear 以完全重置上下文窗口
运行 /compact <instructions> 自定义压缩行为
使用 Esc + Esc 或 /rewind 选择消息检查点并总结

使用 subagents 进行调查

使用”使用 subagents 调查 X”委托研究。它们在单独的上下文中探索，为实现保持你的主对话干净。

使用检查点倒带

Claude 在更改前自动检查点。双击 Escape 或运行 /rewind 恢复之前的状态。

自动化和扩展

运行非交互模式

使用 claude -p "your prompt" 非交互地运行 Claude。

运行多个 Claude 会话

使用 Claude Code 桌面应用、Web 版本或 Agent teams 并行运行多个会话。

跨文件扇出

对于大型迁移，循环遍历任务，为每个调用 claude -p。

避免常见失败模式

厨房水槽会话：从不相关任务开始，上下文充满无关信息
- 修复：在不相关的任务之间使用 /clear
一次又一次地改正：上下文被失败的方法污染
- 修复：在两次失败的改正后，/clear 并编写更好的初始提示
过度指定的 CLAUDE.md：太长导致 Claude 忽略一半
- 修复：无情地修剪
信任然后验证的差距：实现不处理边界情况
- 修复：始终提供验证（测试、脚本、屏幕截图）
无限探索：Claude 读取数百个文件，填满上下文
- 修复：狭隘地限定调查范围或使用 subagents

本文档来自 Claude Code 官方文档