Claude Code 避坑指南：我踩过的那些坑（系列收官）

本文是《Claude Code 实战》系列第 8 篇，也是收官篇。前七篇从定位到实战系统梳理了完整用法。本篇把散落在各篇里的注意事项，加上额外的血泪教训，集中成一份避坑清单——读完省下几十个小时的试错成本。

---

上下文管理：最隐蔽的坑

坑 1：一次丢太多，AI 反而抓不住重点

把整个项目的 50 个文件一次性扔进对话，想让 Claude 理解全局——结果它的回答越来越泛，具体细节全丢。

原因：上下文窗口有限。文件越多，模型分配给每个文件的"注意力"越薄，关键信息被稀释。它读到了所有文件，但都理解得浅。

避法：一次只给任务相关的文件。用 @文件路径 精确引用。“先读 src/routes/auth.ts 和 src/middleware/auth.ts，搞清楚认证流程”——两个文件够用，就不给 50 个。

坑 2：长对话不清理，越聊越偏

改了 40 轮之后，Claude 开始犯和 10 轮前一样的错误，或者把早期放弃的方案又重新提出来。

原因：对话历史也是上下文。旧决策、废弃方案、修改记录全堆在里面，占用空间且产生干扰。

避法：连续工作超过 30 分钟就 /compact 一次。把历史压缩成摘要，释放上下文。如果方向已经完全变了，直接 /clear 重置——白纸比糊涂纸好。

坑 3：项目约定全靠嘴说，不写进 CLAUDE.md

每次新会话都要重复"这个项目用 pino 打日志，别用 console.log"。说了十遍，第十一遍还是忘了。

原因：不靠嘴说不靠记忆，靠持久的指令文件。你没写，它就没地方读。

避法：花 15 分钟写一份 CLAUDE.md，放在项目根目录。包含：构建命令、命名规范、架构约束、踩过的坑。15 分钟 × 1 次，替代 30 秒 × 100 次。

---

任务组织：流程决定下限

坑 4：目标模糊就让它动手

“帮我优化一下这个项目”——然后 Claude 开始改文件命名、调整目录结构、重构函数，改了一堆不是你想要的。

原因：AI 有主观能动性，但它的"好"不一定是你的"好"。方向没对齐，干得越多错得越多。

避法：先定义验收标准。“代码可以跑但太慢，帮我把 api/users 的查询从 N+1 改成批量，目标是 200ms 以内”——有标准它才能朝着正确的方向使劲。

坑 5：该用 Plan 的时候直接写代码

改一个涉及 6 个文件的复杂功能，让它直接动手。结果改了 3 个文件后发现和前 2 个对不上，推倒重来。

原因：涉及多文件、多步骤的改动，不先规划路径，边写边调整必然返工。

避法：文件数 ≥3 或涉及架构改动时，先让 Claude 出 Plan。“Plan 一下怎么实现这个功能，列出要改哪些文件、改什么、步骤顺序”。审完方案再施工——改方案的成本远低于改代码。

坑 6：不 review diff 直接接受

改完 200 行代码，看都不看就接受——然后在运行时发现它删掉了一个"看起来没用"的 import，而这个 import 有副作用（init 函数注册）。

原因：AI 无法感知隐式依赖——init 函数、反射注册、monkey patch 这些"看起来没引用但实际在用"的依赖，删了就炸。

避法：每次改动后扫一遍 diff。重点关注：被删除的东西（是否真的没用）、新增的依赖（是否真的需要）、改动的边界条件（null/空数组/超时）。

---

权限与安全：能做的事≠该做的事

坑 7：给了编辑权限就不看它执行什么

Claude Code 编辑文件前不会逐行向你确认——它改了就是改了。给了写入权限却不管它改了什么，等于把编辑器交给一个不太了解你项目的人。

避法：重要文件（配置、数据库 schema、认证逻辑）改完后必须 review diff。对不信任范围的文件，在 .claude/settings.json 里设只读权限。

