EPEEAIKit/.cursor/skills/pitfall-journal/SKILL.md

name, description

name	description
pitfall-journal	踩坑经验记录系统。在调试完成或发现非显而易见的坑后记录根因和解决方式， 后续遇到同类问题时自动检索匹配，避免重复踩坑。 当 debug 完成、问题反复出现、或用户提到"踩坑"、"之前遇到过"、"坑"时触发。

Pitfall Journal

记录开发过程中遇到的"坑"——那些不看代码逻辑觉得应该没问题、但实际运行时才暴露的问题。 与 dev-changelog 互补：changelog 记"做了什么"，pitfall-journal 记"踩了什么坑、怎么爬出来的"。

数据文件

所有记录存放在 .cursor/pitfalls/pitfalls.md。

条目格式

### [PF-YYYYMMDD-HHMM] 一句话标题
- **症状**: 用户/系统看到的错误表现
- **根因**: 技术层面的真正原因
- **解法**: 具体怎么修的
- **防御**: 以后如何避免（可选，如果有通用性的话）
- **关联**: 相关文件、模块、技术栈标签

操作 A：写入记录

触发条件

以下任一场景触发：

1. 调试完成后 — 经历了 debug 过程并找到了非显而易见的根因
2. 用户主动提及 — "记录一下这个坑"、"以后别再犯"
3. Agent 识别到经验价值 — 问题涉及框架/库的隐式行为、配置陷阱、环境差异等

以下情况不触发：

• 纯拼写错误、简单语法错误
• 问题原因一目了然（如变量名打错）
• 纯业务逻辑调整（不涉及"坑"的语义）

流程

1. 生成条目 ID：PF-YYYYMMDD-HHMM
2. 从调试过程中提取：症状、根因、解法
3. 归纳防御措施（如果有通用性）
4. 读取 pitfalls.md，在顶部追加新条目
5. 在回复末尾附：[已记录到踩坑日志]

静默写入原则

与 dev-changelog 一致——Agent 自己调试出来的问题，不需要用户确认就可以记录。

操作 B：自动匹配检索

触发条件

当 Agent 在当前任务中遇到以下情况时，应主动检索 pitfalls.md：

1. 进入 Debug mode — 读取 pitfalls.md，扫描是否有与当前错误症状匹配的记录
2. 同类错误再现 — 错误信息关键词与已有条目的"症状"匹配
3. 涉及已知高危区域 — 当前操作涉及的模块/技术栈在已有条目的"关联"中出现

匹配策略

1. 提取当前问题的关键信号：
   - 错误信息关键词
   - 涉及的文件/模块
   - 涉及的技术栈/框架

2. 在 pitfalls.md 中匹配：
   - 硬匹配：错误信息关键词出现在条目的"症状"中
   - 软匹配：涉及的模块/技术栈出现在条目的"关联"中

3. 命中时，在分析中优先考虑已有经验：
   > 注意：之前遇到过类似问题 [PF-xxx]：[一句话描述]。
   > 上次的根因是 [xxx]，先排查这个方向。

操作 C：手动检索

触发条件

用户主动要求回顾踩坑记录。典型话语：

• "之前那个坑是什么来着"
• "看看踩坑日志"
• "有遇到过类似的问题吗"

流程

1. 读取 pitfalls.md
2. 根据用户描述匹配相关条目
3. 展示匹配结果

与其他系统的协作

系统	关系	说明
dev-changelog	互补	changelog 记改动事实，pitfall 记经验教训
pitfall-recall Rule	下游消费者	进入 Debug mode 或遇到错误时自动触发检索
epee-orchestrator	注册	在 registry.md 中注册本 Skill

自迭代日志

本节记录使用本 Skill 过程中发现的必要检查项。

已知必要检查

（暂无）