这是 Anthropic 官方文档 Best Practices 页面的完整整理，来自 Anthropic 内部工程团队和大量真实用户经验的总结。涵盖从环境配置到大规模自动化的全套黄金法则，是最权威的 Claude Code 使用指导。
核心约束：理解上下文窗口
所有最佳实践都基于同一个约束：上下文窗口填满得很快，填满后性能下降。
Claude 的上下文窗口保存完整对话——每条消息、每次文件读取、每条命令输出。一次调试会话或代码库探索可能消耗数万 Token。
上下文快满时的症状：Claude 开始"忘掉"早期指令，错误率上升，回答质量下降。
解决思路：主动管理上下文，不要被动等待降级。
一、给 Claude 提供可验证标准（最高杠杆）
这是所有实践里影响最大的单一改变。
当 Claude 能自己验证工作结果时（运行测试、对比截图、检查输出），表现会显著提升。没有验证标准，Claude 可能产出看起来正确但实际有问题的结果，你成为唯一的反馈循环。
| 策略 | 模糊指令 | 精确指令 |
|---|---|---|
| 提供验证标准 | "实现一个邮件验证函数" | "写 validateEmail 函数。测试用例：user@example.com→true, invalid→false, user@.com→false。实现后运行测试" |
| 可视化验证 UI 变更 | "把仪表盘做好看一点" | "[粘贴截图] 实现这个设计。截图对比原设计，列出差异并修复" |
| 解决根本原因 | "构建失败了" | "构建报这个错误：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要压制错误" |
验证可以是测试套件、Linter、Bash 命令，或者 Claude for Chrome 扩展（直接在浏览器里测试 UI）。投资在让验证本身更可靠上。
二、探索 → 规划 → 实现 四步流程
让 Claude 直接跳到编码，可能解决了错误的问题。用 Plan Mode 分离探索和实现。
推荐的四个阶段
阶段 1：探索（Plan Mode 只读）
读取 /src/auth，理解我们如何处理会话和登录。
也看看我们如何管理 secrets 的环境变量。
阶段 2：规划（Plan Mode）
我想添加 Google OAuth。哪些文件需要修改？
会话流程是什么？创建一个实现计划。
按 Ctrl+G 在外部编辑器里打开计划，可以直接编辑后再让 Claude 执行。
阶段 3：实现（退出 Plan Mode）
按照计划实现 OAuth 流程。为 callback handler 写测试，
运行测试套件并修复所有失败。
阶段 4：提交
用描述性的 commit 消息提交，创建 PR
什么时候跳过规划：任务范围清晰、修改很小（改个变量名、加一行日志）时，直接实现。规划适合：不确定方案、修改跨多个文件、不熟悉被修改的代码。
三、精准提示的四个策略
| 策略 | 模糊 | 精准 |
|---|---|---|
| 限定范围 | "给 foo.py 加测试" | "为 foo.py 写测试，覆盖用户已登出时的边界情况，避免 mock" |
| 指向信息来源 | "为什么 ExecutionFactory 的 API 这么奇怪？" | "查看 ExecutionFactory 的 git 历史，总结其 API 演变过程" |
| 引用已有模式 | "添加日历组件" | "看 home page 上现有 widget 的实现（HotDogWidget.php 是好例子），按照这个模式实现一个允许用户选择月份的新日历 widget" |
| 描述症状 | "修复登录 Bug" | "用户反馈会话超时后登录失败。检查 src/auth/ 里的认证流程，特别是 token 刷新。先写一个能复现问题的失败测试，然后修复" |
模糊提示也有价值：在探索阶段，"你会改进这个文件的什么？"这样的开放问题能发现你没想到的问题。
四、丰富上下文输入
- 用
@引用文件：Claude 在回答前先读取文件，比描述"在某个文件里"更精确 - 直接粘贴图片：复制粘贴或拖拽图片到输入框
- 给 URL：文档和 API 参考直接给链接，用
/permissions设置常用域名白名单 - 管道传数据：
cat error.log | claude直接发送文件内容 - 让 Claude 自己拉取：告诉 Claude 通过 Bash 命令、MCP 工具或读文件来获取所需上下文
五、写好 CLAUDE.md（环境配置最高优先级）
运行 /init 自动生成基础 CLAUDE.md，然后持续精化。
好的 CLAUDE.md 模板：
# Code style
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 尽量解构导入（eg. import { foo } from 'bar'）
# Workflow
- 做完一系列代码修改后记得做类型检查
- 优先运行单个测试，不要跑整个测试套件（为了性能）什么该放：
| ✅ 放入 | ❌ 排除 |
|---|---|
| Claude 猜不到的 Bash 命令 | Claude 读代码就能推断的内容 |
| 与默认不同的代码风格规则 | 语言的标准约定 |
| 测试指令和首选测试运行器 | 详细 API 文档（链接代替） |
| 仓库规范（分支命名、PR 约定） | 频繁变化的信息 |
| 项目特有的架构决策 | 逐文件的代码库描述 |
| 开发环境的特殊要求 | "写整洁的代码"这类不言而喻的规范 |
CLAUDE.md 太长的信号：
- Claude 持续做你不想要的事，尽管有规则
- Claude 问了 CLAUDE.md 已经回答的问题
用 @path/to/file 语法引入其他文件，保持 CLAUDE.md 简洁：
查看 @README.md 了解项目概览，@package.json 了解可用的 npm 命令。
# 额外指令
- Git 工作流：@docs/git-instructions.md六、精确设置权限
预设允许/拒绝列表，避免每次被询问：
// .claude/settings.json
{
"permissions": {
"allow": [
"Read",
"Bash(git *)",
"Bash(npm run *)",
"Bash(docker compose *)"
],
"deny": [
"Bash(rm -rf *)"
]
}
}或通过 CLI：
claude --allowedTools "Read,Bash(git *)"
claude --disallowedTools "Bash(rm:*),Bash(sudo:*)"七、善用 CLI 工具
把常用 CLI 工具放到 CLAUDE.md 里，Claude 就会在合适时机调用它们：
## 可用工具
- `gh` - GitHub CLI（用于 PR、Issues、CI 状态）
- `jq` - JSON 处理
- `ripgrep (rg)` - 比 grep 快的搜索工具
- `fd` - 更好的 find 替代八、连接 MCP 服务器
MCP 服务器给 Claude 额外的工具和上下文，比描述数据结构更直接：
# 在 Claude Code 内运行
claude mcp add postgres \
--command "npx" \
--args '["-y","@modelcontextprotocol/server-postgres"]' \
--env "DATABASE_URL=postgresql://..."最有价值的 MCP 服务器：PostgreSQL（直接查询数据库）、GitHub（PR 和 Issue 管理）、Brave Search（实时网页搜索）。
注意 Token 开销：每个 MCP 服务器的工具目录都会计入每次请求的上下文，只安装真正使用的。
九、设置 Hooks 实现自动化
Hooks 在特定事件时自动运行：
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npm run lint --fix 2>/dev/null || true"
}]
}]
}
}常用场景：文件修改后自动 lint、commit 前强制测试、Auto Mode 拒绝时发通知。
十、创建 Skills（按需加载的工作流模板）
Skills 在需要时加载到上下文，不会像 CLAUDE.md 一样每次都占用 Token：
<!-- ~/.claude/skills/deploy-check/SKILL.md -->
---
description: 部署前检查清单
---
部署前必须验证：
1. 所有测试通过
2. 无 TODO 注释残留在核心路径
3. 环境变量已设置
4. 数据库迁移已准备好CLAUDE.md vs Skills 的选择：
- 每次会话都需要 → CLAUDE.md
- 特定场景下才需要 → Skills
十一、安装插件（Plugins）
插件是 MCP 服务器，给 Claude 新工具：
# 从 Marketplace 安装
claude plugin install @anthropic-ai/skill-creator
# 从 URL 安装（v2.1.129 新增）
claude --plugin-url https://example.com/my-plugin.zip最值得安装的插件：Firecrawl（网页抓取）、Playwright（浏览器自动化）、官方 Skill Creator（创建新 Skills）。
十二、高效沟通技巧
让 Claude 先问问题
在开始实现前，先问我所有你需要的信息，然后再开始
问代码库问题
Claude 擅长探索你自己都不熟悉的代码库：
这个模块的架构思路是什么？
这里有什么已知的陷阱吗？
为什么这段代码这样设计？
十三、会话管理
提前纠正方向
在会话进行到深处时纠偏成本很高。当看到 Claude 走偏：
- 立即打断（
Ctrl+C） - 描述你想要的结果，而不是纠正过程
- 让 Claude 重新规划
激进管理上下文
/compact # 每 30-40 条消息主动运行
/clear # 完全切换任务时
/compact 保留：正在修改 auth.ts 的 JWT 验证逻辑，还需处理 refresh token
用 Subagents 做调研
让调研任务在独立上下文里运行，结果不污染主会话：
> 用 subagent 探索 src/api/ 的所有路由，汇报结构和各路由的用途
Checkpoints 和 Rewind
双击 Escape 回退到上一个 Checkpoint。大胆实验，随时撤销。
恢复会话
claude -c # 继续最近一次会话
claude -r "名称" # 恢复指定名称的会话十四、自动化和规模化
非交互模式（Print Mode）
git diff main | claude -p "检查安全问题"
cat error.log | claude -p "分析这个崩溃的原因"
claude -p "列出所有 TODO 注释" --output-format json多个并行 Claude 会话
# 在不同目录用多个终端窗口/tmux pane
# 或用 git worktree 分离工作区
claude -w feature-a # Terminal 1
claude -w feature-b # Terminal 2跨文件扩展（/batch）
/batch 把 src/ 下所有 .js 文件里的 var 改为 const 或 let
Auto Mode 自主运行
claude --permission-mode auto分类器自动决定安全操作直接允许、风险操作阻断。替代 --dangerously-skip-permissions 的更安全选项。
十五、避免常见失败模式
| 失败模式 | 正确做法 |
|---|---|
| 等 Claude 完成再发现方向错了 | 提前规划，Plan Mode 先探索 |
| 对话越来越长却不清理 | 主动 /compact，任务切换用 /clear |
| CLAUDE.md 越写越长 | 定期审查，删掉不必要的规则 |
| 把所有信息放 CLAUDE.md | 常用的放 CLAUDE.md，场景化的放 Skills |
| 使用太多 MCP 服务器 | 只安装实际用到的 |
| 直接用 --dangerously-skip-permissions | 用 Auto Mode 替代 |
来源：Claude Code 官方 Best Practices 文档 | 整理：ClaudeEagle