4.5 KiB
name, description
| name | description |
|---|---|
| pitfall-journal | 踩坑经验记录系统。在调试完成或发现非显而易见的坑后记录根因和解决方式， 后续遇到同类问题时自动检索匹配，避免重复踩坑。 当 debug 完成、问题反复出现、或用户提到"踩坑"、"之前遇到过"、"坑"时触发。 |
Pitfall Journal
记录开发过程中遇到的"坑"——那些不看代码逻辑觉得应该没问题、但实际运行时才暴露的问题。 与 dev-changelog 互补：changelog 记"做了什么"，pitfall-journal 记"踩了什么坑、怎么爬出来的"。
数据文件
所有记录存放在 .cursor/pitfalls/pitfalls.md。
条目格式
### [PF-YYYYMMDD-HHMM] 一句话标题
- **症状**: 用户/系统看到的错误表现
- **根因**: 技术层面的真正原因
- **解法**: 具体怎么修的
- **防御**: 以后如何避免（可选，如果有通用性的话）
- **关联**: 相关文件、模块、技术栈标签
操作 A：写入记录
触发条件
以下任一场景触发：
- 调试完成后 — 经历了 debug 过程并找到了非显而易见的根因
- 用户主动提及 — "记录一下这个坑"、"以后别再犯"
- Agent 识别到经验价值 — 问题涉及框架/库的隐式行为、配置陷阱、环境差异等
以下情况不触发：
- 纯拼写错误、简单语法错误
- 问题原因一目了然（如变量名打错）
- 纯业务逻辑调整（不涉及"坑"的语义）
流程
1. 生成条目 ID：PF-YYYYMMDD-HHMM
2. 从调试过程中提取：症状、根因、解法
3. 归纳防御措施（如果有通用性）
4. 读取 pitfalls.md，在顶部追加新条目
5. 在回复末尾附：[已记录到踩坑日志]
静默写入原则
与 dev-changelog 一致——Agent 自己调试出来的问题，不需要用户确认就可以记录。
操作 B：自动匹配检索
触发条件
当 Agent 在当前任务中遇到以下情况时，应主动检索 pitfalls.md：
- 进入 Debug mode — 读取 pitfalls.md，扫描是否有与当前错误症状匹配的记录
- 同类错误再现 — 错误信息关键词与已有条目的"症状"匹配
- 涉及已知高危区域 — 当前操作涉及的模块/技术栈在已有条目的"关联"中出现
匹配策略
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 过程中发现的必要检查项。
已知必要检查
-
顶部插入必须保持旧首条目完整性 — 使用 StrReplace 在文件顶部插入新条目时（操作 A 第 4 步），anchor（
old_string）有且仅有两种合法选择： (a) 只包含新条目之前的"稳定前缀"（如---\n\n或整个文件头部说明段），不触及任何已有条目的任何一行；然后new_string= 稳定前缀 + 新条目完整内容 + 空行。 (b) 把旧首条目的完整多行内容（标题行 + 全部字段行）都纳入old_string；然后new_string= 新条目完整内容 + 空行 + 旧首条目完整内容。绝对禁止：把旧首条目的"标题行"单独当 anchor 而不带上它紧跟的字段行——StrReplace 是精确替换，这样做会删掉标题、让字段"无主"残留在新条目之后，造成半损坏状态（2026-04-20 实际踩过此坑）。
写入后自检：Read 文件头 25 行，确认看到
### [PF-新ID]后紧跟其 5 字段，再往下能看到### [PF-旧首条目ID]标题行且字段完整跟随。