AI 前沿精读

外观

Best Practices for Claude Code ​

原标题: Best Practices for Claude Code 中文标题: Claude Code 最佳实践：从入门到精通的高效使用指南 原文链接: https://www.anthropic.com/engineering/claude-code-best-practices

一句话摘要 ​

本文系统性地梳理了使用 Claude Code 的最佳实践，核心围绕一个关键约束展开：上下文窗口是最宝贵的资源，有效管理上下文是获得最佳输出的根本。

完整核心内容翻译 ​

核心理念 ​

Claude Code 是一个智能体编程环境，而非简单的聊天机器人。与传统的"你写代码，AI审查"模式不同，Claude Code 允许你描述意图，由 Claude 自主探索、规划并实现。但这种自主性也带来了学习曲线。

最重要的约束：上下文窗口会迅速填满，性能随之下降。 Claude 的上下文窗口包含整个对话、每个读取的文件和每条命令输出。一次调试会话或代码库探索可能消耗数万个Token。当上下文接近饱和时，Claude 可能开始"遗忘"早期指令或犯更多错误。

一、让 Claude 有能力自我验证 ​

这是你能做的最高杠杆的事情。 Claude 在能够自我验证工作时表现显著提升——运行测试、对比截图、验证输出。

策略低效做法高效做法
提供验证标准"实现一个验证邮箱的函数""写一个 validateEmail 函数，测试用例：user@example.com 为真，invalid 为假。实现后运行测试"
视觉验证UI变更"让仪表盘更好看""[粘贴截图] 实现这个设计，截图对比结果，列出差异并修复"
解决根因而非症状"构建失败了""构建失败报错：[粘贴错误]。修复它并验证构建成功，解决根本原因，不要压制错误"

二、先探索、再规划、后编码 ​

让 Claude 直接编码可能会解决错误的问题。推荐的工作流分为四个阶段：

  1. 探索阶段（Plan Mode）： Claude 读取文件、回答问题但不做修改。
  2. 规划阶段： 让 Claude 制定详细的实现方案。按 Ctrl+G 可在文本编辑器中直接编辑方案。
  3. 实现阶段（Normal Mode）： 让 Claude 按方案编码，边写边验证。
  4. 提交阶段： 让 Claude 提交并创建PR。

注意： Plan Mode 也有开销。对于范围明确的小修改（修改错别字、添加日志行），直接让 Claude 执行即可。规划最适合方向不确定、涉及多文件修改或不熟悉待修改代码的场景。

三、在Prompt中提供具体上下文 ​

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

  • 限定任务范围： 指定具体文件、场景和测试偏好
  • 指向信息来源： 引导 Claude 查看特定的git历史、文档
  • 引用现有模式： 指向代码库中的参考实现
  • 描述症状： 提供症状、可能的位置和"修复"的样子

提供丰富内容的方式：

  • 用 @ 引用文件
  • 直接粘贴图片（拖放或复制粘贴）
  • 提供URL（用 /permissions 把常用域名加入白名单）
  • 管道传入数据：cat error.log | claude
  • 让 Claude 自行获取上下文

四、配置你的环境 ​

编写有效的 CLAUDE.md： 运行 /init 生成初始文件，然后逐步完善。CLAUDE.md 在每次对话开始时被读取，应包含 Bash 命令、代码风格和工作流规则。

CLAUDE.md 应该包含的内容：

  • Claude 无法猜到的 Bash 命令
  • 与默认不同的代码风格规则
  • 测试指令和首选测试运行器
  • 仓库规范（分支命名、PR 约定）
  • 项目特定的架构决策
  • 开发环境的特殊要求

不应包含的内容：

  • Claude 通过读代码就能知道的事情
  • 标准语言惯例
  • 详细的 API 文档（改用链接）
  • 频繁变化的信息
  • 冗长的解释或教程

关键原则： 把 CLAUDE.md 当代码一样对待——出问题时审查它，定期裁剪，通过观察 Claude 行为是否改变来验证修改效果。如果太长，Claude 会忽略掉真正重要的规则。

配置权限： 使用 /permissions 将安全命令加入白名单，或使用 /sandbox 进行操作系统级隔离，减少不必要的审批中断。

使用 CLI 工具： 告知 Claude Code 使用 gh、aws、gcloud 等 CLI 工具与外部服务交互。CLI 工具是与外部服务交互的最高效方式。

连接 MCP 服务器： 运行 claude mcp add 连接 Notion、Figma 或数据库等外部工具。

设置 Hooks： Hooks 在 Claude 工作流的特定节点自动运行脚本。与 CLAUDE.md 指令不同，Hooks 是确定性的，保证动作一定会执行。

创建 Skills： 在 .claude/skills/ 中创建 SKILL.md 文件，为 Claude 提供特定领域知识和可复用的工作流。Skills 按需加载，不会膨胀每次对话。

创建自定义子智能体： 在 .claude/agents/ 中定义专门的助手，用于隔离任务中的委托工作。

五、有效沟通 ​

  • 将 Claude 当作高级工程师来提问，适用于代码库入门和学习
  • 让 Claude 访谈你： 对于大型功能，先让 Claude 用 AskUserQuestion 工具对你进行深度访谈，覆盖技术实现、UI/UX、边缘情况和权衡，然后写出完整规格说明

