Claude Code 最佳实践指南：10 个技巧提升 AI 编码智能体工程效率

Claude Code 提供了一个全新的编码智能体环境。与我们过去熟悉的问答式聊天机器人不同，它能够读取你的文件、执行命令、进行修改，并自主地解决复杂问题。在这个过程中，你可以选择在一旁观察、适时重定向，甚至完全离开。

这彻底改变了我们的工作模式。你不再需要自己编写每一行代码，然后让 AI 来审查。相反，你可以描述你想要实现的目标，Claude Code 会自行探索、规划并最终完成构建。

然而，这种自主性也伴随着一条学习曲线。Claude Code 在一定的约束条件下工作，理解这些约束是高效使用它的关键。

本指南汇集了经过 Anthropic 内部团队及众多工程师在不同代码库、语言和环境中实践验证的有效模式。

一个核心的约束贯穿始终：Claude 的上下文窗口很容易被填满，而且随着内容的增加，其性能会下降。这个上下文窗口保存着你的整个对话历史，包括每条消息、Claude 读取的每个文件以及每个命令的输出。一次调试会话或代码库探索就可能会消耗数万个 token。

这一点至关重要，因为当上下文窗口接近满载时，大型语言模型的性能会显著下降，Claude 可能会开始“遗忘”先前的指令或犯更多错误。因此，有效管理上下文窗口是我们需要掌握的最重要资源之一。

为 Claude 提供验证工作的方法

当 Claude 能够自主验证其工作时，例如运行测试、对比截图或检查输出，它的表现会得到显著提升。

如果没有明确成功标准，它可能会产出看起来正确但实际上存在缺陷的代码。这时，你将成为唯一的反馈循环，每个错误都需要你的手动介入。

策略	不佳的示例	改进后的示例
提供验证标准	“实现一个验证电子邮件地址的函数”	“编写一个 validateEmail 函数。提供测试用例：user@example.com 应返回 true，invalid 应返回 false，user@.com 应返回 false。实现后请运行这些测试。”
可视化验证 UI 更改	“让仪表板看起来更好”	“（粘贴截图）请实现这个设计。完成后对结果进行截图，并与原始设计图进行比较。列出所有差异并逐一修复。”
解决根本原因，而非症状	“构建失败了”	“构建失败并出现以下错误：（粘贴错误信息）。请修复它并验证构建能够成功。目标是解决根本原因，而非简单地抑制错误信息。”

你可以利用 Chrome 扩展中的 Claude 来验证 UI 更改。它会打开浏览器，测试 UI 交互，并持续迭代直到代码正常工作。

你的验证手段也可以是测试套件、代码检查工具（linter）或用于检查输出的 Bash 命令。花些时间构建坚实的验证机制是值得的。

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

让 Claude 直接开始编码，可能会导致它解决一个错误的问题。使用“计划模式”可以将探索阶段与执行阶段分离开来。

推荐的工作流程包含四个清晰的阶段，更多信息请参考官方技术文档。

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

Claude 擅长推断意图，但它无法读懂你的心思。在提示中引用具体的文件、提及约束条件，并指向已有的代码模式至关重要。

策略	不佳的示例	改进后的示例
界定任务范围：指定文件、场景和测试偏好。	“为 foo.py 添加测试”	“为 foo.py 编写一个测试，专门覆盖用户注销时的边缘情况。请避免使用模拟（mocks）。”
指向信息来源：指示 Claude 到能够解答问题的源头去查找。	“为什么 ExecutionFactory 的 API 这么奇怪？”	“请浏览 ExecutionFactory 的 Git 历史记录，并总结其 API 是如何演变成现在这样的。”
引用现有模式：指向代码库中已有的实现模式。	“添加一个日历小部件”	“请先查看主页上现有小部件（例如 HotDogWidget.php）的实现方式以了解模式。然后，按照该模式实现一个新的日历小部件，允许用户选择月份并通过向前/向后翻页来选择年份。请从头开始构建，除了代码库中已使用的库外，不要引入新的外部库。”
描述具体症状：提供错误现象、可能的位置以及修复后的预期状态。	“修复登录错误”	“用户报告在会话超时后登录失败。请检查 src/auth/ 目录下的身份验证流程，特别是令牌刷新逻辑。首先编写一个能重现此问题的失败测试，然后修复它。”

当你处于探索阶段，并且有足够空间进行纠正时，模糊的提示也可能有其价值。例如，像“你觉得这个文件里有什么可以改进的？”这样的问题，可能会暴露出你未曾想到的盲点。

提供丰富的内容

你可以通过多种方式为 Claude 提供充足的数据支持：

