Skip to content

claude-code.md

Latest commit

 

History

History
265 lines (195 loc) · 7.88 KB

claude-code.md

File metadata and controls

265 lines (195 loc) · 7.88 KB

Claude Code 陷阱合集

README 里的"常见陷阱"表是速查，这里展开讲：每个陷阱讲清楚症状 → 根因 → 出坑 → 预防，用过都会遇到。

贡献踩过的坑，请提 Issue 或 PR。

陷阱 1：上下文溢出，AI 开始胡说八道

症状

  • 对话到后半段，AI 开始编造之前没讨论过的细节
  • 明明前面说过的约束，它忘了
  • 回答越来越短、越来越笼统，问题没回答完就 ↩

根因 Claude 有上下文窗口上限。对话+工具调用累计到 80% 以上时，最早的消息会被截断，AI "忘记"了早期设定。但它不会告诉你——它会装作记得，靠编造填空。

出坑

/compact              # 主动压缩上下文，保留关键决策

或者直接开新对话，把重要信息写进 CLAUDE.md 传递。

预防

  • 上下文用到 50% 就 /compact，不要等 80%
  • 一个对话做一件事，做完关了开新的
  • 重要决策不要只靠对话记忆——写进文件（CLAUDE.md 或 docs/）

陷阱 2：幻觉 API — AI 编了个不存在的函数

症状

  • AI 写了 someLib.fancyMethod()，但这个库根本没这个方法
  • 引用了不存在的配置项、不存在的 CLI flag
  • 代码看起来很合理，跑起来报 TypeError: x is not a function

根因 LLM 的训练数据截止日期前某个版本可能有这个 API，或者根本没有。它会根据"看起来应该有"生成代码。不 grep、不看文档就动手，就会编。

出坑

  • 先让它证明：先 grep 一下这个方法，确认它存在再用
  • 跑一次看报错，把报错贴回去：看这个报错，上网查这个库的最新文档

预防 在 CLAUDE.md 加一条：

## 编码纪律
- 使用任何第三方库 API 前，先 Read 它在 node_modules/ 下的类型定义或源码确认
- 不确定的 API 不要猜，要么查文档要么问我

陷阱 3：过度重构 — 修一行，改一百行

症状

  • 你说"给这个函数加个参数"，它把整个文件重写了
  • 顺手把变量重命名、加了注释、改了格式化、换了错误处理风格
  • PR diff 看起来像"整个文件重写"，实际想要的改动埋在中间

根因 Claude 默认倾向于"做好"，看到不满意的地方就顺手改。没明确约束时，它把"改进代码质量"当成加分项。

出坑 已经改完了但 diff 太乱：

把所有非必要改动回滚。只保留 [具体改动] 这一处。
格式化、重命名、加注释 全部回退。

预防 提示词里明确划边界：

只改 userService.ts 的 createUser 函数。
不要重命名、不要加注释、不要改格式、不要动其他文件。
如果看到别的问题，告诉我但不要动手。

对关键文件加 <important> 标签：

<important>
不要自动重构 src/legacy/ 下的代码，那是旧兼容层。
</important>

陷阱 4：测试谎报 — 它说"通过了"但根本没跑

症状

  • AI 说"测试已通过，所有功能正常" ✅
  • 你自己跑 pnpm test，一堆红
  • 或者：它只跑了部分测试，没跑的那部分就是挂的

根因 Claude 有时会基于代码推断测试应该通过，而不是真跑了测试。或者跑了部分测试但没看全输出。

出坑

  • 用否定式打断："不要推断，跑 pnpm test 把完整输出贴出来"
  • 要求可验证产物："跑完后把覆盖率报告粘给我看"

预防 用 Hook 强制验证：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{ "type": "command", "command": "pnpm test --run --reporter=basic" }]
    }]
  }
}

或者装 superpowers-zh 的 verification skill，它会在声称"完成"前强制跑测试。

陷阱 5：CLAUDE.md 被忽略 — 规则写了，它不听

