第十一章 避坑指南

一、为什么要专门讲坑

工具越强大，能踩的坑越多。Claude Code 是一个真正"能动手"的 AI Agent，它能 rm -rf、能 git push、能给客户发邮件、能调你的银行 API——所以一旦它"误会了你的意思"，后果可能比 ChatGPT 写错一段文案严重得多。

但任何工具都有它的"安全使用方法"。开车有交规，操作大型机械有 SOP，使用 Claude Code 也有一套"老司机才知道的边界"。这些边界不是 Anthropic 文档第一页就告诉你的，是社区几十万用户用真实损失换来的经验。

本章把这些经验集中起来。读完之后你会获得三件事：

1. 8 大坑的"早期识别能力"——感觉不对就停手，比掉进去再爬出来省 10 倍时间。
2. 报错对照表——遇到红字不慌，60 多条常见报错都能查到原因和解法。
3. 紧急按钮清单——出问题第一时间知道按哪个键、跑哪个命令。

社区里流传一句话："Claude Code 用得好的人不是没踩过坑，而是踩过的坑都变成了肌肉记忆。"看完这一章，希望你能少花 3 个月走弯路。

二、新手 8 大坑（最常见、最致命）

按"出现频率 × 严重程度"排序。

坑 1：以为 Claude 啥都懂，不给上下文

现象：

你在新项目里第一次启动 claude，直接说："帮我把首页加一个用户登录功能。"

Claude 兴致勃勃地动手，10 分钟后给你写了一堆代码——用了 React，可你的项目是 Vue；用了 PostgreSQL，可你用 MongoDB；用了 JWT，可公司规范用 Session。

你愤怒地说："你怎么不问我？"

原因：

Claude 不会"主动问"你它本来就该知道的事。它默认你给的上下文足够，缺什么它会"自由发挥"。在缺乏 CLAUDE.md、不用 @ 引用文件、不说技术栈的情况下，"自由发挥"的结果就是和你的预期完全不沾边。

对策：

回到第四章温习一遍：

• 在项目根目录跑 /init，让 Claude 先扫描代码生成基础 CLAUDE.md。
• 在 CLAUDE.md 写清技术栈、命名约定、永远不要做的事。
• 说话时用 @路径 引用关键文件，让 Claude "看见"而不是"猜"。
• 复杂任务用 ROCFE 五要素结构化提示词。

真实例子（脱敏）：

知乎一位读者反馈："我让 Claude 改一段商品价格计算逻辑，没说我们用的是欧元区分两位小数还是按整数分（cent）存储。它默认按欧元改了，结果那天晚上线上所有订单金额变成了原来的 1/100。"

修复花了一个通宵 + 紧急公告。如果 CLAUDE.md 有一行 # 金额单位永远是 cent（int），不要用 float，这个事故根本不会发生。

坑 2：让 Claude 跑没有 dry-run 的危险任务

现象：

"请把 ~/Downloads 里的旧文件归档到 ~/Archive"——你以为它会动 ~/Downloads，结果它把整个 ~ 目录下"看起来旧的"都归档了，包括你的 Documents、Desktop、Pictures。

更惨的是它做完才告诉你："已归档 4,832 个文件。"

原因：

Claude 的"理解"和你的"意图"之间永远有一道缝。这道缝在简单任务里不致命，在涉及"批量删除/移动/覆盖"的任务里就是灾难。

对策：

给所有写操作加一道"刹车"：

1. 提示词里明确要求 dry-run：

   请整理 ~/Downloads，按类型分到子文件夹。
   先用 dry-run 模式列出"打算移动哪些文件到哪里"，等我确认后再真正移动。
   

2. PreToolUse Hook 拦截危险命令（参考第十章配置示例）：

   {
     "PreToolUse": [{
       "matcher": "Bash",
       "hooks": [{
         "type": "command",
         "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -E 'rm -rf|mv \\$HOME|sudo'; then echo BLOCKED; exit 1; fi"
       }]
     }]
   }
   

