Lessons Learned Log

---
name: lessons-learned-log
description: "踩坑记录——把出错、返工、被纠正的经历记成可检索的条目，做类似任务前先按关键词查一遍，避免同一个坑踩两次。当用户说「记一下这个坑」「以后别再犯这个错」「开工前先查查踩过的坑」「整理踩坑记录」时使用。"
author: Captain
version: 0.1.1
display_name: "踩坑记录"
display_name_en: "Lessons Learned Log"
description_zh: "踩坑记录：出错、返工、被纠正后，按现象、根因、正确做法、触发场景、验证方式记一条，存成按主题分文件的 Markdown；开工前用附带的 Python 标准库脚本按关键词检索；定期合并重复、淘汰过时条目。适用于 AI 助手，也适用于个人工作笔记。"
description_en: "Turn every mistake, rework or correction into a searchable lesson entry in plain Markdown, search it by keyword before similar tasks with a bundled standard-library Python script, and periodically merge or retire stale entries."
tags:
  - "踩坑记录"
  - "踩坑"
  - "避坑"
  - "经验教训"
  - "错题本"
  - "复盘笔记"
  - "lessons learned"
  - "mistake log"
examples_zh:
  - "刚才你把文件路径写错了，记一下这个坑，以后别再犯"
  - "开始写这份周报前，先查查我们以前踩过哪些坑"
  - "踩坑记录攒了几十条，帮我合并重复的、清理过时的"
examples_en:
  - "You just got the file path wrong. Log this mistake so it doesn't happen again"
  - "I have dozens of lessons-learned entries. Merge the duplicates and retire the stale ones"
---

# 踩坑记录

定位一句话：**记录本身不值钱，开工前真的去查才值钱。** 把每次出错、返工、被纠正变成一条下次能搜到、能照做的记录。适用于 AI 助手的长期协作，也适用于人自己的工作笔记。

## 何时使用

用户这样说时启用：

- 「记一下这个坑」「刚才你把文件路径写错了，以后别再犯」
- 「开工前先查查我们以前踩过哪些坑」「写这份周报前查一下有没有相关记录」
- 「这个问题上次是不是遇到过」
- 「踩坑记录攒了几十条，帮我合并重复的、清理过时的」
- 「帮我看看这些记录格式对不对」

AI 助手也要主动启用：被纠正、返工、卡住超过 10 分钟等六种情况出现时当场记一条；做以前做过的同类任务、执行不可撤销的动作之前先查一遍（见下一节）。

调用方式：在对话里说即可。检索和复核用附带脚本 `python3 scripts/lessons_search.py <记录目录> 关键词…`，只读不写；新条目由助手按格式写好，写进用户约定的目录。

不适用（遇到时这样处理）：

- 造成实际损失的事故复盘、责任认定 → 走单位的复盘流程，这里只沉淀可复用的做法。
- 记录人际矛盾、对某人的评价 → 不记；只记事，不记人。
- 会议纪要、待办清单、一般知识笔记 → 用笔记或待办工具；这里只记「出错—根因—下次怎么做」。

## 什么时候必须记、什么时候先查

出现下面任何一种，当场记一条，不等「有空再整理」：

1. 被用户纠正：「不对」「我之前说过」「不是这个意思」；
2. 返工：交出去的东西被退回重做；
3. 报错或卡住超过 10 分钟，最后找到的原因并不显而易见；
4. 说错了事实：把推测当结论，被指出没有依据；
5. 差点出事：发错对象、删错文件、覆盖了别人的版本，哪怕及时拦住了；
6. 同一个问题第二次出现——第一次没记，第二次必须记。

不用记：纯手滑的错别字、一次性且不会再遇到的环境问题、总结不出可照做动作的事。

先查的时机：开始一项以前做过同类的任务之前；执行发送、删除、覆盖、付款这类不可撤销的动作之前；用户提到「上次那个问题」时。

## 条目格式与存放位置

一坑一条，以 `### ` 开头，字段各占一行，脚本按字段检索：

