Claude Code: 智能体编程最佳实践

# Claude Code 最佳实践 - Claude Code 文档 来源：https://code.claude.com/docs/en/best-practices > ## 文档索引 > 获取完整文档索引：https://code.claude.com/docs/llms.txt > 在深入探索之前，使用此文件发现所有可用页面。 Claude Code 是一个智能体编码环境。与回答问题后等待的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、做出修改，并在你观察、引导或完全离开的情况下自主解决问题。这改变了你的工作方式。你不再是自己写代码然后让 Claude 审查，而是描述你想要什么，Claude 会想办法构建它。Claude 会探索、规划并实施。 但这种自主性仍有学习曲线。Claude 在某些约束条件下工作，你需要理解这些约束。本指南涵盖了在 Anthropic 内部团队以及使用 Claude Code 的工程师在各种代码库、语言和环境中被证明有效的模式。关于智能体循环的底层工作原理，请参阅 [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)。 --- 大多数最佳实践基于一个约束条件：**Claude 的上下文窗口很快会被填满，而且随着填充性能会下降**。 Claude 的上下文窗口包含你的整个对话，包括每条消息、Claude 读取的每个文件以及每条命令输出。然而，这会很快填满。一次调试会话或代码库探索就可能生成并消耗数万个 token。 这很重要，因为随着上下文填充，LLM 性能会下降。当上下文窗口快满时，Claude 可能开始"忘记"之前的指令或犯更多错误。**上下文窗口是最重要的管理资源**。 要了解会话在实践中如何填充，请观看 [交互式演示](https://code.claude.com/docs/en/context-window)，了解启动时加载的内容以及每次文件读取的代价。使用 [自定义状态栏](https://code.claude.com/docs/en/statusline) 持续跟踪上下文使用情况，并参阅 [Reduce token usage](https://code.claude.com/docs/en/costs#reduce-token-usage) 了解减少 token 使用的策略。 --- ## 让 Claude 有办法验证其工作 当 Claude 能够验证自己的工作时，表现会显著提升，比如运行测试、对比截图和验证输出。如果没有明确的成功标准，它可能会产生看起来正确但实际上无法工作的结果。你成为唯一的反馈循环，每个错误都需要你的关注。 | 策略 | 之前 | 之后 | |------|------|------| | **提供验证标准** | "实现一个验证邮箱地址的函数" | "编写 validateEmail 函数。示例测试用例：[email protected] 为 true，invalid 为 false，[email protected] 为 false。实现后运行测试" | | **视觉验证 UI 更改** | "让仪表盘更好看" | "[粘贴截图] 实现这个设计。截取结果截图并与原图对比。列出差异并修复" | | **解决根本原因，而非症状** | "构建失败了" | "构建失败并出现此错误：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要抑制错误" | UI 更改可以使用 [Claude in Chrome 扩展](https://code.claude.com/docs/en/chrome) 进行验证。它会在浏览器中打开新标签页，测试 UI，并迭代直到代码工作。 你的验证也可以是测试套件、linter 或检查输出的 Bash 命令。投入精力让你的验证坚如磐石。 --- ## 先探索，再规划，最后编码 让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用 [plan mode](https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) 将探索与执行分离。 推荐的工作流程有四个阶段： --- ## 在提示中提供具体上下文 Claude 可以推断意图，但它读不懂你的心。引用具体文件、提及约束条件、指向示例模式。 | 策略 | 之前 | 之后 | |------|------|------| | **限定任务范围。** 指定哪个文件、什么场景和测试偏好。 | "为 foo.py 添加测试" | "为 foo.py 编写测试，覆盖用户未登录的边界情况。避免使用 mock。" | | **指向来源。** 引导 Claude 到能回答问题的来源。 | "为什么 ExecutionFactory 的 API 这么奇怪？" | "查看 ExecutionFactory 的 git 历史，总结其 API 是如何演变成这样的" | | **引用现有模式。** 指向代码库中的模式。 | "添加一个日历组件" | "查看首页上现有组件的实现方式以了解模式。HotDogWidget.php 是个好例子。遵循该模式实现一个新的日历组件，让用户可以选择月份并向前/向后翻页选择年份。从头构建，不使用代码库中已有的库之外的库。" | | **描述症状。** 提供症状、可能位置和"修复完成"的样子。 | "修复登录 bug" | "用户报告会话超时后登录失败。检查 src/auth/ 中的认证流程，特别是 token 刷新。编写能复现问题的失败测试，然后修复它" | 模糊提示在探索和可以承受调整时很有用。像 `"这个文件你有什么可以改进的？"` 这样的提示可以发现你想不到要问的东西。 ### 提供丰富内容 你可以通过多种方式向 Claude 提供丰富的数据： - **使用 `@` 引用文件**，而不是描述代码在哪里。Claude 会在回复前读取文件。 - **直接粘贴图片**。复制/粘贴或拖拽图片到提示中。 - **提供文档和 API 参考的 URL**。使用 `/permissions` 将常用域名加入白名单。 - **管道输入数据**，运行 `cat error.log | claude` 直接发送文件内容。 - **让 Claude 获取它需要的内容**。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来自行获取上下文。 --- ## 配置你的环境 几个设置步骤能让 Claude Code 在所有会话中更加高效。关于扩展功能的完整概述以及何时使用每个功能，请参阅 [Extend Claude Code](https://code.claude.com/docs/en/features-overview)。 ### 编写有效的 CLAUDE.md CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时都会读取。包含 Bash 命令、代码风格和工作流规则。这给了 Claude 无法从代码本身推断的持久上下文。 `/init` 命令会分析你的代码库以检测构建系统、测试框架和代码模式，为你提供坚实的完善基础。 CLAUDE.md 文件没有固定格式，但保持简短且人类可读。例如： ```markdown # 代码风格 - 使用 ES modules (import/export) 语法，而非 CommonJS (require) - 尽可能解构导入（例如 import { foo } from 'bar'） # 工作流 - 完成一系列代码更改后务必进行类型检查 - 优先运行单个测试，而非整个测试套件，以提升性能 ``` CLAUDE.md 每次会话都会加载，所以只包含普遍适用的内容。对于仅有时相关的领域知识或工作流，请使用 [skills](https://code.claude.com/docs/en/skills)。Claude 按需加载它们，不会膨胀每次对话。 **保持简洁**。对每一行问自己：*"删除这行会导致 Claude 犯错吗？"* 如果不会，删掉它。臃肿的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令！ | ✅ 包含 | ❌ 排除 | |--------|--------| | Claude 猜不到的 Bash 命令 | Claude 通过阅读代码能弄清楚的东西 | | 与默认不同的代码风格规则 | Claude 已知的标准语言约定 | | 测试指令和首选测试运行器 | 详细的 API 文档（链接到文档代替） | | 仓库规范（分支命名、PR 约定） | 经常变化的信息 | | 项目特定的架构决策 | 长篇解释或教程 | | 开发者环境特性（必需的环境变量） | 代码库的文件级描述 | | 常见陷阱或非明显行为 | 自明的实践如"编写干净代码" | 如果 Claude 尽管有规则仍持续做你不想要的事，文件可能太长，规则被淹没了。如果 Claude 问的问题在 CLAUDE.md 中有答案，措辞可能不够明确。 像对待代码一样对待 CLAUDE.md：出问题时审查、定期修剪、通过观察 Claude 行为是否实际改变来测试更改。 你可以通过添加强调（例如 "IMPORTANT" 或 "YOU MUST"）来调整指令以提高遵守度。 将 CLAUDE.md 加入 git 以便团队贡献。这个文件的价值会随时间复利增长。 CLAUDE.md 文件可以使用 `@path/to/import` 语法导入其他文件： ```markdown See @README.md for project overview and @package.json for available npm commands. # Additional Instructions - Git workflow: @docs/git-instructions.md - Personal overrides: @~/.claude/my-project-instructions.md ``` 你可以将 CLAUDE.md 文件放在多个位置： - **Home 文件夹 (`~/.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 工具等。这很安全但繁琐。第十次批准后你就不再真的在审查了，只是在点击通过。 有三种方式减少这些中断： - **Auto mode**：单独的分类器模型审查命令，只阻止看起来有风险的操作：范围升级、未知基础设施或敌意内容驱动的操作。最适合你信任任务整体方向但不想点击每一步时 - **权限白名单**：允许你知道安全的特定工具，如 `npm run lint` 或 `git commit` - **沙箱**：启用操作系统级隔离，限制文件系统和网络访问，让 Claude 在定义边界内更自由地工作 更多内容请参阅 [permission modes](https://code.claude.com/docs/en/permission-modes)、[permission rules](https://code.claude.com/docs/en/permissions) 和 [sandboxing](https://code.claude.com/docs/en/sandboxing)。 ### 使用 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 servers](https://code.claude.com/docs/en/mcp)，你可以让 Claude 从 issue 跟踪器实现功能、查询数据库、分析监控数据、集成 Figma 设计并自动化工作流。 ### 设置 hooks [Hooks](https://code.claude.com/docs/en/hooks-guide) 在 Claude 工作流的特定点自动运行脚本。与 CLAUDE.md 指令的建议性质不同，hooks 是确定性的，保证操作发生。 Claude 可以为你编写 hooks。尝试提示如 *"编写一个每次文件编辑后运行 eslint 的 hook"* 或 *"编写一个阻止写入 migrations 文件夹的 hook"*。 直接编辑 `.claude/settings.json` 手动配置 hooks，运行 `/hooks` 浏览已配置的内容。 ### 创建 skills [Skills](https://code.claude.com/docs/en/skills) 用特定于你的项目、团队或领域的信息扩展 Claude 的知识。Claude 在相关时自动应用它们，或你可以用 `/skill-name` 直接调用。 通过添加包含 `SKILL.md` 的目录到 `.claude/skills/` 创建 skill： ``` .claude/skills/api-conventions/SKILL.md ``` ```markdown --- name: api-conventions description: REST API design conventions for our services --- # API Conventions - Use kebab-case for URL paths - Use camelCase for JSON properties - Always include pagination for list endpoints - Version APIs in the URL path (/v1/, /v2/) ``` Skills 也可以定义你直接调用的可重复工作流： ``` .claude/skills/fix-issue/SKILL.md ``` ```markdown --- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Analyze and fix the GitHub issue: $ARGUMENTS. 1. Use `gh issue view` to get the issue details 2. Understand the problem described in the issue 3. Search the codebase for relevant files 4. Implement the necessary changes to fix the issue 5. Write and run tests to verify the fix 6. Ensure code passes linting and type checking 7. Create a descriptive commit message 8. Push and create a PR ``` 运行 `/fix-issue 1234` 调用它。对具有副作用且希望手动触发的工作流使用 `disable-model-invocation: true`。 ### 创建自定义 subagents [Subagents](https://code.claude.com/docs/en/sub-agents) 在自己的上下文中运行，拥有自己允许的工具集。它们适用于读取大量文件或需要专注而不 clutter 主对话的任务。 ``` .claude/agents/security-reviewer.md ``` ```markdown --- name: security-reviewer description: Reviews code for security vulnerabilities tools: Read, Grep, Glob, Bash model: opus --- You are a senior security engineer. Review code for: - Injection vulnerabilities (SQL, XSS, command injection) - Authentication and authorization flaws - Secrets or credentials in code - Insecure data handling Provide specific line references and suggested fixes. ``` 明确告诉 Claude 使用 subagents：*"使用 subagent 审查此代码的安全问题。"* ### 安装插件 [Plugins](https://code.claude.com/docs/en/plugins) 将 skills、hooks、subagents 和 MCP 服务器打包成来自社区和 Anthropic 的单一可安装单元。如果你使用静态类型语言，安装 [code intelligence plugin](https://code.claude.com/docs/en/discover-plugins#code-intelligence) 让 Claude 获得精确的符号导航和编辑后的自动错误检测。 关于 skills、subagents、hooks 和 MCP 的选择指导，请参阅 [Extend Claude Code](https://code.claude.com/docs/en/features-overview#match-features-to-your-goal)。 --- ## 有效沟通 你与 Claude Code 的沟通方式显著影响结果质量。 ### 询问代码库问题 onboarding 到新代码库时，使用 Claude Code 进行学习和探索。你可以问 Claude 你会问其他工程师的同类问题： - logging 是如何工作的？ - 如何创建新的 API 端点？ - `foo.rs` 第 134 行的 `async move { ... }` 是做什么的？ - `CustomerOnboardingFlowImpl` 处理了哪些边界情况？ - 第 333 行为什么调用 `foo()` 而不是 `bar()`？ 以这种方式使用 Claude Code 是有效的 onboarding 工作流，能缩短上手时间并减少其他工程师的负担。不需要特殊提示：直接提问。 ### 让 Claude 面试你 Claude 会问你还没考虑到的事情，包括技术实现、UI/UX、边界情况和权衡。 ``` 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. Don't ask obvious questions, dig into the hard parts I might not have considered. Keep inte