## 踩坑经验自动检索

### 被动检测触发

Agent 在以下场景中，应自动读取 `.claude/pitfalls/pitfalls.md` 并进行匹配检索：

1. **进入 Debug mode**：读取全部条目，将当前错误症状与已有记录比对
2. **遇到运行时错误**：提取错误信息关键词，在"症状"字段中检索匹配
3. **同一问题第二次出现**：如果当前会话中某个错误已出现过一次且未解决，强制检索

### 匹配策略

```
1. 提取当前问题的信号：错误信息关键词、涉及文件/模块、技术栈
2. 在 pitfalls.md 中匹配：
   - 硬匹配：错误关键词出现在条目的"症状"中
   - 软匹配：模块/技术栈出现在条目的"关联"中
3. 命中时在分析开头提示：
   > 注意：之前遇到过类似问题 [PF-xxx]：[标题]。根因是 [xxx]，先排查这个方向。
```

### 写入提醒

Agent 在完成涉及 debug/修复的任务后，应读取 `pitfall-journal` Skill 并执行其"操作 A：写入记录"流程。
判断标准：问题的根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题，但实际运行时才暴露，就值得记录。

### 注意

- 检索结果是**辅助参考**，不是确定性答案——匹配到不代表根因一定相同
- pitfalls.md 不存在时跳过，不报错
- 每次会话中对同一条 pitfall 最多提醒一次