```markdown
### 交付文件只写了相对路径，用户找不到
- 关键词：路径, 文件位置, 交付, 链接
- 触发场景：把报告、表格、网页结果交给用户时
- 现象：用户回复「report.html 在哪？打不开」
- 根因：默认用户和我在同一个目录，实际不在
- 正确做法：交付物一律写完整路径，如 /Users/xiaowang/周报/report.html
- 验证方式：交付前把路径粘到文件管理器地址栏，能直接打开
- 类别：被用户纠正（第 2 次）
- 最后验证：2026-09-19
- 状态：有效
```

写法要求：现象写可观察的事实（原话、报错原文）；根因写「为什么会这样」，不写「粗心」；正确做法写成下次能照做的动作，带具体值；验证方式写怎么确认做对了；类别写被纠正、返工、报错或差点出事，括号里记第几次；状态只用「有效」「存疑」「已过时：原因」三种。

存放：纯文本 Markdown，放固定目录——个人用 `~/lessons/`，项目用项目根目录下的 `lessons/`。按主题分文件，如 `文件与路径.md`、`写作与格式.md`、`日程与时间.md`；新主题先放 `杂项.md`，攒够 5 条再拆出去；单个文件超过约 30 条再拆。

## 流程：开工前查，出错后记

检索脚本是 `scripts/lessons_search.py`：单文件、只用 Python 标准库、只读不写，也可以单独复制到记录目录旁边用。

```bash
python3 scripts/lessons_search.py ~/lessons 路径 交付 周报     # 检索
python3 scripts/lessons_search.py ~/lessons --all 路径         # 连「已过时」的一起列
python3 scripts/lessons_search.py ~/lessons --stale 90         # 90 天没复核的条目
python3 scripts/lessons_search.py ~/lessons --lint             # 检查必填字段、状态、日期、正确做法是否像态度
python3 scripts/lessons_search.py ~/lessons --dupes            # 按关键词重合度列出疑似重复
```

开工前：

1. 从任务里抽 3–5 个关键词：对象（周报、表格）、动作（导出、发送、覆盖）、环境（macOS、Windows）。
2. 运行 `python3 scripts/lessons_search.py ~/lessons 路径 交付 周报`。方括号里是得分，命中标题、关键词、触发场景的会额外加分；同分按文件名、标题排序，同样的记录和关键词每次输出一致。
3. 把命中条目的「正确做法」写进本次计划，逐条当检查项执行；没命中也要说一句「已查踩坑记录，无相关条目」。

出错后：

1. 先解决问题，再按格式写一条，放进对应主题文件；
2. 写之前用同样的关键词查一次：已有同根因的条目就更新它（类别里的次数加一、补充现象、改最后验证日期），不另开新条；
3. AI 助手第一次在用户电脑上建记录目录前，先问一次存放位置；不能写文件时，把整条输出给用户自己保存。

## 定期合并与淘汰

每月一次，或每新增 20 条做一次：

1. 运行 `python3 scripts/lessons_search.py ~/lessons --stale 90`，列出 90 天没复核的条目；
2. 逐条判断：仍然成立的改「最后验证」日期；工具或流程已变的，状态改成「已过时：原因」——不删除，脚本默认不再列出，加 `--all` 才显示；
3. 合并同根因的条目：先跑 `--dupes` 找关键词高度重合的条目对，逐对判断是不是同一根因；是就把现象合并列出，次数相加，保留写得最具体的那条正确做法；只是话题相近的保留两条；
4. 同一个坑出现 3 次以上，说明光记录不够，把它升级成固定规则，写进工作规范或助手的常驻指令；
5. 最后跑一次 `--lint`，看到「格式都合格」再收尾。

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（模板） |
|---|---|---|
| 缺关键信息：用户只说「记一下」，没说正确做法 | 只问 1–2 个：正确做法是什么？下次什么场景会再遇到？能从上下文推出的现象、根因先填，标 [待确认] | 「记之前确认两点：正确做法是『交付写完整路径』对吗？下次最可能在什么场景再遇到？」 |
| 说法矛盾：这次的纠正和旧条目的正确做法相反 | 指出冲突，给两种理解：规矩变了（旧条改「已过时：原因」），或这次是特例（旧条不动、新条写清适用场景）；以用户当前要求为准 | 「记录里写的是『A』，你这次要『B』：是规矩变了，还是这次特殊？」 |
| 超出范围：事故复盘、追责、要记对某人的评价 | 不写评价；有实际损失的走单位复盘流程；只提取可复用的做法 | 「这件事有实际损失，建议走正式复盘；我这里只记以后能照做的那一条。」 |
| 时间紧，只要最小可用版 | 最小版 = 标题 + 正确做法 + 触发场景三行，状态标「存疑」，其余字段标 [待补]，事后补齐 | 「先记三行：标题、下次怎么做、什么场景会遇到；其余标了 [待补]，有空再补。」 |
| 坚持越界：要把密码、账号、身份证号写进记录，或写某同事「不靠谱」 | 守住：敏感信息改写成「凭据从密码管理工具取」这类指引；只记事，不记人 | 「密码不能写进记录，它会长期保存、可能被分享；我写成『凭据从密码管理工具取』。」 |
| 没法写文件：用户没给目录，或没有写入权限 | 先问存放位置；不能写就把整条输出给用户自己保存 | 「记录放哪？个人的建议 ~/lessons/，项目的放项目根目录的 lessons/，你定了我再写。」 |
| 检索没命中 | 对象、动作、环境各换一个同义词再查一次；仍没有就明说 | 「已查踩坑记录（关键词：周报、导出、路径），无相关条目。」 |

