ClaudeInit/.claude/skills/pitfall-journal/SKILL.md

name, description

name	description
pitfall-journal	Pitfall experience recording system. Records root causes and solutions after debugging or discovering non-obvious pitfalls, and automatically retrieves matching entries when similar issues arise. Triggers when debug completes, issues recur, or the user mentions "踩坑", "之前遇到过", "坑", or when entering Debug mode.

Pitfall Journal

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

数据文件

所有记录存放在 .claude/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 过程中发现的必要检查项。

已知必要检查

1. 顶部插入必须保持旧首条目完整性 — 使用 Edit 在文件顶部插入新条目时（操作 A 第 4 步），anchor（old_string）有且仅有两种合法选择： (a) 只包含新条目之前的"稳定前缀"（如 ---\n\n 或整个文件头部说明段），不触及任何已有条目的任何一行；然后 new_string = 稳定前缀 + 新条目完整内容 + 空行。 (b) 把旧首条目的完整多行内容（标题行 + 全部字段行）都纳入 old_string；然后 new_string = 新条目完整内容 + 空行 + 旧首条目完整内容。

   绝对禁止：把旧首条目的"标题行"单独当 anchor 而不带上它紧跟的字段行——Edit 是精确替换，这样做会删掉标题、让字段"无主"残留在新条目之后，造成半损坏状态（2026-04-20 实际踩过此坑）。

   写入后自检：Read 文件头 25 行，确认看到 ### [PF-新ID] 后紧跟其 5 字段，再往下能看到 ### [PF-旧首条目ID] 标题行且字段完整跟随。