• 使用 @ 引用文件，而不是描述代码位置。Claude 在响应前会读取该文件。
• 直接粘贴图片。可以通过复制粘贴或拖放的方式将图像插入到提示中。
• 提供文档和 API 参考的 URL。使用 /permissions 命令将常用域名加入白名单。
• 通过管道传输数据，例如运行 cat error.log | claude 直接将文件内容发送给 Claude。
• 让 Claude 自行获取所需信息。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来主动拉取上下文。

配置你的工作环境

一些初始的设置步骤能让 Claude Code 在所有会话中更加高效。

编写高效的 CLAUDE.md

CLAUDE.md 是一个特殊文件，Claude 会在每次对话开始时读取它。你应该在其中包含 Bash 命令、代码风格规范和工作流程规则。这为 Claude 提供了仅通过阅读代码无法推断的持久化上下文。

运行 /init 命令可以分析你的代码库，自动检测构建系统、测试框架和代码模式，为你生成一个良好的基础文件。

CLAUDE.md 没有固定的格式要求，但应保持简短和人类可读。例如：

# 代码风格
- 使用 ES 模块（import/export）语法，而不是 CommonJS（require）
- 尽可能解构导入（例如 import { foo } from 'bar'）

# 工作流
- 完成一系列代码更改后一定要进行类型检查
- 为了性能，优先运行单个测试，而不是整个测试套件

CLAUDE.md 会在每个会话中加载，因此只应包含广泛适用的内容。对于特定领域的知识或有时才需要的工作流，请使用 skills。Claude 会按需加载它们，而不会使每次对话都变得臃肿。

保持文件简洁至关重要。对于每一行内容，不妨问问自己：“删除这一行会导致 Claude 犯错吗？”如果答案是否定的，就删掉它。过于臃肿的 CLAUDE.md 文件可能会导致 Claude 忽略你的实际指令！

✅ 应该包含	❌ 应该排除
Claude 无法猜到的 Bash 命令	Claude 通过阅读代码就能弄清楚的任何事情
与默认值不同的代码风格规则	Claude 已经知道的标准语言约定
测试说明和首选的测试运行器	详细的 API 文档（改为链接到官方文档）
存储库礼仪（分支命名、PR 约定）	经常更改的信息
特定于你的项目的架构决策	长篇解释或教程
开发者环境的特殊情况（必需的环境变量）	代码库的逐文件描述
常见的陷阱或非显而易见的行为	像“编写干净的代码”这样不言自明的做法

如果 Claude 屡次违反 CLAUDE.md 中的规则，可能是因为文件太长，规则被淹没在噪音中了。如果 Claude 询问已在 CLAUDE.md 中回答过的问题，则说明相关措辞可能模棱两可。请将 CLAUDE.md 视为代码：当出现问题时审查它，定期修剪它，并通过观察 Claude 的行为是否真正改变来测试每一次修改。

你可以通过添加强调性词语（例如“IMPORTANT”或“YOU MUST”）来提高指令的遵守度。建议将 CLAUDE.md 提交到 Git 仓库中，以便你的团队成员共同维护。这个文件的价值会随着时间的推移而不断累积。

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

参见 @README.md 了解项目概述，@package.json 了解可用的 npm 命令。

# 附加说明
- Git 工作流：@docs/git-instructions.md
- 个人覆盖：@~/.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 在定义的边界内更自由地工作。

或者，对于包含性的工作流（如修复 lint 错误或生成样板代码），可以使用 --dangerously-skip-permissions 选项绕过所有权限检查。

使用 CLI 工具

CLI 工具是与外部服务交互最节省上下文的方式。如果你使用 GitHub，请安装 gh CLI。Claude 知道如何使用它来创建 Issue、打开 Pull Request 和阅读评论。如果没有 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 (Model Context Protocol) 服务器，你可以让 Claude 实现来自问题跟踪器的功能、查询数据库、分析监控数据、集成来自 Figma 的设计，并自动化各种工作流。

设置 Hooks

Hooks 能在 Claude 工作流程的特定节点自动运行脚本。与建议性的 CLAUDE.md 说明不同，hooks 是确定性的，能够确保操作必然发生。

Claude 可以帮你编写 hooks。尝试这样的提示：“编写一个在每次文件编辑后运行 eslint 的 hook” 或 “编写一个阻止写入 migrations 文件夹的 hook”。运行 /hooks 进行交互式配置，或直接编辑 .claude/settings.json 文件。

创建 Skills

Skills 可以用特定于你的项目、团队或领域的知识来扩展 Claude 的能力。Claude 会在相关时自动应用它们，你也可以直接使用 /skill-name 来调用。

通过向 .claude/skills/ 目录中添加一个包含 SKILL.md 文件的子目录来创建 skill：

