最佳实践

Claude Code 是一个代理式编程环境，能自主读取文件、执行命令、修改代码。与对话机器人不同，你描述目标，Claude 自己探索和实现。高效使用 Claude Code 的核心在于：提供可验证的成功标准（测试用例、截图）、利用计划模式先探索后执行、配置好项目的 CLAUDE.md 和 Skills、并主动管理上下文窗口。本文基于 Anthropic 内部团队和各类用户的实践经验总结而成。

Claude Code 是一个代理式编程环境——它不只是回答问题，而是能读取你的文件、运行命令、做改动，并自主处理问题，你可以观看、纠偏，或者直接切换任务。这改变了你的工作方式：不是自己写代码再让 Claude 审查，而是描述你想要什么，让 Claude 弄清楚怎么实现。

但这种自主性有一个学习曲线，也有一个核心约束：上下文窗口填满得很快，填满后性能下降。Claude 的上下文窗口存放整个对话——包括每条消息、每次文件读取和每个命令输出。当上下文快满时，Claude 可能开始"遗忘"早期指令或犯更多错误。

要了解上下文如何被使用，可以用自定义状态栏持续追踪用量，并参考减少 token 用量的策略。

给 Claude 一个可验证的标准

这是单一最高效的事：提供测试用例、截图或预期输出，让 Claude 能自我校验。

没有明确成功标准时，Claude 可能生成看起来正确但实际不工作的代码，你成了唯一的反馈环，每个错误都需要你介入。

策略	不好的写法	好的写法
提供验证标准	"实现验证邮箱地址的函数"	"写 validateEmail 函数。测试用例：user@example.com 返回 true，invalid 返回 false，user@.com 返回 false。实现后运行测试"
UI 变更提供截图	"把仪表盘做得更好看"	"[粘贴截图] 实现这个设计。截个结果图和原版对比，列出差异并修复"
解决根因而非症状	"构建失败了"	"构建报这个错误：[粘贴错误]。修复它并验证构建成功，解决根本原因，不要屏蔽错误"

UI 变更可以用 Chrome 中的 Claude 扩展进行验证——它在浏览器中打开新标签页、测试 UI 并迭代，直到代码能正常运行。

先探索再计划再编码

用计划模式（Plan Mode）把探索和执行分开，避免解决错误的问题。

直接让 Claude 跳到编码可能生成解决了错误问题的代码。推荐的四步工作流：

第一步：探索（Plan Mode 中）

读取 src/auth/ 了解我们如何处理会话和登录。
同时看看我们如何管理存放密钥的环境变量。

第二步：规划（Plan Mode 中）

我想添加 Google OAuth。哪些文件需要改动？
会话流程是什么？创建一个实现计划。

按 Ctrl+G 在文本编辑器中打开计划，直接编辑后再让 Claude 执行。

第三步：实现（切换回普通模式）

根据计划实现 OAuth 流程。为回调处理函数写测试，
运行测试套件并修复所有失败。

第四步：提交

用描述性信息提交，并开一个 PR

提示：范围清晰、改动小的任务（如修拼写错误、加日志、重命名变量）不需要计划模式。计划模式最适合跨多个文件的改动、不熟悉的代码库或不确定方向时。

提示词要具体

越精确的初始提示，需要的纠正越少。

策略	不好的写法	好的写法
明确范围	"给 foo.py 加测试"	"给 foo.py 写测试，覆盖用户未登录的边界情况。不用 mock"
指向来源	"ExecutionFactory 的 API 为什么这么奇怪？"	"查看 ExecutionFactory 的 git 历史，总结它的 API 是如何演变的"
引用现有模式	"加一个日历组件"	"看首页现有 widget 的实现方式，HotDogWidget.php 是好例子。按这个模式创建日历 widget，让用户选月份、向前/向后翻页选年份，不用额外库"
描述症状	"修复登录 bug"	"用户反映会话超时后登录失败。检查 src/auth/ 的认证流程，尤其是 token 刷新。先写复现问题的失败测试，再修复"

提供丰富内容：

用 @ 引用文件：@src/auth/ 让 Claude 在回答前先读文件
直接粘贴截图：复制/粘贴或拖放图片到提示框
给 URL：提供文档和 API 参考链接。用 /permissions 将常用域名加入白名单
管道输入数据：cat error.log | claude 直接传文件内容
让 Claude 自取所需：告诉 Claude 用 Bash 命令、MCP 工具或文件读取来主动拉取上下文

配置好你的环境

以下几步可以让 Claude Code 在所有会话中都更高效。关于各扩展功能的完整说明，参见扩展 Claude Code。

写有效的 CLAUDE.md

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时都会读取。在其中写 Bash 命令、代码风格和工作流规则，给 Claude 代码本身无法推断的持久上下文。/init 命令会分析你的代码库来检测构建系统、测试框架和代码模式，给你一个坚实的起点。

CLAUDE.md 没有固定格式，但要保持简短可读：

markdown

