Claude Code 最佳实践指南

概览

Claude Code 是一个智能体编码环境，它使 AI 能够读取文件、执行命令并自主实现解决方案，而不仅仅是审查代码。为了最大限度地提高其效率，用户必须管理上下文窗口——它存储了所有消息、文件读取和命令输出——因为当窗口填满时，性能会下降。

实现自主验证

为了防止用户成为唯一的验证环节，应为 Claude Code 提供确定性的信号，以确定任务何时完成。

验证策略

  • 验证标准：与其提供模糊的要求，不如提供具体的测试用例（例如，“编写一个 validateEmail 函数；user@example.com 为 true，无效的为 false”）并指示 Claude 运行它们。
  • 视觉验证：对于 UI 变更，提供设计截图并指示 Claude 获取结果截图并列出差异。
  • 根本原因分析：在修复构建问题时，提供具体的错误并要求构建成功，而不是压制错误。

门控机制

根据所需的自主程度，可以通过以下方式实现验证：

  • 单次提示词：在一条消息中请求检查和迭代。
  • 目标条件 (/goal)：使用单独的评估器在每一轮对话后重新检查条件。
  • 停止钩子 (Stop Hooks)：在特定检查通过之前阻止回合结束的脚本。
  • 验证子智能体 (Verification Subagents)：使用全新的模型来反驳主要智能体的结果。

工作流：探索、计划与编码

直接进入编码可能会导致解决错误的问题。Anthropic 建议使用 plan mode 的四阶段工作流，将探索与执行分离：

  1. 探索：理解代码库和问题。
  2. 计划：定义实现策略。
  3. 编码：执行计划。
  4. 验证：确保解决方案符合标准。

提示词与上下文优化

提供特定上下文

提示词的精准度可以减少歧义并防止错误。有效的策略包括：

  • 限定任务范围：指定确切的文件、场景和测试偏好（例如，“避免使用 mocks"）。
  • 指导来源：指向 Claude 的特定 git 历史记录或文件，以回答架构问题。
  • 引用模式：指示 Claude 参考现有代码库中的示例（例如，“HotDogWidget.php”）以确保一致性。
  • 描述症状：提供错误、可能的位置以及“已修复”的定义。

丰富的内容集成

  • @ 引用：使用 @ 直接引用文件，以便 Claude 在响应之前读取它们。
  • 直接输入：粘贴图像、提供文档的 URL，或使用 cat error.log | claude 管道传输数据。
  • 自主获取：指示 Claude 使用 Bash 命令或 MCP 工具来获取必要的上下文。

环境配置

CLAUDE.md 文件

CLAUDE.md 是一个持久化的上下文文件，在每次会话开始时读取。它应该保持简洁，以避免上下文窗口膨胀。

  • 应包含的内容：非显而易见的 Bash 命令、自定义代码风格规则、首选的测试运行器、仓库规程，以及项目特定的架构决策。
  • 应排除的内容：标准的语言规范、详细的 API 文档（请使用链接代替）、以及频繁变化的信息。

权限与自动化

  • Auto Mode：使用分类器模型来仅拦截风险操作（例如，权限提升），从而减少手动审批的需要。
  • 权限允许列表 (Permission Allowlists)：专门允许安全的工具，如 npm run lint。
  • 沙箱机制 (Sandboxing)：操作系统层级的隔离，以限制文件系统和网络访问。

扩展与工具化

  • CLI Tools：安装像 GitHub CLI (gh) 这样的工具，可以使 Claude 实现比通过 API 更高效的 issue 和 PR 管理。
  • MCP Servers：将 Claude 连接到问题追踪器、数据库和 Figma 设计。
  • Hooks：在特定点运行的确定性脚本（例如，在每次编辑后运行 eslint）。
  • Skills：存储在 .claude/skills/ 中的项目特定知识，可以通过 /skill-name 调用。
  • Subagents：用于重度研究或对抗性审查的独立上下文，以避免干扰主会话。
  • Plugins：技能、钩子和 MCP 服务器的组合单元，包括针对强类型语言的代码智能插件。

会话管理

上下文维护

由于上下文窗口是主要的约束条件，因此需要进行积极的管理：

  • /clear：在不相关的任务之间重置上下文，以防止“大杂烩会话 (Kitchen Sink Sessions)”。
  • /compact：手动触发对话历史的摘要生成。
  • /btw：用于不应保存到对话历史中的旁路问题。
  • 纠错机制：如果 Claude 在同一个问题上失败了两次，请使用 /clear 重置会话并使用更具体的提示词开始。

状态控制

  • 回退与检查点 (Rewind and Checkpoints)：使用 Esc + Esc 或 /rewind 来恢复之前的代码状态或对话历史。
  • 恢复 (Resuming)：使用 claude --continue 或 claude --resume 来接续之前的会话。

扩展与自动化

非交互模式

使用 claude -p "prompt" 允许集成到 CI 管道和 pre-commit 钩子中，输出可以是以纯文本、JSON 或流式 JSON 形式提供。

并行执行

  • Worktrees：为不同的 CLI 会话提供隔离的 git checkouts。
  • Agent Teams：通过团队负责人实现多个会话的自动化协调。
  • Writer/Reviewer Pattern：使用独立的会话进行实现与审查，以消除偏差。

Fan-out Patterns

对于大规模迁移，用户可以通过识别文件、生成任务列表并运行并行非交互式调用来实现任务分发。

常见失败模式（应避免）

  • 大杂烩会话 (The Kitchen Sink Session)：在一个会话中混合不相关的任务；通过使用 /clear 来修复。

  • 过度纠正 (Over-correcting)：重复纠正同一个错误；通过使用更好的提示词重新开始会话来修复。

  • CLAUDE.md 过度详细：规则过多导致 Claude 忽略指令；通过精简来修复。

  • 信任后验证的缺口 (Trust-then-Verify Gap)：交付了看似合理但未经测试的代码；通过要求确定性的验证来修复。

  • 无限探索 (Infinite Exploration)：未限定范围的研究导致上下文填满；通过使用 subagents 来修复。

Sources

相关