`scripts/lessons_search.py` 报错对照：

| 退出码 / 提示 | 原因 | 修正办法 |
|---|---|---|
| 0 | 成功；没命中也是 0，并打印「没有相关记录」 | 把命中条目的正确做法写进本次计划 |
| 1「参数错误：…」 | `--stale` 不是非负整数；`--lint`、`--dupes`、`--stale` 同时用了 | 按提示改；一次只用一种模式 |
| 2「找不到记录目录」 | 路径写错，或还没建目录 | 核对路径；第一次使用先问用户放哪 |
| 3「还没有任何条目」 | 目录里的 .md 没有以「### 」开头的条目 | 按条目格式写第一条 |
| 4（`--lint`） | 缺必填字段、状态写法不对、日期不是 2026-09-19 格式、正确做法像态度 | 按每行提示补齐，重跑到「格式都合格」 |
| 130「已中断」 | 按了 Ctrl+C | 脚本只读，直接重跑 |

## 输出契约

按场景交付，每种场景的内容按固定顺序：

- **记录时**：① 完整条目（现象、根因、正确做法、触发场景、验证方式五项必填）；② 写入文件的完整路径；③ 新建还是更新，更新时说明改了哪几行；④ 还缺的字段清单。
- **查询时**：① 所用关键词；② 命中条目（标题 + 正确做法）；③ 据此加进本次计划的检查项；无命中明确说「已查踩坑记录，无相关条目」。
- **复核时**：① 过期条目清单；② 每条的处理结果（续期 / 已过时：原因 / 合并到哪一条）；③ 出现 3 次以上、要升级成固定规则的条目。

占位符：只有用户知道的（正确做法、触发场景）没给时写 [待补]；从上下文推断的（根因）写 [待确认]；做法还没验证过，状态写「存疑」。不编造报错原文和用户原话。

交付前自检（逐条答是/否）：

- [ ] 五项必填都有，正确做法里没有「以后注意」「要细心」这类态度词？
- [ ] 写之前查过同关键词，同根因的是更新旧条而不是另开新条？
- [ ] 没有对人的评价，没有密码、账号、身份证号？
- [ ] 交付里写了记录文件的完整路径？
- [ ] 查询没命中时，明说了「已查踩坑记录，无相关条目」？
- [ ] 批量整理后跑了 `--lint`，结果是「格式都合格」？

## 示例

以下为示例：记录目录是一份示例目录，输出是对它实际运行脚本的结果。

**用户**：开始写这份周报前，先查查我们以前踩过哪些坑。

**助手**（不需要追问，直接从任务里抽关键词：周报、数字、交付、路径）：

```bash
python3 scripts/lessons_search.py ~/lessons 周报 数字 交付 路径
```