症状

  • 明明 CLAUDE.md 写了"用 pnpm 不要用 npm"，它照样 npm install
  • 写了"测试放 __tests__/ 下"，它照样写在同目录

根因 CLAUDE.md 超过 ~200 行时，靠后的规则会被"边缘化"。Claude 看到长文档会自动摘要，细节丢了。另一个常见原因：规则太像"建议"而不是"要求"。

出坑

# 立刻在当前会话里
从现在开始严格按 CLAUDE.md 第 X 节执行。
重要规则是 [具体复述一遍]。

预防

  • CLAUDE.md 控制在 200 行以内
  • 大项目拆到 .claude/rules/ 用 globs 按文件类型加载
  • 关键规则加 <important> 标签
  • 用 "必须 / 禁止" 代替 "建议 / 尽量"：
## 禁止
- ❌ 禁止用 npm，本项目用 pnpm
- ❌ 禁止把测试写在同目录，必须放 __tests__/

陷阱 6：git --amend 覆盖你未 commit 的工作

症状

  • 你让 Claude "帮我改一下上一个 commit"
  • 它跑 git commit --amend
  • 你之前 stage 但没 commit 的修改……被吃进上一个 commit 了，或者丢了

根因 --amend 会把当前 staged 的所有内容合进上一个 commit。Claude 不知道你 staging area 里还有别的东西。

出坑

git reflog                    # 找回被 amend 覆盖的前一个 commit
git reset --hard HEAD@{N}     # 回滚到那个状态（N 是 reflog 里的序号）

预防

  • 不让 Claude 用 --amend——明确告诉它"新建 commit，不要 amend"
  • 在 .claude/settings.json 里限制：
{
  "permissions": {
    "deny": ["Bash(git commit --amend*)"]
  }
}

陷阱 7：Plan Mode 写得好，执行偏了

症状

  • 用 /plan 让它先规划，方案写得头头是道
  • 点确认开始执行，前两步还对
  • 到第三步开始"自由发挥"，偏离了原方案

根因 Plan mode 给的是起点，不是"锁死的脚本"。执行过程中 Claude 会基于实际情况调整，有时调整得太远就脱轨了。尤其是当某步失败时，它倾向于"换个思路"而不是停下来问你。

出坑

停。对照一下原 plan 的第 N 步，你现在在做的和 plan 一致吗？
如果偏了，说明为什么，让我决定继续偏还是回到 plan。

预防

  • 让 plan 更"原子化"：每步独立可验证，而不是"第三步：重构登录流程"这种大步
  • 关键节点明确要求"做完暂停等确认"：
按 plan 执行。每步做完：
1. 跑相关测试
2. 总结改动一句话
3. 暂停等我 OK 再下一步

陷阱 8：Subagent 之间上下文对不上

症状

  • 主 agent 让 subagent A 写代码，subagent B 跑测试
  • B 回报"测试失败，找不到文件"
  • 但 A 明明写了——原来 A 的"写"只是返回了文本，没真写到磁盘

根因 Subagent 之间不共享文件系统视图的实时状态，尤其是主 agent 没把 A 的输出持久化就传给 B。A 在它的上下文里"知道"文件存在，但磁盘上可能根本没有。

出坑

停，让我核实状态。
运行：ls -la src/newfile.ts && cat src/newfile.ts
确认文件真的存在再往下做。

预防

  • 让 agent 通过文件传结果，不要只靠消息传递
  • 主 agent 调度时明确："A 把代码写到磁盘后，告诉我文件路径；B 读那个路径再跑测试"
  • 复杂编排超过 2 个 subagent，考虑换成主 agent 线性执行——可靠性比并行更重要

补充：遇到新陷阱怎么办

踩坑是最值钱的经验。欢迎提 Issue 或 PR 补充，模板：

## 陷阱 N：一句话标题

**症状**
你看到的异常现象（越具体越好）

**根因**
为什么会发生（用你的理解说清楚）

**出坑**
已经掉坑里了怎么爬出来

**预防**
下次怎么避免（提示词 / 配置 / Hook / Skill 等）

相关方法论