六、管理你的会话 ​

及早且频繁地纠正方向：

  • Esc：中途停止 Claude，上下文保留
  • Esc + Esc 或 /rewind：打开回溯菜单恢复之前的对话和代码状态
  • /clear：在不相关任务之间重置上下文

积极管理上下文：

  • 在任务之间频繁使用 /clear
  • 运行 /compact <指令> 进行定向压缩
  • 使用 /btw 进行快速提问，答案不会进入对话历史
  • 在 CLAUDE.md 中自定义压缩行为

使用子智能体进行调研： 子智能体在独立的上下文窗口中运行并返回摘要，不会污染主对话上下文。这是最强大的工具之一。

利用检查点： Claude 在每次修改前自动创建检查点。可以恢复对话、代码或两者。检查点跨会话持久保存。

恢复对话： 使用 claude --continue 继续最近的对话，claude --resume 从最近的会话中选择。

七、自动化与扩展 ​

非交互模式： 使用 claude -p "prompt" 在 CI、pre-commit hooks 或脚本中运行。

并行多会话： 通过桌面应用、网页版或 Agent Teams 运行多个 Claude 会话。推荐的"写者/审阅者"模式：一个会话写代码，另一个审查。

跨文件扇出： 对于大规模迁移，将工作分配给多个并行 Claude 调用，用 --allowedTools 限制权限。

八、避免常见失败模式 ​

  1. 万能会话： 在一个会话中混合不相关任务——用 /clear 隔离
  2. 反复纠正： 两次纠正失败后，/clear 并写更好的初始Prompt
  3. 过度臃肿的 CLAUDE.md： 无情裁剪，删除 Claude 已经能正确做到的指令
  4. 信任-验证落差： 始终提供验证手段（测试、脚本、截图）
  5. 无限探索： 限定调研范围或使用子智能体

九、培养你的直觉 ​

这些模式不是金科玉律，而是通用起点。注意什么有效——Prompt结构、提供的上下文、所处的模式。当 Claude 遇困时，问"为什么"——上下文太嘈杂？Prompt太模糊？任务对单次处理太大？随着时间推移，你将发展出指南无法捕捉的直觉。

技术要点 ​

  1. 上下文窗口是核心约束： 所有最佳实践本质上都围绕"如何高效利用有限的上下文窗口"展开。性能随上下文填充而下降，管理上下文是第一要务。
  2. 自我验证机制是最高杠杆点： 为 Claude 提供测试用例、截图或预期输出，让它能够自我检查，这比任何其他技巧都更能提升输出质量。
  3. CLAUDE.md 是持久性上下文的核心： 作为每次会话的"系统提示"，需要像代码一样维护——简洁、精确、定期裁剪，过长反而有害。
  4. 子智能体是上下文管理的利器： 将调研和探索委托给子智能体，在独立的上下文窗口中运行，保持主对话的"干净"。
  5. 并行化与扇出实现规模化： 通过非交互模式和多会话并行，将单人单Claude的生产力成倍放大。

深度解读 ​

本文最深刻的洞察是将"上下文窗口管理"提升为使用 Claude Code 的第一原则。这一认知框架解释了几乎所有最佳实践的底层逻辑：

为什么要先规划再编码？ 因为盲目编码会用失败尝试填满上下文。为什么要用子智能体？ 因为调研过程的文件读取会大量消耗主对话上下文。为什么CLAUDE.md要精简？ 因为冗余信息在每次会话中都占用宝贵的上下文容量。

这本质上是一种**"注意力经济学"**的思维方式——上下文窗口是稀缺资源，每一个Token的占用都有机会成本。工程师需要像管理内存一样管理上下文：及时释放（/clear）、按需分配（子智能体）、压缩存储（/compact）。

另一个重要启示是 Claude Code 正在改变"人机协作"的边界。从传统的"人写代码，AI辅助"到"人描述意图，AI自主实现"，这要求工程师发展一套新的元技能：不是如何编写更好的代码，而是如何更好地表达意图、提供约束和验证标准。

"写者/审阅者"双会话模式特别值得关注——它利用了一个重要事实：Claude 在审查自己刚写的代码时天然存在偏见，而一个全新的上下文能提供更客观的视角。这实际上是用"上下文隔离"来模拟团队中的代码审查流程。

延伸思考 ​

  1. 随着上下文窗口不断扩大（100K → 200K → 1M），本文强调的"上下文管理"最佳实践是否会过时？还是说即便窗口无限大，信噪比管理依然重要？
  2. CLAUDE.md 的"持久性上下文"概念是否可以演化为一个团队级的"AI工程知识库"？如何在团队中共建和维护？
  3. 子智能体的分层模式（主智能体-子智能体）是否会演变为更复杂的多智能体协作拓扑？如何设计最优的智能体协作架构？
  4. "先让 Claude 访谈你"这一模式，是否暗示了一种新的产品设计范式——AI主动引导需求澄清而非被动接受指令？

本文为 Anthropic 官方 Claude Code 文档最佳实践章节的深度中文解读。

全球顶尖 AI 实验室博客的中文翻译与深度解读 · 210+ 篇文章 · 15+ 实验室

© 2025-2026 AI 前沿精读