坑 8：敏感信息进上下文

“用这个 API key：sk-xxx…” ——说完这句话，token 就进了上下文，并且会在 /compact 后的摘要里保留。

避法：API key 和 token 用环境变量传，别写进对话。已经说了的话，/clear 重置上下文，确保清理完全。

---

能力边界：它不是万能的

坑 9：盲信它写的 API 调用

Claude 写了一个调用某库 v3.2 新增方法的代码。跑的时候发现这个方法在 v3.1 里不存在——它"编造"了一个合理的 API。

原因：幻觉是 LLM 的固有特性。当它不确定时，它倾向于生成"看起来像对的"而不是"空着不做"。

避法：对 API 调用保持怀疑。遇到不熟悉的库名或函数名，在代码里加一行注释让它标出版本要求，或者先让它去查文档确认 API 存在再写代码。

坑 10：用旧版本的用法套当前版本

Claude Code 迭代很快。一个月前的"正确用法"今天可能就不是最佳实践了。凭前几个月的经验指挥它，结果它按新版本的行为执行，产出和预期对不上。

避法：使用新功能前，让它读当前版本的文档。“先读 Claude Code 的最新文档里关于 X 的部分，再按文档里的方式做”——让 AI 自己核实当前版本的机制。

---

成本与效率：token 不是免费的

坑 11：小任务上重流程

加一行日志，走了 Plan → 多 Agent 探索 → 并行实现的流程。过程看起来很酷，但一行日志原本 10 秒改完的事，花了 3 分钟和 40 倍 token。

避法：判断标准——单文件、单函数、逻辑简单 → 直接说"改这里"，别规划。只有跨文件、有设计决策、可能影响其他地方的任务才走 Plan。

坑 12：无节制地并行子 Agent

“并行探索全球所有数据库 ORM”——派了 8 个子 Agent 同时干活。token 消耗爆炸，但最终有用的只有 1 个子 Agent 的结果。

避法：并行只用于独立任务。问自己三个问题：这几个任务真能同时跑吗？每个结果都必须用吗？总 token 消耗值得吗？三个都是"是"再并行。

---

协作心态：你不是甲方，你是搭档

坑 13：期待一遍成功

让它写一个完整功能，跑一遍就完美——这种期待会在第一次报错时摧毁你的耐心。

真相：它擅长第一版的 80%。剩下的 20%（边界条件、环境适配、性能优化）需要人介入。这不是缺陷，是正确分工——人力花在判断和修正上，不是打字上。

避法：预期管理。把 AI 当成一个"打字快但需要监督的资深同事"，而不是"按按钮出产品的黑盒"。每轮迭代缩小误差，而不是追求一次完美。

坑 14：完全放手不把关

走了另一个极端——“反正 AI 写的，出问题不是我的责任”。

避法：AI 写的代码上线后的 bug，背锅的是你，不是 Claude Code。保持对产出的 owner 意识——review、测试、验证，你做最终决策。

---

系列收束

八篇下来，一条主线贯穿始终：把 Claude Code 当成需要正确协作方式的 agent，而不是魔法代码补全。

核心心法，就四句话：

1. 给对上下文——精确、精简、持久化。CLAUDE.md 固化，@文件引用，长对话压缩。
2. 先规划再执行——复杂任务先出 Plan，审方案再施工。改方案便宜，改代码贵。
3. 始终 review——diff 必须看。边界条件、隐式依赖、幻觉 API，AI 都会漏。
4. 按需扩展与拆分——单文件改动不规划，多文件并行用子 Agent，大到装不下才拆任务。工具是手段，不是目的。

感谢追完这八篇。如果你在实际使用中踩到了新的坑或者总结出了自己的高效工作流，欢迎在评论区交流——这比教程本身更有价值。

---

标签：Claude Code、AI编程、避坑、AI Agent、最佳实践、开发工具