.claude/skills/api-conventions/SKILL.md

---
name: api-conventions
description: 我们服务的 REST API 设计约定
---

# API 约定
- 对 URL 路径使用 kebab-case
- 对 JSON 属性使用 camelCase
- 始终为列表端点包括分页
- 在 URL 路径中版本化 API（/v1/、/v2/）

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

.claude/skills/fix-issue/SKILL.md

---
name: fix-issue
description: 修复 GitHub 问题
disable-model-invocation: true
---

分析并修复 GitHub 问题：$ARGUMENTS。

1. 使用 `gh issue view` 获取问题详细信息
2. 理解问题中描述的问题
3. 搜索相关文件的代码库
4. 实现必要的更改以修复问题
5. 编写并运行测试以验证修复
6. 确保代码通过 linting 和类型检查
7. 创建描述性的提交消息
8. 推送并创建 PR

运行 /fix-issue 1234 来调用它。对于那些你希望手动触发且具有副作用的操作流，请使用 disable-model-invocation: true。

创建自定义子代理

子代理在它们自己的上下文中运行，并拥有自己的一套允许使用的工具。它们对于需要读取大量文件，或需要高度专业化专注而不会使主对话混乱的任务非常有用。

.claude/agents/security-reviewer.md

---
name: security-reviewer
description: 审查代码是否存在安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---

你是一位高级安全工程师。审查代码是否存在：
- 注入漏洞（SQL、XSS、命令注入）
- 身份验证和授权缺陷
- 代码中的机密或凭据
- 不安全的数据处理

提供具体的行引用和建议的修复。

明确告诉 Claude 使用子代理：“使用子代理审查此代码是否存在安全问题。”

安装插件

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

有关如何在 skills、子代理、hooks 和 MCP 之间进行选择的指导，请参阅官方文档。

进行有效沟通

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

询问关于代码库的问题

在加入一个新的代码库时，利用 Claude Code 进行学习和探索。你可以向 Claude 提出任何你会向一位资深工程师提出的问题：

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

以这种方式使用 Claude Code 是一个高效的入职工作流程，它能加快你的上手速度，并减轻团队其他工程师的负担。你不需要任何特殊的提示技巧，直接提问即可。

让 Claude 来“面试”你

Claude 可以询问你可能尚未考虑过的问题，包括技术实现细节、UI/UX 设计、边缘情况以及各种权衡。

我想构建 [简要描述]。使用 AskUserQuestion 工具详细面试我。

询问技术实现、UI/UX、边缘情况、担忧和权衡。不要问显而易见的问题，深入挖掘我可能没有考虑过的困难部分。

继续面试，直到我们涵盖所有内容，然后编写完整的规范到 SPEC.md。

规范完成后，可以开启一个新的会话来执行它。新的会话拥有专注于实现的干净上下文，而你也有了一份书面的规范可供参考。

管理你的会话

对话是持久且可逆的。学会利用这一点来发挥你的优势！

尽早且频繁地进行纠正

最佳结果通常来自紧密的反馈循环。虽然 Claude 有时能在第一次尝试时就完美解决问题，但快速纠正它通常能带来更快、更好的解决方案。

• Esc 键：使用 Esc 键可以在中途停止 Claude。上下文会被保留，因此你可以重新下达指令。
• Esc + Esc 或 /rewind：按两次 Esc 或运行 /rewind 命令可以打开倒带菜单，恢复到此前的对话和代码状态。
• “撤销那个”：直接告诉 Claude 撤销它所做的更改。
• /clear：在不相关的任务之间重置上下文。包含不相关内容的长会话可能会降低性能。

如果你在一个会话中针对同一个问题纠正 Claude 超过两次，上下文就可能被失败的方法所干扰。此时，运行 /clear 并使用一个结合了你所学经验的、更具体的提示重新开始。一个拥有更好提示的干净会话，几乎总是胜过带有累积纠正的长会话。

积极管理上下文

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

在长时间会话中，Claude 的上下文窗口可能会被不相关的对话、文件内容和命令输出填满，这可能会分散其注意力并降低性能。

• 经常在不同任务之间使用 /clear 来完全重置上下文窗口。
• 当自动压缩触发时，Claude 会总结最重要的内容，包括代码模式、文件状态和关键决策。
• 为了获得更多控制权，可以运行 /compact <instructions>，例如 /compact Focus on the API changes。
• 你可以在 CLAUDE.md 中自定义压缩行为，使用诸如 “压缩时，始终保留修改文件的完整列表和任何测试命令” 之类的指令，以确保关键上下文在摘要中得以保留。

使用子代理进行调查

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

