---
description: 在 Debug、运行时错误或重复失败时被动检索既有踩坑经验
alwaysApply: true
---

# 踩坑经验被动检索

## 触发条件

出现任一情况时读取 `.cursor/pitfalls/pitfalls.md`：

- 进入 Debug 或系统化故障排查；
- 遇到运行时、构建、配置、版本或工具链错误；
- 同一问题在当前会话中第二次出现。

文件不存在或只有模板时跳过，不报错。

## 匹配方式

1. 提取错误关键词、涉及模块、运行环境和复现条件。
2. 优先匹配条目的“症状”，再匹配“关联”或技术栈。
3. 命中时简短指出相似记录、既有根因和首要排查方向。
4. 将命中结果视为假设，必须用当前证据验证；同一条记录每次会话最多提醒一次。

## 任务结束

若根因只能通过实际运行或多步排查发现，读取 `.cursor/skills/pitfall-journal/SKILL.md` 并按其流程记录。纯拼写、明显语法错误或普通业务逻辑调整不记录。

用户限制可修改范围或 Skill 缺失时，不越权写入，只报告待记录事项。