Claude 踩坑守则 —— 常见犯错清单，一键导入 Claude Code

⚠️ Claude 踩坑守则

让 Claude 变强的最快方式，是把别人用真实事故换来的教训直接写进它的记忆。这里的 15 条守则全部来自生产环境的真实翻车（丢文件、幻觉「已完成」、API 静默失败……），每条都提炼成一行可执行的规矩。勾选你需要的组合，一条命令合并进你的 Claude Code —— 更新永远是 merge，不会覆盖你自己的记忆和修改。

当前版本: 2026-08-05 · 15 条守则 · JSON · install.sh

✅ 验证与实事求是

高危未验证不声明「完成/修好了」——跑测试、看日志、发真实请求拿到证据再下结论

事故背景: 「改完了应该就好了」是 AI 助手幻觉的重灾区。声明完成的那一刻必须能贴出证据：测试输出、日志行、HTTP 状态码。拿不出证据 = 没完成。

文档与代码冲突时以代码为准，并顺手把文档改对

事故背景: 项目文档里写着旧服务器 IP，而部署脚本早已换新。照文档操作会连到错误的机器。文档是快照，代码才是事实。

判断「没流量/没日志」前，先用 nginx -T 等命令确认日志的真实写入路径

事故背景: 默认路径 /var/log/nginx/access.log 是 0 字节，差点得出「这台机器没流量」的结论——nginx -T 显示 access_log 早被改到了自定义目录，真实日志一直在写。

长度/数量类硬限制必须脚本实测，「目测砍了不少」不算验证

事故背景: 数据库字段限 500 字符，摘要从 598 精简后「感觉够了」直接提交，实际 506，再次失败。同一个坑明知故犯，根因是用目测替代了计数。

🐚 Shell 与文件操作

高危批量 mv/重命名必须 mv -n 或先检测目标存在——撞名 = 静默丢数据

事故背景: 按文件 mtime 推日期批量重命名日志，同一天轮转过两次的文件算出同一个目标名，mv 静默覆盖，3 个历史文件永久丢失。

怀疑「文件被篡改/工具出鬼」前先检查自己的命令 flag——如 rg 的 -r 是 --replace 不是递归

事故背景: rg -r 把搜索结果的显示替换当成了递归搜索，输出「看起来文件内容变了」，差点引发一场「工具输出被注入」的错误排查。

临时脚本放项目内 ./tmp/，不放系统 /tmp——脚本在 /tmp 找不到项目依赖

事故背景: cron 补救脚本写到 /tmp 执行，node 按脚本所在目录向上找 node_modules，报 ERR_MODULE_NOT_FOUND。放项目 ./tmp/ 一次通过。

🔌 外部 API 集成

高危部分 API（MiniMax 等）业务错误藏在 HTTP 200 的 body 错误码里——只判 HTTP 状态 = 没做错误处理

事故背景: 限流、鉴权失败、余额不足、内容拦截全部返回 HTTP 200，真实错误码在 base_resp.status_code。按状态码写的重试逻辑一行都不会触发。

代理环境变量必须带 http:// 前缀；且 gRPC 认 grpc_proxy、REST 认 HTTPS_PROXY，各认各的

事故背景: grpc_proxy 写成裸 127.0.0.1:7897 直接解析报错 60 秒超时；GA4(gRPC) 配好的代理照搬给 GSC(REST) 完全无效——Node 内置 fetch 根本不读 HTTPS_PROXY。

只有限流值得退避重试；鉴权/余额/内容拦截类错误重试一万次也是同一个结果，直接抛

事故背景: 无差别重试让一次鉴权失败变成三次慢失败，还掩盖了真实报错。重试白名单应该只有限流和瞬时网络错误。

🚀 Git / CI / 部署

改动后先 bump 版本号再触发构建——同版本 tag 重复构建会因竞态互相覆盖

事故背景: 同一个镜像 tag 触发两次构建，后完成的覆盖先完成的，部署到的版本取决于谁跑得慢。版本号是构建的身份证，不是装饰。

