常见反模式与避坑

官方 best-practices 里有一条专门叫「Avoid common failure patterns」——常见失败模式。这一篇就是「踩坑指南」：把 10 种最常见的反模式列出来，每种都配 Before vs After 对比。

为什么不写「正确做法」而写「错误做法」？因为人脑对痛感的记忆比对成就感的记忆深。看一遍「别人这么干搞砸了」，比看十遍「应该这么做」更记得住。

反模式 1：上来就写代码

新手拿到任务立刻喊「帮我实现 XXX」，Claude 一头扎进去改代码，改完发现踩了一堆隐藏依赖。

Before	After
`帮我实现 OAuth 登录`	`先读 @src/auth/ 摸清现在认证怎么走的，进 plan mode 给方案，包括要改哪些文件、边界情况、风险点。我点头后再动手`

Plan-first 模板详解了「Explore → Plan → Implement → Commit」四阶段。一上来就 Implement，等于没看地图就开车。

反模式 2：提示太模糊

「fix the bug」是最经典的反模式——bug 在哪？什么症状？哪个文件？Claude 只能瞎猜。

Before	After
`fix the bug`	`登录页输入正确密码点登录，控制台报 401，但网络面板看请求体里 password 字段是空的。怀疑是表单序列化的问题。看 @src/login/form.ts 第 42 行`
`优化性能`	`首页加载 lighthouse 跑分 LCP 4.2s，目标是降到 2.5s 以内。瓶颈看起来在 @src/pages/index.tsx 的图片没懒加载`
`加个错误处理`	`给 @src/api/user.ts 的 fetchUser 函数加 try/catch，错误时返回 null（参考 @src/api/post.ts 里 fetchPost 的写法）`

After 版都做了一件事：圈定范围 + 指给文件 + 描述症状。Claude 不用猜在哪、猜什么、猜怎么改。

反模式 3：上下文不清理

一个会话从早写到晚，什么功能都往里塞，聊到下午上下文已经糊成一锅——前面定的方案忘了、刚才改的代码记不清了。

Before	After
一个会话干完 5 件事，越往后越笨	一个功能一个会话，做完 `/clear` 或 `/resume` 切到下一个
上下文 80% 了还在硬撑	40% 主动 `/compact`，45% 就该分流
聊歪了还不清空	`/clear` 推倒重来，比费力整理快

详见上下文工程。上下文是会退化的（45% 左右就开始），不主动管理就等死。

反模式 4：不给验证方式

Claude 自信地说「我改完了」，你信了，结果一跑发现崩了。这是最危险的失败模式——「看起来不错」糊弄。

Before	After
`帮我修这个 bug`	`帮我修这个 bug。改完跑一遍 npm test，把输出贴给我看，全绿才算完`
`重构这块代码`	`重构这块代码。改完跑 npm run build 确认没编译错误，再跑 lint 确认没警告`
`做个登录页`	`做个登录页。改完用 playwright 截张图，把截图给我看`

差别就一个动词：show vs say。详见反馈循环设计——四种验证强度，按风险选。

反模式 5：大块 diff

一次性丢巨大改动——500 行 diff 谁也没法审查，只能祈祷。

Before	After
`把整个 auth 模块重构了`	`把这个任务拆成 5 个自包含小块，每块改完停下来给我看 diff，确认后再做下一块`
一口气写完，崩了不知道哪步出问题	每步独立可测、可回退（/rewind 只丢一步）
500 行 diff，reviewer 哭	50 行 × 10 步，每步扫一眼就过

「自包含」是关键词——每块改完，相关测试能过、代码能编译，不是半成品。详见 9 步循环第 4 步「拆小块构建」。

反模式 6：自己当验证循环

每个错误都等你自己发现——Claude 改完说「应该没问题」，你手动跑、手动看、手动挑错，再回来反馈。这是把人当成了循环的一环，慢且不可靠。

Before	After
改完你手动跑测试	改完 Claude 自己跑 npm test，失败继续修
你逐个文件看 diff	派 review 子代理独立审查，列清单
你盯着 console 看报错	让 Claude 跑 reproduce 脚本，exit code 0 算修好

把人从循环里拿出来，让机制当验证——这是从「手工指挥」走向「自动化交付」的关键。详见反馈循环设计。

