1.4 KiB
1.4 KiB
踩坑经验自动检索
被动检测触发
Agent 在以下场景中，应自动读取 .claude/pitfalls/pitfalls.md 并进行匹配检索：
- 进入 Debug mode：读取全部条目，将当前错误症状与已有记录比对
- 遇到运行时错误：提取错误信息关键词，在"症状"字段中检索匹配
- 同一问题第二次出现：如果当前会话中某个错误已出现过一次且未解决，强制检索
匹配策略
1. 提取当前问题的信号：错误信息关键词、涉及文件/模块、技术栈
2. 在 pitfalls.md 中匹配：
- 硬匹配：错误关键词出现在条目的"症状"中
- 软匹配：模块/技术栈出现在条目的"关联"中
3. 命中时在分析开头提示：
> 注意：之前遇到过类似问题 [PF-xxx]：[标题]。根因是 [xxx]，先排查这个方向。
写入提醒
Agent 在完成涉及 debug/修复的任务后，应读取 pitfall-journal Skill 并执行其"操作 A：写入记录"流程。
判断标准：问题的根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题，但实际运行时才暴露，就值得记录。
注意
- 检索结果是辅助参考，不是确定性答案——匹配到不代表根因一定相同
- pitfalls.md 不存在时跳过，不报错
- 每次会话中对同一条 pitfall 最多提醒一次