# 代码风格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 尽量使用解构导入（如 import { foo } from 'bar'）

# 工作流程
- 做完一系列代码改动后记得做类型检查
- 优先运行单个测试，不要跑整个测试套件，性能更好

CLAUDE.md 在每次会话时都会加载，所以只包含广泛适用的内容。对于只在特定情况下有用的领域知识或工作流，用 Skills 代替——它们按需加载，不会撑大每次对话。

保持精简。对每一行问："删掉这行 Claude 会犯错吗？" 如果不会，删掉。臃肿的 CLAUDE.md 会让 Claude 忽略你真正想要的指令！

✅ 应该包含	❌ 不应该包含
Claude 猜不到的 Bash 命令	Claude 读代码就能发现的内容
与默认值不同的代码风格规则	标准语言约定（Claude 已知道）
测试指令和首选测试框架	详细的 API 文档（链接过去即可）
分支命名、PR 规范等仓库礼仪	频繁变化的信息
项目特有的架构决策	文件级别的详细描述
开发环境特殊要求（必需环境变量）	"写干净的代码"之类的废话

可以加强关键指令的力度（如 "重要：" 或 "你必须："）以提高遵守率。把 CLAUDE.md 提交到 git，团队可以共同贡献，这个文件会随时间变得越来越有价值。

CLAUDE.md 支持 @path/to/import 语法引入额外文件：

markdown

参见 @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 Code 会为可能修改系统的操作请求确认（文件写入、Bash 命令、MCP 工具等）。这很安全但很繁琐——确认到第十次你其实已经不是在真正审查了，只是在点击通过。有三种方式减少打扰：

自动模式：由独立分类器模型审查命令，只阻断真正有风险的操作（权限提升、未知基础设施、恶意内容驱动的操作）
权限白名单：把你知道安全的工具加入白名单，如 npm run lint 或 git commit
沙箱：开启操作系统级别的隔离，限制文件系统和网络访问，让 Claude 在定义好的边界内更自由地工作

详见权限模式、权限规则和沙箱。

使用 CLI 工具

CLI 工具是与外部服务交互时最节省上下文的方式。如果你用 GitHub，安装 gh CLI。Claude 知道如何用它创建 issue、开 PR、读评论。没有 gh 时 Claude 也能用 GitHub API，但未认证请求容易触发限速。

Claude 学习不认识的 CLI 工具效果很好："用 'foo-cli-tool --help' 了解 foo 工具，然后用它完成 A、B、C"

连接 MCP 服务器

通过 MCP 服务器，你可以让 Claude 实现来自 issue 追踪器的功能、查询数据库、分析监控数据、从 Figma 整合设计稿、自动化工作流。

配置 Hooks

Hooks 在 Claude 工作流的特定时点自动运行脚本。与 CLAUDE.md 指令不同（建议性的），Hooks 是确定性的——它们保证某些操作一定会发生。Claude 可以帮你写 Hooks，试试这样的提示："写一个每次文件编辑后运行 eslint 的 Hook" 或 "写一个阻止写入 migrations 文件夹的 Hook"。直接编辑 .claude/settings.json 手动配置，运行 /hooks 查看已配置的内容。

创建 Skills

Skills 用项目、团队或领域专属的信息扩展 Claude 的知识库。相关时 Claude 自动应用，也可以用 /skill-name 直接调用。在 .claude/skills/ 中创建一个包含 SKILL.md 的目录即可：

markdown

---
name: api-conventions
description: 我们服务的 REST API 设计约定
---
# API 约定
- URL 路径使用 kebab-case
- JSON 属性使用 camelCase
- 列表接口始终包含分页
- URL 路径中加版本号（/v1/、/v2/）

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

markdown

---
name: fix-issue
description: 修复 GitHub issue
disable-model-invocation: true
---
分析并修复 GitHub issue：$ARGUMENTS

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

运行 /fix-issue 1234 调用。对于有副作用、需要手动触发的工作流，使用 disable-model-invocation: true。

创建自定义子代理

子代理在独立上下文中运行，有独立的允许工具集。适合读取大量文件或需要专项聚焦而不污染主对话的任务：

markdown

---
name: security-reviewer
description: 审查代码中的安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---
你是一位高级安全工程师。审查代码的以下方面：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 代码中的密钥或凭证
- 不安全的数据处理

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

明确让 Claude 使用子代理："用子代理审查这段代码的安全问题。"

有效沟通

让 Claude 采访你

对于较大的功能，先让 Claude 提问，再动手：

我想构建 [简短描述]。用 AskUserQuestion 工具详细采访我。

问我技术实现、UI/UX、边界情况、关注点和权衡取舍。
别问显而易见的，深挖我可能没想到的难题。

持续采访直到覆盖所有方面，然后把完整规格写到 SPEC.md。

规格完成后开新会话来执行——新会话有干净的上下文，专注于实现，你也有了可参考的书面规格。

问代码库问题

把 Claude Code 当有经验的同事来用，直接问：