反模式 7：不用子代理

所有活都让主会话扛——读一万行代码、跑全套测试、审查大 diff——主上下文被污染，越用越笨。

Before	After
主会话通读 @src/ 全目录	派 Explore 子代理读，主会话只拿摘要
主会话跑全套测试看输出	派子代理跑，只回传「全绿」或「3 个失败」
主会话审 500 行 diff	派 review 子代理独立审查，列清单

子代理的独立上下文是上下文工程的大腿——重活甩出去，主会话只装决策。详见 Subagents 深入。

反模式 8：CLAUDE.md 太长

把所有规则都塞进 CLAUDE.md——5000 字的公约，指令被淹没，Claude 抓不到重点。

Before	After
5000 字的 CLAUDE.md，啥都往里塞	500 字以内，只放最关键的公约
命名规范、设计偏好、历史决策、TODO 全混一起	分层：公约放 CLAUDE.md，操作手册放 Skill，强制规则放 Hook
「记得做 X」写在 CLAUDE.md 祈求	写进 Hook 100% 必跑

CLAUDE.md 是「贴在墙上的标语」，标语太长没人看。公约精简，操作手册化 Skill，硬规则挂 Hook——三层分工，每层只做自己擅长的事。

反模式 9：不用 /rewind

走错路就重新开始，把前面正确的部分也丢了——或者硬着头皮继续，越走越偏。

Before	After
走错了从头再来	`/rewind` 回到走错前那一步，只丢错的
硬着头皮继续，越偏越远	rewind 后换个方向重新走
改坏了手动 revert	rewind 一键回退，连上下文一起回

/rewind 是会话内的安全绳——和 git checkout 不同，它连对话上下文一起回退，让你从「走错前」那一刻重新开始。详见 /rewind 安全绳。

反模式 10：命名会话缺失

开 10 个终端不知道哪个是哪个——session-2024-11-03-abc123 一堆默认名，回头想恢复某个任务找不到。

Before	After
默认名 `session-xxx`	`/rename auth-refactor`，会话名 = 任务名
10 个终端不知道哪个是哪个	一眼看出 auth-refactor、payment-webhook、perf-bottleneck
一周后找不到当时那个会话	`claude -r auth-refactor` 按名恢复

会话名 = 任务名，越早养成越省事。详见会话管理。

Develop your intuition：培养直觉

官方 best-practices 最后一条建议：Develop your intuition。

反模式背一遍没用，得在日常用里反复试、反复复盘：

这次提示让 Claude 走偏了？想想哪句话该改。
这次上下文爆了？看看 /stats 哪步烧的。
这次忘了 /rewind 硬撑？下次走偏立刻回退。

每次复盘一点点，几个月下来你就能凭直觉判断：什么任务该 plan、什么该拆、什么该甩给子代理、什么时候该 /clear。这时候你不再「照着清单避坑」，而是「按感觉避坑」——而感觉对了，才是真会了。

直觉不是玄学，是反复实践压缩出来的判断力。10 个反模式是路标，告诉你哪里有坑；走多了，你的脚自然知道往哪儿避。

Before vs After 总览

把 10 个反模式的解药压成一张表：

反模式	解药
上来就写代码	先 Explore + Plan
提示太模糊	圈范围、指文件、描述症状
上下文不清理	/compact、/clear、用子代理
不给验证方式	让 Claude 拿证据
大块 diff	拆自包含小块
自己当验证循环	让机制验证
不用子代理	重活甩给子代理
CLAUDE.md 太长	精简，分层到 Skill/Hook
不用 /rewind	走错立刻回退
命名会话缺失	会话名 = 任务名

一句话总结

反模式是踩坑指南：上来就写代码、提示模糊、上下文不清理、不给验证、大块 diff、自己当循环、不用子代理、CLAUDE.md 太长、不用 /rewind、命名会话缺失——10 个坑每个配 Before vs After。Develop your intuition：背一遍没用，在日常用里反复复盘，练成「按感觉避坑」的判断力。

至此，「提示工程与最佳实践」板块走完。回头看提示词设计原则把八条心法再过一遍，或者去 9 步纪律化循环把心法固化成流水线。🚀