最佳实践

Claude Code 是一个 AI 代理，不只是回答问题——它能读取文件、运行命令、自主工作。这改变了你的工作方式：不是自己写代码让 Claude 审查，而是描述你想要什么，让 Claude 弄清楚怎么构建。

但使用好 Claude Code 是有技巧的，核心约束是：上下文窗口很快就会填满，填满后性能下降。

给 Claude 一个可验证的标准

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

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

策略	不好的写法	好的写法
提供验证标准	"实现验证邮箱地址的函数"	"写 validateEmail 函数。测试用例：user@example.com 返回 true，invalid 返回 false，user@.com 返回 false。实现后运行测试"
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 在回答前先读文件
直接粘贴截图：复制/粘贴或拖放图片到提示框
管道输入数据：cat error.log | claude 直接传文件内容

配置好你的环境

写有效的 CLAUDE.md

运行 /init 自动生成项目的 CLAUDE.md 起始文件，再根据实际情况完善。

核心原则：简短可读，对每一行问："删掉这行 Claude 会犯错吗？" 如果不会，删掉。臃肿的 CLAUDE.md 反而让 Claude 忽略你真正想要的指令！

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

可以加强关键指令的力度，如 "重要：" 或 "你必须："。

CLAUDE.md 支持 @path 引入额外文件，保持主文件精简。

配置权限

用 /permissions 将安全命令加入白名单（如 npm run lint、git commit），减少不必要的确认弹窗。

或者用 /sandbox 开启操作系统级别的隔离，让 Claude 在定义好的边界内更自由地工作。

使用 CLI 工具

告诉 Claude 用 CLI 工具和外部服务交互，如 gh（GitHub）、aws、gcloud。没有 gh 的话 Claude 也能用 GitHub API，但未认证请求容易触发限速。

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

连接 MCP 服务器

运行 claude mcp add 连接外部工具（Notion、Figma、数据库等），让 Claude 可以查询数据库、分析监控数据、整合设计稿。

创建 Skills

在 .claude/skills/ 中创建 SKILL.md 文件，给 Claude 项目特定的领域知识和可复用的工作流。技能按需加载，不会每次都占用上下文。详见 Skills 系统。

有效沟通

问代码库问题

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

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

这是快速熟悉新代码库的有效方式，能减少询问其他工程师的需求。

让 Claude 采访你

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

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

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

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

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

会话管理

及早纠偏

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

Esc：停止当前操作，保留上下文，重新引导
Esc + Esc 或 /rewind：打开回退菜单，恢复到之前的会话和代码状态
"撤销那个改动"：让 Claude 回滚
/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 调查，它读了上百个文件塞满上下文 → 用子代理隔离探索，或者缩小调查范围

最佳实践 ​

给 Claude 一个可验证的标准 ​

先探索再计划再编码 ​

提示词要具体 ​

配置好你的环境 ​

写有效的 CLAUDE.md ​

配置权限 ​

使用 CLI 工具 ​

连接 MCP 服务器 ​

创建 Skills ​

有效沟通 ​

问代码库问题 ​

让 Claude 采访你 ​

会话管理 ​

及早纠偏 ​

积极管理上下文 ​

用子代理调查 ​

自动化和扩展 ​

非交互式模式 ​

并行运行多个会话 ​

常见问题模式 ​

相关资源 ​