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的查询从 N1 改成批量目标是 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 keysk-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而不是魔法代码补全。核心心法就四句话给对上下文——精确、精简、持久化。CLAUDE.md 固化文件引用长对话压缩。先规划再执行——复杂任务先出 Plan审方案再施工。改方案便宜改代码贵。始终 review——diff 必须看。边界条件、隐式依赖、幻觉 APIAI 都会漏。按需扩展与拆分——单文件改动不规划多文件并行用子 Agent大到装不下才拆任务。工具是手段不是目的。感谢追完这八篇。如果你在实际使用中踩到了新的坑或者总结出了自己的高效工作流欢迎在评论区交流——这比教程本身更有价值。标签Claude Code、AI编程、避坑、AI Agent、最佳实践、开发工具