使用子代理调查我们的身份验证系统如何处理令牌刷新，以及我们是否有任何现有的 OAuth 工具应该重用。

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

你也可以在 Claude 实现某项功能后，使用子代理进行验证：

使用子代理审查此代码是否存在边缘情况

使用检查点进行倒带

Claude 在进行更改前会自动创建检查点。双击 Escape 或运行 /rewind 可以打开检查点菜单。你可以选择仅恢复对话（保持代码更改不变）、仅恢复代码（保持对话不变）或两者都恢复。

你可以告诉 Claude 尝试一些有风险的操作，而不是仔细规划每一步。如果行不通，就倒带并尝试不同的方法。检查点在会话之间持久存在，因此即使你关闭了终端，稍后仍然可以回来进行倒带操作。

恢复对话

Claude Code 在本地保存对话。当任务跨越多个会话时（例如你开始一项功能开发，中途被打断，第二天才回来），你不需要重新解释所有上下文：

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

使用 /rename 为会话赋予一个描述性名称（例如 “oauth-migration”、“debugging-memory-leak”），以便日后查找。将会话视为分支，不同的工作流可以拥有独立的持久化上下文。

自动化与扩展工作流

一旦你能够高效地使用一个 Claude 实例，就可以通过并行会话、无头模式和扇出模式来倍增你的产出。

运行无头模式

使用 claude -p "your prompt"，你可以在没有交互式会话的情况下以无头模式运行 Claude。这是将 Claude 集成到 CI 流水线、pre-commit hooks 或任何自动化工作流中的方式。输出格式（纯文本、JSON、流式 JSON）允许你以编程方式解析结果。

# 一次性查询
claude -p “解释这个项目的作用”

# 用于脚本的结构化输出
claude -p “列出所有 API 端点” --output-format json

# 用于实时处理的流式输出
claude -p “分析这个日志文件” --output-format stream-json

运行多个 Claude 会话

有两种主要方式可以运行并行会话：

• Claude Desktop：可视化管理多个本地会话。每个会话都有自己的隔离工作树。
• Web 上的 Claude Code：在 Anthropic 的安全云基础设施上的隔离 VM 中运行。

除了并行处理工作外，多个会话还支持专注于质量的工作流程。干净的上下文可以改善代码审查的效果，因为 Claude 不会对刚刚编写的代码产生先入为主的偏见。

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

会话 A（编写者）	会话 B（审查者）
为我们的 API 端点实现速率限制器
	审查 @src/middleware/rateLimiter.ts 中的速率限制器实现。寻找边缘情况、竞争条件与我们现有中间件模式的一致性。
这是审查反馈：[会话 B 输出]。解决这些问题。

你也可以用测试做类似的事情：让一个 Claude 编写测试，然后让另一个编写能够通过这些测试的代码。

跨文件扇出

对于大规模迁移或分析任务，你可以将工作分配到许多并行的 Claude 调用中。

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

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

在开发过程中可以使用 --verbose 标志进行调试，在生产环境中则关闭它。

安全的自主模式

使用 claude --dangerously-skip-permissions 可以绕过所有权限检查，让 Claude 不间断地工作。这适用于修复 lint 错误或生成样板代码等受控且包含性的工作流。

避免常见的失败模式

以下是一些常见的错误模式。及早识别它们可以节省大量时间：

• 厨房水槽式会话：你从一个任务开始，然后问 Claude 一些不相关的事情，接着又回到第一个任务。上下文充满了无关信息。

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

• 一遍又一遍地纠正：Claude 做错了，你纠正它；它又错了，你再纠正。上下文被失败的方法所污染。

  修复：在两次失败的纠正后，果断 /clear 并编写一个结合了你所学经验的更好的初始提示。

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

  修复：无情地进行修剪。如果 Claude 在没有某条指令的情况下也能正确行事，请删除该指令或考虑将其转换为一个 hook。

• 信任与验证之间的差距：Claude 产生了一个看起来合理的实现，但没有处理边缘情况。

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

• 无限探索：你让 Claude “调查”某些事情但没有限定范围。Claude 读取了数百个文件，填满了上下文。

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

培养你的直觉

本指南中的模式并非一成不变的规则。它们是在大多数情况下行之有效的起点，但可能并非对每种情况都是最优的。

有时，你应该让上下文积累起来，因为你正深陷于一个复杂问题，历史记录很有价值。有时，你应该跳过规划，让 Claude 自行摸索，因为任务是探索性的。有时，模糊的提示恰恰是正确的选择，因为你希望在约束它之前，先看看 Claude 会如何解释问题。

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

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

如果你希望与更多开发者交流这些AI智能体编码的最佳实践，或者探讨其他开源实战经验，欢迎到相关的技术社区参与讨论。