Appearance
21 · 反模式与排障速查
📚 系列导航：上一篇 20 最佳实践 讲了「该这么用」。这一篇翻到背面——专挑「不该这么用」的坑，和常见报错怎么解。
第一部分：七个反模式
反模式一：一句话塞一大堆需求
| ❌ Before | ✅ After |
|---|---|
| 「改 OAuth、修报错、调样式、补测试」一口气甩 | 先「把登录改成 Google OAuth，先别动别的，给我个方案」 |
| 四件事混在一起 | 一次一件，每件说清范围 |
反模式二：不写 CLAUDE.md / 全塞进 CLAUDE.md
不写： 每开会话重交代一遍，Claude 天天「失忆」。 全塞： 规则被几百行废话淹没，遵守度反而下降。
判断标准： 每行自问「删了它 Claude 会犯错吗？」不会就删。大块知识做成 Skill。
反模式三：一个会话从早开到晚
任务不相关了用 /clear，同一任务太长用 /compact。纠正两次以上，清屏重开。
反模式四：把它当搜索引擎，说啥信啥
大模型会编。要查实时信息，给它联网工具（WebFetch/MCP）。任何产出，要个验证办法。
反模式五：不给它验证的办法
NOTE
没有验证手段，「看着像对的」就是它唯一的完工标准——而「看着像对」和「真的对」之间，隔着所有它没测到的边界情况。
反模式六：无脑开 bypassPermissions
bypassPermissions 连提示注入都不防。想省心又有底线，用 auto 模式（有分类器兜底）。
反模式七：让它「调查一下」不给范围
text
调查一下这个项目的架构→ 它可能读几百个文件，烧爆窗口。正确做法：
text
调查一下这个项目的架构，只看 src/ 目录下的主要模块，每个模块用一句话概括第二部分：排障速查
自助命令
| 处境 | 先敲这个 |
|---|---|
| 不确定问题属于哪类 | /doctor |
claude 起不来 | claude doctor（终端） |
/doctor 报了问题 | 按 f 把报告发给 Claude |
| 查完文档也解不了 | /feedback 上报 |
| 怀疑服务器挂了 | 看 status.claude.com |
认证问题
| 症状 | 真正原因 | 怎么修 |
|---|---|---|
This organization has been disabled | 环境变量有旧 API key 压过订阅 | unset ANTHROPIC_API_KEY，删配置文件 |
| 反复被要求登录 | 系统时钟不准 / macOS Keychain 锁了 | 对时，跑 claude doctor 查 Keychain |
403 Forbidden | 订阅/角色问题 | 查订阅状态或 Console 角色 |
Invalid API key | key 过期或被撤销 | 重新生成 |
配置问题
| 症状 | 多半因为 | 怎么修 |
|---|---|---|
| hook 不触发 | matcher 大小写错了 | 工具名首字母大写：Bash、Edit |
| 设置被忽略 | settings.local.json 覆盖了 | 检查优先级 |
| MCP server 不加载 | .mcp.json 放错目录 | 放项目根目录，不在 .claude/ 里 |
性能问题
| 症状 | 先做这个 |
|---|---|
| 越用越慢 | /compact，然后重启 |
| 彻底卡死 | Ctrl+C，不行关终端，claude --resume 续上 |
| 自动压缩抖动 | 分块读大文件，或 /compact keep only ... |
@file 补全失灵 | 装系统 ripgrep，设 USE_BUILTIN_RIPGREP=0 |
API 报错
| 报错 | 什么意思 | 怎么修 |
|---|---|---|
529 Overloaded | API 过载 | 等几分钟重试，或切模型 |
429 Too Many Requests | 速率限制 | 等速率重置 |
5xx | 服务器错误 | 先看 status.claude.com |
NOTE
下一篇：22 速查表：常用命令、快捷键、斜杠命令、环境变量全量速查。