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

# Pitfall Journal

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

## 数据文件

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

## 条目格式

```markdown
### [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. **顶部插入必须保持旧首条目完整性** — 使用 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]` 标题行且字段完整跟随。