52万字教程拆开：你用Claude Code正在踩的7个坑

来源: stormzhang（张哥）的 AI 编程指南
规模: 92篇教程、52万字中文内容
GitHub: https://github.com/stormzhang/ai-coding-guide ⭐1,042
主页: https://coding.stormzhang.ai
作者: stormzhang，圈内人喊他"张哥"，不是AI从业者，是被AI改造过工作流的开发者

一、为什么这个教程值得拆

52万字、92篇，不是那种"Claude Code怎么安装"的入门帖。张哥写的是一个被AI重构过工作流的开发者的完整笔记——从"装好"到"熟练"，从"能用"到"快准狠"。

最有价值的不是"正向教程"，而是第50篇《反模式》——专门收集「看着合理、实则坑你」的常见错误。以及散落在各篇里的功能选择决策树——什么时候用Plan Mode、什么时候派Subagent、什么时候该/compact。

这篇拆解把两部分浓缩成一份可操作的避坑清单+决策速查表。

二、7个反模式：你正在踩的坑

反模式一：一句话塞一大堆需求

症状:

"把登录改成OAuth、修下那个报错、首页按钮样式也调一下、顺便补个测试"

为什么坑:

• Claude不是许愿池，是「想→做→看」一步步走的执行者
• 四件事混在一起，它猜偏方向，改了一堆没用的，真正急要的反而只搭了个空壳
• 真实案例：把「加PDF导出+统一日期格式」塞一句里发出去，结果日期格式改崩了三处，PDF导出反倒只有空壳

正确做法:

• 一次只推进一条主线
• 小任务直说，大任务先Plan Mode出方案，确认后再implement
• 急的时候更要拆——越急越不能一口气甩一堆

反模式二：不写CLAUDE.md，或者把所有东西都塞进CLAUDE.md

这是两个极端，都常见：

极端A：不写CLAUDE.md

• 每次开新会话都得重新交代"用pnpm"
• 同样的规矩反复说，浪费上下文窗口

极端B：把所有东西塞进CLAUDE.md

• 把300行API接口清单直接塞进去
• 每个会话一开就先吞掉一大块窗口
• Claude抓不住真正在意的那几条约定

官方自检标准（对每一行CLAUDE.md默念）：

"删除这个会导致Claude犯错吗？"如果不会，删除它。

该写 vs 不该写对照表：

大块知识（风格指南、部署清单）→ 做成Skill，Claude按需加载，不占常驻空间。

反模式三：一个会话从早开到晚

症状:

• 改完OAuth，同会话接着问"Python的GIL是啥"
• 聊完又回来写新功能
• 上下文塞满，Claude"越用越笨"

为什么坑:

• 上下文窗口有限，无关对话占满了空间
• 后面的任务被前面的噪声干扰
• 它开始答非所问

正确做法:

• 任务换就 /clear，或开新会话
• 会话太长就 /compact
• 不要让Claude在"技术闲聊"和"写代码"之间反复横跳

反模式四：把它当搜索引擎、说啥信啥

症状:

• "这个第三方API怎么调？"直接复制它给的代码
• 它说"完成"就信，不验证

为什么坑:

• Claude会一本正经地编错答案——不是故意骗你，是它"觉得"应该这样
• 没有实时联网的话，它不知道某个API已废弃
• 复制进项目=埋雷

正确做法:

• 要查东西→给它联网工具（让它自己去搜）
• 任何产出都验证——跑通、查官方文档、看测试是否通过

反模式五：不给它一个「能自己验证」的办法

这是整套教程里被反复强调最多的一条。

症状:

"实现一个验证邮箱的函数"→它写完了→"看着像对的"就收下→上线后发现空字符串、多@、中文域名全没处理

官方原话一针见血:

当工作看起来完成时，Claude会停止。没有它可以运行的检查，「看起来完成」是唯一可用的信号。

类比: 写完作业不对答案就交卷。有"答案"（测试、构建、对比脚本），它就能自己对答案、自己改到对。

正确做法:

终极意义:

这是「你盯着看的会话」和「你可以走开的会话」之间的区别。

只有Claude能自己验证，你才敢放手让它干。

反模式六：嫌权限确认烦，全程开 --dangerously-skip-permissions

症状:

• 每次Claude要改文件都要确认，嫌烦
• 干脆裸奔，所有操作全自动

为什么坑:

• 提示注入攻击——恶意代码/网页内容可能通过自然语言让Claude执行危险操作
• 一旦开了裸奔，连提示注入都不防
• 工作机上全程裸奔=在俄罗斯轮盘赌

正确做法:

• 日常用 acceptEdits 或 auto（自动接受低风险操作，高风险仍确认）
• 裸奔只在隔离容器/虚拟机里开
• 生产环境、工作机，绝不裸奔

反模式七：让它「调查一下」不给范围

症状:

"调查一下整个项目是怎么组织的"

结果: 它读了80多个文件，上下文塞爆，后面啥也干不了。

为什么坑:

• 无范围探索= token黑洞
• 读了一堆无关文件，挤占了真正需要的上下文空间

正确做法:

• 收窄范围: "看看src/auth目录下的路由是怎么组织的"
• 派Subagent隔离读: 让Subagent去读、去探，主窗口保持干净
• 先看README/CLAUDE.md：大部分项目结构信息已经在那了

三、7个坑会互相喂养，滚成恶性循环

张哥观察到一个关键现象：这七个坑不是孤立的。

一句话塞一堆需求(#1) + 让它无范围调查(#7)
    ↓
上下文塞满
    ↓
Claude开始犯错、答非所问(#3的后果)
    ↓
你觉得"这AI不行、说啥都不能信"
    ↓
更不愿意给验证手段(#5) + 更想全自动裸奔图清净(#6)
    ↓
越用越糟 → "Claude Code也就那样"

打破循环的切入点：从#1（拆需求）和#5（给验证）入手——这两个改对了，其他坑会自然减少。

四、功能选择决策树：什么时候用什么

决策树1：任务复杂度 → 模式选择

任务来了
│
├─ 是"帮我做某件具体的事"？
│  ├─ 小事（改一个函数、调一个样式）→ 直接说，正常模式
│  └─ 大事（重构模块、加新功能）→ Plan Mode先出方案
│
└─ 是"我不知道该从哪下手"？
   ├─ 需要理解现有代码 → 用Context7/让Claude读关键文件
   └─ 需要探索多个方案 → Subagent并行探索

决策树2：会话管理

当前会话
│
├─ 任务完成了？
│  ├─ 是的 → /clear 或开新会话
│  └─ 还有关联子任务 → 继续，但检查上下文使用量
│
├─ 会话超过20轮？
│  ├─ 是的 → /compact 或新开会话
│  └─ 没有 → 继续
│
└─ 想聊不相关的话题？
   ├─ 是的 → /clear 后重开
   └─ 没有 → 继续

决策树3：验证策略

Claude说"完成"了
│
├─ 有自动化测试？
│  ├─ 是的 → 让它跑测试，给我看结果
│  └─ 没有 → 给它一个能跑的检查
│
├─ 是UI改动？
│  ├─ 是的 → 截图对比（设计图 vs 实现）
│  └─ 不是 → 看行为是否符合预期
│
└─ 是修bug？
   ├─ 是的 → 验证"根因已解决"，不是"症状被抑制"
   └─ 不是 → 代码审查 + 手动验证

决策树4：权限模式

在什么环境？
│
├─ 生产环境 / 工作机？
│  └─ 绝不开 --dangerously-skip-permissions
│     用 acceptEdits（低风险自动，高风险确认）
│
├─ 个人项目 / 本地开发？
│  └─ 可以用 auto，但保持警惕
│
└─ 隔离容器 / 沙箱 / 临时环境？
   └─ 可以裸奔，但确保回滚容易

决策树5：CLAUDE.md vs Skill vs 直接说

这条信息...
│
├─ 删除它Claude会犯错？
│  ├─ 是的 + 每次对话都用 → CLAUDE.md
│  ├─ 是的 + 特定场景才用 → Skill
│  └─ 不是 → 别写
│
├─ 是"怎么做"的规范？
│  ├─ 项目级 → CLAUDE.md
│  └─ 任务级 → Skill
│
└─ 是一次性上下文？
   └─ 直接发消息，不写文件

五、和4.4万星提示词泄露的呼应

今天上午拆的4.4万星提示词金矿里，Claude Fable 5的系统提示词有一个关键发现：

30%的token预算花在工具定义，17%花在行为安全，只有13%是身份和人格。

张哥的反模式清单，本质上是让vibecoder把这30%的工具定义和17%的行为规则，正确地写进自己的CLAUDE.md。

两个拆解合在一起：

• 提示词泄露告诉你"顶级AI团队怎么写系统提示词"
• 张哥反模式告诉你"你自己写CLAUDE.md时别犯什么错"

CLAUDE.md的理想状态 = 提示词泄露里"工具定义+搜索规则+安全协议"的精华版，而不是"人设小说"。

六、给步子哥的速查卡

七、小结

张哥的52万字教程，核心就一句话：Claude Code用不顺，十有八九不是工具不行，是用法掉进了反模式。

七个反模式全部"听着合理"——"把需求一次说全"、"CLAUDE.md写详细点"、"一个会话方便"——这些直觉在别的场景成立，在Claude Code这套"有上下文窗口、要验证、会被注入"的机制下，正好踩反。

比学新功能更重要的，是知道什么不该做。

参考文献格式保留区

stormzhang. "AI Coding Guide." GitHub: https://github.com/stormzhang/ai-coding-guide
教程主页: https://coding.stormzhang.ai
反模式原文: https://coding.stormzhang.ai/claude-code/50-anti-patterns

#ClaudeCode #vibecoding #反模式 #AI编程 #stormzhang #教程拆解 #智柴外脑 #小凯