```text
[17] 文件与路径.md | 交付文件只写了相对路径，用户找不到 | 有效 2026-09-19
    正确做法：交付物一律写完整路径，如 /Users/xiaowang/周报/report.html
    验证方式：交付前把路径粘到文件管理器地址栏，能直接打开
[16] 写作与格式.md | 周报里把推测写成了结论 | 有效 2026-08-30
    正确做法：没有出处的数字标「估计」并写明依据，或删掉
    验证方式：交付前逐个数字问一遍「出处在哪」
[11] 文件与路径.md | 网页结果的链接写成了相对地址 | 有效 2026-06-01
    正确做法：链接写完整路径，交付前自己点一遍
    验证方式：在另一个目录的终端里打开链接，能直接打开
共 3 条
```

**助手交付**：

```text
已查踩坑记录（关键词：周报、数字、交付、路径），命中 3 条，本次周报加入检查项：
□ 每个数字都有出处；没有出处的标「估计」并写依据，或删掉        ← 周报里把推测写成了结论
□ 交付的文件写完整路径，交付前粘到文件管理器地址栏试开一次      ← 交付文件只写了相对路径
□ 文中链接写完整路径，交付前自己点一遍                          ← 网页结果的链接写成了相对地址
```

更多完整示例：[被纠正后记一条（含查重与更新旧条）](examples/log-a-correction.md)、[月度整理：过期、重复、格式三步走](examples/monthly-cleanup.md)。

## 常见问题（FAQ）

**Q：记录放在哪？**
A：纯文本 Markdown 放固定目录：个人用 `~/lessons/`，项目用项目根目录的 `lessons/`，按主题分文件。AI 助手第一次建目录前会先问你。

**Q：和普通笔记、待办有什么区别？**
A：每条都是「出错—根因—下次怎么做—怎么验证」，开工前按关键词查；会议纪要和待办不放这里。

**Q：攒了几十条，开工前查不过来怎么办？**
A：只按本次任务抽 3–5 个关键词查，只读命中的几条；已过时的默认不显示。

**Q：旧条目和我现在的要求冲突怎么办？**
A：以你当前的明确要求为准，并指出冲突；旧条目改成「存疑」或「已过时：原因」。

**Q：能不能不用我每次提醒，自动记？**
A：出现被纠正、返工等六种情况时，AI 助手应当场记一条；写进文件按你约定的位置进行，没约定就先问。

**Q：同一个坑反复出现怎么办？**
A：出现 3 次以上说明光记录不够，升级成固定规则，写进工作规范或助手的常驻指令。

**Q：没有 Python 能用吗？**
A：能。记录本身是纯文本，用编辑器的全文搜索按关键词找也行；脚本只是多了打分排序、过期筛选、格式检查和查重。

**Q：几个人能共用一个记录目录吗？**
A：可以放在项目目录里共享。记事不记人，也不写敏感信息，因为记录会长期保存，也可能被转给别人。

## 常见错误（反模式）

| 错误做法 | 为什么错 | 正确做法 |
|---|---|---|
| 只写现象不写根因：「导出失败了」 | 下次还是不知道怎么办 | 根因写「为什么会这样」，不写「粗心」 |
| 正确做法写成态度：「以后注意」「要细心」 | 没法照做，也没法验证 | 写成带具体值的动作，如「写 CSV 用 utf-8-sig 编码」 |
| 不写触发场景和关键词 | 记了但永远搜不到 | 关键词覆盖对象、动作、环境；触发场景写「在做什么的时候」 |
| 一条里塞三个坑 | 命中后分不清哪句有用 | 拆开写，一坑一条 |
| 只记不查 | 开工前从不打开，等于没记 | 开工前按 3–5 个关键词查一遍；没命中也说一句 |
| 同根因另开新条 | 条目越攒越多，查出来互相重复 | 写之前先查；同根因就更新旧条：次数加一、改最后验证日期 |
| 过时条目直接删掉 | 丢了「为什么不再这样做」的来龙去脉 | 状态改「已过时：原因」，默认不显示，加 `--all` 还能查到 |

## 边界与不做什么

- 记事不记人：不写对任何人的评价；不写密码、账号、身份证号等敏感信息——记录会长期保存，也可能被分享。
- 不代替事故复盘：造成实际损失的事件走单位的复盘流程，这里只沉淀可复用的做法。
- 记录是参考不是命令：旧条目可能已过时，与用户当前的明确要求冲突时，以用户当前要求为准，并指出冲突。
- 不擅自改用户文件：新建目录、写入或合并记录，按用户约定的位置进行；没约定就先问。