日志是怎么工作的？
怎么新建一个 API 接口？
foo.rs 第 134 行的 async move { ... } 是什么意思？
CustomerOnboardingFlowImpl 处理了哪些边界情况？

这是快速熟悉新代码库的有效方式。

会话管理

及早纠偏

发现 Claude 走错方向就立刻纠正，不要等它完成：

Esc：停止当前操作，保留上下文，重新引导
Esc + Esc 或 /rewind：打开回退菜单，恢复到之前的会话和代码状态
/clear：重置上下文，在无关任务之间使用

如果连续纠正 Claude 两次以上还是不对，说明上下文被失败的方法污染了。运行 /clear 重新开始，写一个更具体、包含了你学到的教训的提示。

积极管理上下文

上下文是最宝贵的资源：

无关任务之间用 /clear 重置
长会话中用 /compact <重点> 手动压缩，如 /compact 专注于 API 改动
用 /btw <问题> 问快速问题，答案不会进入对话历史
把持久规则写进 CLAUDE.md，而不是依赖对话历史

用子代理调查

让子代理探索代码库，避免污染主对话上下文：

用子代理调查我们的认证系统如何处理 token 刷新，
以及是否有我应该复用的现有 OAuth 工具。

子代理在独立上下文中工作，完成后汇报摘要，不会撑大你的主对话。

自动化和扩展

非交互式模式

用 claude -p "提示" 集成到 CI 流水线、pre-commit hook 或脚本：

bash

# 一次性查询
claude -p "解释这个项目做什么"

# 脚本解析用结构化输出
claude -p "列出所有 API 端点" --output-format json

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

并行运行多个会话

三种方式：

桌面应用：可视化管理多个本地会话
Claude Code Web：在 Anthropic 云端运行
代理团队：自动协调多个会话，有共享任务和领头代理

并行会话还能用于质量工作流，如 Writer/Reviewer 模式：

Session A（Writer）：实现功能
Session B（Reviewer）：用新鲜视角审查代码

故障排查题模式

厨房水槽会话：同一个会话处理不相关的任务 → 任务之间运行 /clear
反复纠正：Claude 做错了，纠正，还是错，再纠正 → 两次失败后 /clear 并写更好的初始提示
CLAUDE.md 过于臃肿：太长导致 Claude 忽略一半内容 → 大幅删减，对每行问"删掉会怎样"
信任-验证缺口：Claude 生成看起来合理但没处理边界情况的实现 → 始终提供验证（测试、脚本、截图）
无限探索：没有范围限制地让 Claude 调查，它读了上百个文件塞满上下文 → 用子代理隔离探索，或者缩小调查范围

常见问题

Q: Claude Code 最重要的一个实践是什么？

提供可验证的成功标准——测试用例、截图或预期输出。这是单一最高效的事：让 Claude 能自我校验，避免你成为唯一的反馈环。

Q: 什么时候应该用计划模式（Plan Mode）？

跨多个文件的改动、不熟悉的代码库、或不确定方向时使用计划模式。小型、范围清晰的改动（修拼写、加日志）直接做更快。

Q: CLAUDE.md 文件应该写多长？

目标控制在 200 行以内。文件越长，Claude 遵守的可靠性越低。对每一行问："删掉这行 Claude 会犯错吗？" 如果不会，删掉。

Q: Skills 和 CLAUDE.md 有什么区别？

CLAUDE.md 在每次会话时都加载，适合广泛适用的基础规则。Skills 按需加载，适合只在特定任务时才需要的领域知识或可重复工作流，避免每次都占用上下文。

Q: 如何避免 Claude Code 对话上下文被填满？

任务之间用 /clear 重置，长会话中用 /compact 压缩，用 /btw 问临时问题，用子代理隔离大量文件的探索工作。持续追踪上下文用量，避免在最后 20% 的上下文空间内开始大规模任务。

最佳实践 ​

给 Claude 一个可验证的标准 ​

先探索再计划再编码 ​

提示词要具体 ​

配置好你的环境 ​

写有效的 CLAUDE.md ​

配置权限 ​

使用 CLI 工具 ​

连接 MCP 服务器 ​

配置 Hooks ​

创建 Skills ​

创建自定义子代理 ​

有效沟通 ​

让 Claude 采访你 ​

问代码库问题 ​

会话管理 ​

及早纠偏 ​

积极管理上下文 ​

用子代理调查 ​

自动化和扩展 ​

非交互式模式 ​

并行运行多个会话 ​

故障排查题模式 ​

相关资源 ​

常见问题 ​

最佳实践

给 Claude 一个可验证的标准

先探索再计划再编码

提示词要具体

配置好你的环境

写有效的 CLAUDE.md

配置权限

使用 CLI 工具

连接 MCP 服务器

配置 Hooks

创建 Skills

创建自定义子代理

有效沟通

让 Claude 采访你

问代码库问题

会话管理

及早纠偏

积极管理上下文

用子代理调查

自动化和扩展

非交互式模式

并行运行多个会话

故障排查题模式

相关资源

常见问题