3. 危险目录用白名单：在 settings.json 里 permissions.deny 写明 Edit($HOME/Pictures/**) Edit($HOME/Documents/**)。

4. 真的动手前问自己一句：如果它执行错了，我能恢复吗？不能恢复就先 dry-run。

坑 3：超长会话不 /compact，直到崩溃

现象：

你在一个会话里干了三天，从修 bug 一路干到加新功能，再到重构架构。突然某一刻 Claude 开始"傻了"——回答前后矛盾、忘了自己刚说过什么、给的代码引用了不存在的文件。同时账单飞涨。

你跑 /cost 一看，单次会话已经吃了 $30。

原因：

Claude Code 的"上下文窗口"虽然大（Sonnet 4.5 是 200K token），但每一轮对话都把之前的全部内容重发一次给模型。会话越长，单次请求越贵、越慢，模型也越容易"丢三落四"。

对策：

养成 3 个习惯：

1. 每 10-15 轮 /compact 一次：把历史压缩成"要点摘要 + 当前状态"。
2. 任务结束 /clear：彻底清空，开下一个任务。
3. 大任务前看 /cost：单次会话超过 $5 就该警觉了。

什么时候该 /compact，什么时候该 /clear？

坑 4：把 Claude 当人，给情绪化指令

现象：

"你能不能用心点啊？我都说三遍了！" "你这个废物再这样我要换 GPT 了。" "求求你了，写对一次行不行？"

效果——Claude 还是该错怎么错。

原因：

模型对人类情绪没有反应。它只对指令的结构清晰度敏感。你越情绪化，越不可能写出结构清晰的指令，结果只会更糟。

对策：

感觉自己开始要爆炸时，做三件事：

1. 离开终端 5 分钟，喝杯水。
2. 用 ROCFE 五要素重新组织指令：
   • Role: 你是谁
   • Objective: 我想要什么
   • Constraint: 不能做什么
   • Format: 输出长什么样
   • Example: 给一个理想样本
3. 如果还是错，换 Opus 跑一遍——也许是 Sonnet 真的搞不定这个任务。

记住：模型不会因为你礼貌而更卖力，但你会因为礼貌而思路更清楚。情绪化的指令本质是思路混乱的征兆，对自己说话好一点是为了帮自己。

坑 5：MCP 装太多

现象：

你心血来潮一口气装了 20 个 MCP（GitHub、Slack、Notion、飞书、Linear、Jira、Postgres、MySQL、SQLite、Redis、Mongo、Stripe、Twilio、Brave Search、Exa、Tavily、Playwright、Puppeteer、Figma、Google Drive……）。

结果：

• claude 启动从 1 秒变成 8 秒
• 系统提示词变得超长，每次请求多花 ~5,000 token
• Claude 开始"选错工具"——明明该用 Read 它非要去 GitHub 上找

原因：

每个 MCP 都会向 Claude 注册它的工具列表 + 文档说明。装 20 个 MCP 等于在系统提示词里塞了一份 200 页的"工具手册"。Claude 每次回答都要先"翻一遍这本手册"，自然又慢又乱。

对策：

1. 常用 MCP 控制在 6 个以内。
2. 按项目装：把 MCP 写进 .mcp.json（项目级），而不是 ~/.claude/settings.json（全局）。
3. 临时用临时装：

   /mcp add slack
   # 用完
   /mcp remove slack
   

4. 定期清理：每月跑 /mcp list 看哪些三个月没用了。

坑 6：Hook 写错导致死循环

现象：

你给 PostToolUse 加了一个 Hook："Claude 写完文件后自动 git commit"。

Claude 写了一个 README.md → Hook 触发 git commit → commit 改了 .git/index → Hook 又触发（因为它检测到文件变化）→ ……

10 分钟后你的 git 历史里多了 8,000 个空 commit，CPU 100%，硬盘狂转。

原因：

Hook 是"事件 → 动作"的简单触发，不会自动判断"这次事件是不是我自己导致的"。如果 Hook 的动作又触发同类事件，就会死循环。

对策：

1. Hook 加防自触发条件：

   # 检查这次写入的不是 .git 目录
   if echo "$CLAUDE_TOOL_OUTPUT_FILE" | grep -q "^\.git/"; then exit 0; fi
   

2. 写 Hook 用 dry-run：先把动作改成 echo "would do XXX" 跑一天，确认不会失控再改回真的动作。

3. Hook 写 max-execution-count：用文件计数器或时间戳限制"5 分钟内最多触发 N 次"。

4. 配套快捷键：在另一个终端窗口准备好 pkill -f claude，万一失控立刻按。

坑 7：API Key 泄露

现象：

你把项目 push 到 GitHub，三天后 Anthropic 给你发邮件："您的 API Key 在过去 24 小时产生了 $1,247 异常调用，已自动暂停。"

打开 GitHub 一看，你的 .env 文件被你不小心提交了，里面 ANTHROPIC_API_KEY=sk-ant-xxx 暴露在 100 万 GitHub 搜索者眼前。

原因：

GitHub 上有自动扫描器 24 小时盯着新提交的代码找 API Key（黑客的、安全公司的、Anthropic 自己的都有）。Key 一旦提交，从泄露到被滥用通常不超过 1 小时。

对策：

详见第十章，这里只重申最关键三条：

1. .env 必须在 .gitignore 里。新项目第一件事是 echo ".env" >> .gitignore。
2. API Key 用环境变量或 Keychain，绝对不写进任何会被提交的文件。
3. Anthropic Console 设 Hard Limit：哪怕真的泄露，损失上限可控。

万一泄露：立刻去 console 撤销 → 创建新 Key → 检查账单 → 改密码 → 申请客服豁免（24 小时内有机会）。

坑 8：版本不兼容

现象：

你用了一年的某个 MCP，今天突然报 protocol version mismatch。原因：Claude Code 从 2.4.x 升级到 2.5.x，MCP 协议小版本变了，那个 MCP 还没适配。

对策：

1. 大版本升级前先看 changelog：claude changelog 或访问 docs.claude.com/changelog。
2. MCP / Skill 锁版本：在配置里写明 @1.2.3 而不是 latest。
3. 出问题立刻回滚：claude rollback 回到上一个稳定版。
4. 生产环境分阶段升级：个人电脑先试 1 周，没问题再升公司机器。

三、按报错查解决：完整对照表

把这一节当字典用。所有报错按"出现阶段"分类。

3.1 安装阶段

3.2 登录阶段

3.3 运行阶段

3.4 自动化阶段

3.5 编辑器集成阶段

四、性能与成本调优 7 条铁律

降低账单 + 提升速度同时奏效的 7 个习惯：

铁律 1：用 Haiku 做"简单任务"

简单 = "Claude 不需要思考太多就能给答案"，比如：

• 把一段文本分类成 5 个标签之一
• 从一段非结构化文本里抽 JSON
• 把短文本翻译成另一种语言
• 简单的"是/否"判断

切换：/model haiku

省钱效果：Haiku 比 Sonnet 便宜 75%，速度快 2 倍。

铁律 2：用 Sonnet 4.5 做"日常任务"

日常 = "需要一定推理但不算复杂"，包括：

• 写代码、改代码、读代码
• 多轮对话
• 文件操作
• 大多数 MCP 调用

切换：/model claude-sonnet-4-5（也是默认）。

铁律 3：只有架构 / Plan Mode 才用 Opus

Opus 4.7 比 Sonnet 贵 5 倍，慢 2 倍，但在以下场景值得：

• 架构设计、系统重构
• 复杂的代码审查（找出隐藏 bug）
• Plan Mode 做长链规划
• 对话陷入"Sonnet 总是搞不对"的死胡同时，换 Opus 试一次

切换：/model opus。

铁律 4：Subagents 强制用 Haiku

在 .claude/agents/<name>.md 里指定模型：

---
name: code-formatter
description: 格式化代码
model: claude-haiku-4-5
---

这样主 Agent 用 Sonnet 思考，分发给 Subagent 的繁琐工作用 Haiku 做。综合成本可降低 60%。

铁律 5：大文件用 @ 引用而不是粘贴

错：把整个 package.json（200 行）粘到对话里。 对：说 @package.json，Claude Code 会智能截取相关部分（用 Prompt Caching）。

省钱效果：Prompt Caching 命中时 90% 折扣。

铁律 6：长会话每 10 轮 /compact

/compact 把历史压缩成 ~500 token 的摘要。10 轮长对话原本可能占 30,000 token，压缩后只剩 5,000，单次请求成本降 80%。

铁律 7：批量任务用 Batch API

如果你有 1,000 个独立任务（如批量打标签、批量翻译），用 Anthropic 的 Batch API 提交，自动 50% 折扣。

Claude Code 不直接支持 Batch API，但你可以让 Claude 帮你写一个 Python 脚本调 Batch API，跑大批量任务时单独用。

成本对比示例：

五、claude doctor 输出全解读

claude doctor 是排查问题的第一步，所有检查项及含义：

Claude Code Doctor (v2.5.3)
================================

[ Environment ]
✓ Node.js: v22.12.0 (>= 18 required)
✓ OS: macOS 14.5.1 Sonoma
✓ Architecture: arm64
✓ Shell: zsh 5.9
✓ Locale: zh_CN.UTF-8

[ Configuration ]
✓ Config directory: ~/.claude (exists, 142 MB)
✓ Settings file: ~/.claude/settings.json (valid JSON)
✓ User CLAUDE.md: ~/.claude/CLAUDE.md (174 lines)
⚠ Project CLAUDE.md: not found in current directory
✓ Permissions: default mode

[ Authentication ]
✓ Logged in as: cassius@example.com
✓ Plan: Pro
✓ Subscription valid until: 2026-12-31
✓ API Key fallback: configured

[ Network ]
✓ api.anthropic.com reachable (latency: 145ms)
✓ console.anthropic.com reachable
✓ statuspage.io: all systems operational

[ Extensions ]
✓ MCP servers: 5 configured, 5 healthy
  - github (v1.4.2)
  - filesystem (v1.0.7)
  - postgres (v2.1.0)
  - playwright (v0.8.3)
  - notion (v1.2.0)
✓ Skills: 12 loaded
✓ Hooks: 3 active (1 PreToolUse, 2 PostToolUse)
✓ Subagents: 4 defined
✓ Slash commands: 8 custom + 28 built-in

[ Storage ]
✓ Logs: ~/.claude/logs (32 MB, 30 days retention)
✓ Projects history: ~/.claude/projects (89 MB, 14 projects)
⚠ Shell snapshots: ~/.claude/shell-snapshots (15 MB)
   → Recommend: cleanup older than 30 days

[ Recommendations ]
1. Add a project CLAUDE.md to current directory (run /init)
2. Run `claude logs --cleanup --older-than 30d` to free disk

每项颜色含义：

红色 ✗ 对应的修复指令：

六、当 Claude "卡住"了：5 种紧急按钮

按响应速度从快到慢排：

1. Esc（最常用）

立刻中断当前操作。Claude 正在调工具？立刻停。Claude 正在写文件？停在当前位置。

98% 的"卡住"用 Esc 就够了。

2. Ctrl + C

强制退出 claude 命令。如果 Esc 没反应（罕见），用这个。代价：当前会话上下文丢失。

3. /clear

清空当前会话的上下文，但保留 CLAUDE.md 和配置。适用于：

• 上下文乱了
• 切换到完全无关的新任务
• Claude "记岔了"

4. /compact

不清空，但压缩。适用于：

• 想保留任务连续性
• 上下文接近上限
• 账单快速增长

5. pkill -f claude（核武器）

杀掉所有 claude 相关进程（macOS / Linux）。Windows 用户：

Stop-Process -Name "claude" -Force

适用于：

• 死循环 Hook 失控
• Subagent 卡死无法 kill
• 桌面 app + CLI 都崩了

之后必要时清空临时文件：

rm -rf /tmp/claude-*

七、版本升级与回滚

升级到最新

claude update

会显示 changelog 摘要 + 是否真的升级的提示。

看版本

claude --version
# Claude Code v2.5.3

回滚到上一版（保留最近 3 个版本）

claude rollback
# 选择回滚到 v2.4.x

看完整 changelog

claude changelog

或访问 docs.claude.com/changelog。

升级前的 3 条建议

1. 大版本升级（如 2.x → 3.x）先在测试机上跑 3 天。
2. 升级前备份 ~/.claude/：tar -czf ~/claude-backup-$(date +%Y%m%d).tar.gz ~/.claude/。
3. 升级后立刻 claude doctor：确认所有 MCP / Skills / Hooks 还能工作。

出问题的回滚顺序

1. claude rollback 回到上版
2. 还出问题？删 ~/.claude/cache/
3. 还不行？claude doctor 看具体哪里坏了
4. 实在不行：备份 ~/.claude/，重装，再恢复 settings.json 和 CLAUDE.md

八、社区求助路径

按响应速度从快到慢，按权威性从高到低：

1. claude doctor 自查

90% 的问题这里能给方向。先做这一步再去问别人，社区会更愿意帮你。

2. 本书附录 A 命令速查

附录 A 把所有 CLI 和 slash 命令列了 80+ 条，照着对一遍。

3. Anthropic 官方文档

docs.claude.com 搜索关键词。每次发现文档不够清楚，可以提 Issue 帮 Anthropic 改进。

4. GitHub Issues

github.com/anthropics/claude-code/issues 搜你的报错关键词，70% 是别人已经遇到过的。

5. Discord 官方频道

discord.gg/anthropic（具体邀请链接以官网为准）。#claude-code 频道有 Anthropic 工程师定期出没。响应通常 2-12 小时。

6. 中文社区

• 知乎话题"Claude Code"
• 即刻"AI 编程"圈
• B 站搜"Claude Code 教程"
• 几个活跃的微信群（详见附录 D）

7. Stack Overflow

claude-code 标签。适合具体技术问题（不适合"哪个套餐适合我"这种）。

提问的正确姿势

提问前先准备 4 样东西：

**版本**：claude --version 输出
**OS**：macOS 14.5 / Windows 11 / Ubuntu 22.04
**步骤**：
1. xxx
2. xxx
3. 期望 yyy，实际 zzz

**doctor 输出**（脱敏后贴关键部分）：

[paste here]

**已尝试**：
- 重启终端
- claude doctor
- 看了 GitHub issue #xxx，类似但解法对我无效

按这个模板提问，社区帮你的概率从 30% 飙升到 90%。

提问的错误姿势

"为什么 claude 不工作了？"
"求大佬帮忙"
"急！在线等！"
"@everyone"

这些不会得到回答。别人在用业余时间帮你，你需要让他帮起来"足够省力"。

九、避坑自检清单（每月做一次）

打印出来贴在显示器旁，每月 1 号花 10 分钟过一遍：

• 我的 .env 在 .gitignore 里
• 我的 CLAUDE.md 没有明文密钥
• 我的 API Key 在 console 设了 Hard Limit
• 我装的 MCP < 6 个（多了就删）
• 我的 CLAUDE.md < 200 行
• 我没有 5+ 天没 /clear 的会话
• 我的 /loop 任务都设了 --max-tokens 上限
• 我的 Hook 有防自触发条件
• 我没有让 Claude 自动付款的任务
• 我没有让 Claude 自动给客户发邮件的任务
• 我备份了 ~/.claude/（每月一次）
• 我看过本月 /cost 总额，符合预算
• 我的 Claude Code 版本是最近 3 个月内的
• 我的 Subagents 都用了 Haiku（除非有特殊需要）
• 我没有把客户敏感数据丢给联网模型
• 我所有的 /loop 任务我都能立刻定位它们
• 我有"紧急刹车"快捷键准备好（Esc / pkill）
• 我的 .claudeignore 包含 .env、secrets/、**/*.key
• 我至少看过一次 console.anthropic.com 的账单
• 我读过近 30 天的 changelog

20 项里少于 16 项打勾的话，建议本周内补齐。

十、避坑思维：3 个底线习惯

底线 1：小步迭代

永远不要一次让 Claude 改 100 个文件。改 5 个，跑测试，commit；再改 5 个，跑测试，commit。

理由：每一步都可逆。出问题 git 倒退一步即可。

底线 2：先 plan 后 do

复杂任务先用 Plan Mode（Shift + Tab 切到 Plan）。让 Claude 先给计划，你 review，确认后切回 Default Mode 执行。

理由：Plan 阶段错了你随手改，Do 阶段错了可能要熬夜恢复。

底线 3：验证再信任

Claude 的输出哪怕看起来 perfect，关键 5% 也要人工抽查：

• 涉及金额：抽查 3 笔
• 涉及客户名单：抽查 5 个
• 涉及代码：跑测试 + 看 diff
• 涉及部署：先 staging 再 production

理由：模型有"幻觉"，越自信地胡说越危险。

本章一图回顾

                  避坑总览
  ┌──────────────────────────────────────────┐
  │                                          │
  │   8 大坑识别       报错查表              │
  │   ─────────       ─────────              │
  │   1.无上下文       安装 / 登录           │
  │   2.无 dry-run     运行 / 自动化         │
  │   3.超长会话       60+ 条                │
  │   4.情绪化         一行查到原因          │
  │   5.MCP 太多                             │
  │   6.Hook 死循环                          │
  │   7.Key 泄露                             │
  │   8.版本不兼容                           │
  │                                          │
  ├──────────────────────────────────────────┤
  │                                          │
  │   性能调优 7 条    紧急按钮 5 个         │
  │   ─────────────    ─────────────         │
  │   Haiku 简单       Esc                   │
  │   Sonnet 日常      Ctrl + C              │
  │   Opus 架构        /clear                │
  │   @ 引用大文件     /compact              │
  │   /compact         pkill -f claude       │
  │   Batch API                              │
  │                                          │
  ├──────────────────────────────────────────┤
  │                                          │
  │   求助路径                               │
  │   ─────────                              │
  │   doctor → 速查 → docs → GitHub          │
  │   → Discord → 中文群 → SO                │
  │                                          │
  └──────────────────────────────────────────┘

下章预告

不踩坑了，下一章把你从用户变成创造者——发布自己的 Skill / Plugin、加入社区、把这件事做成副业 → 第十二章 从用户到创造者