CI 秒级失败 = 网络/鉴权问题，分钟级失败才可能是编译/依赖——先看失败发生在第几秒

事故背景: 构建启动 2 秒就挂在 load metadata，报错行却指向 Dockerfile——真凶是跨境拉镜像的 connection reset，与代码毫无关系。同一份 Dockerfile 前后都构建成功过就是铁证。

🎨 AI 生成内容

高危AI 生图管氛围，程序管信息：标题/数字/品牌元素用代码合成，别让模型画（中文必乱码）；宽幅构图写明确指令（主体居中、铺满全宽），别用「留白」这类审美形容词

事故背景: prompt 里一句 generous negative space，模型把主体挤到画面一侧、剩 60% 纯色空白；而分享缩略图恰恰从中央裁切。改成「主体居中铺满全宽」一次修正。标题则始终由 SVG 合成——锐利且永不乱码。

⚙️ 自动化管线

高危保存/提交前必须等第三方的异步过程真正完成——轮询目标状态，不要 sleep 猜时间

事故背景: 往微信编辑器粘贴外链图后立即保存会丢图：编辑器需要约 4 秒把图转存到自己的 CDN。正确做法是轮询所有 img 的 src 全部变成目标域名后再点保存。

高危无人值守管线的每一环都要有降级回落——AI/外部接口天生不可靠，靠兜底不靠祈祷

事故背景: AI 封面生成失败（限流/拦截/没配 key）时回落到模板封面：封面素一天可以接受，日更管线断更不可以。回落路径要和主路径一样被测试过。

💡 设计理念：记录无限，常驻有预算，晋升有门禁

经验库最大的敌人不是「记得少」，而是「越记越臃肿」——每条常驻记忆都在吃你每个会话的上下文。我们用四层机制对抗膨胀：

① 分层加载：hot 层是跨场景铁律（全库硬上限 10 条），随 @import 常驻每个会话；warm 层按分类装成 Claude Code skill——常驻的只有一行触发描述，正文只在你做相关任务（动 shell、接 API、排查 CI……）时才被加载，上下文成本趋近于零。

② 入口门禁：能进库的守则必须同时满足「会再犯、一行规矩可表达、有真实事故背书」，单次小问题只进事故簿不进守则。

③ 使用衰减：每条守则带 last_confirmed（最近一次真实生效日期），长期不生效的条目在季度复盘中降级或归档，而不是永久占位。

④ 定期压缩：同主题的多条坑会合并升维成一条更通用的规矩（比如三个代理坑合成「代理配置三查」），库的健康靠压缩而不是无限追加。

导入原理（为什么敢说「非覆盖」）

只写独立受管文件 ~/.claude/claude-lessons.md 与 ~/.claude/skills/claude-lessons-*/，你的 CLAUDE.md 仅被幂等插入一行 @import；

每条守则是带 ID + 版本 + 内容哈希的标记块：你改过的条目更新时保留并提示冲突；你删除过的条目记入 ignore 永不回填；文末 local:below 区完全归你；

多次不同组合的安装自然累积；卸载 = 删掉 CLAUDE.md 里那行 import + 删除受管文件与 skills。

FAQ

会覆盖我自己的 CLAUDE.md 吗？

不会。安装只在你的 CLAUDE.md 追加一行 @import 引用（带标记、幂等），所有内容都在独立的受管文件里。你的记忆与我们的守则物理隔离。

我改过或删过某条，更新会被冲掉吗？

不会。每条守则携带内容哈希，检测到你改过就保留你的版本并提示冲突；你删除过的条目 ID 会记入 ignore 文件，之后的更新永不回填。

装得越多会不会让 Claude 越来越慢、越来越贵？

不会。只有 hot 层铁律（≤10 条，约几百 tokens）常驻会话；warm 层守则装成按需加载的 skill，平时只有一行描述在场，做相关任务时才展开。全选 15 条的常驻成本也只有约 400 tokens。

导入会占用多少上下文？

页面勾选时实时显示常驻成本估算。全量导入约 400 tokens/会话 + 6 个按需 skill；只选基础包可以压到 200 tokens 以内。