lessons-learned

经验教训

使用此技能维护轻量级项目记忆循环。

将此文件视为经验记忆行为的唯一事实来源： 触发规则、回忆流程、记录流程、限制和验证。 README.md、references/ 和阶段入口命令不得覆盖这些 规则。

触发约定

在以下时机调用此技能：

• 任务开始：在实施前运行回忆。
• 任务期间：当用户纠正你的做法时，运行记录。
• 任务结束：评估记录条件，并自动记录符合条件的经验教训。

以下情况不要触发：

• 没有可复用流程的一次性事实问答。
• 不含可执行指导的纯概念解释。
• 没有技术经验教训的纯格式或管理类编辑。
• 不可复现且没有稳定预防规则的情境。

最简执行保障

当此技能是会话中的主要流程技能时：

• 对于非简单任务（3 步或更多），在实施前创建任务跟踪器。
• 在宣称完成之前，运行相关验证命令并报告证据。
• 不得以假设或部分检查代替验证。

存储

将所有经验教训资料存储在项目根目录下的 docs/lessons/ 中：

docs/lessons/
├── _index.md
├── api-timeout-retry-pattern.md
├── db-migration-run-order.md
└── null-check-before-save.md

每张经验教训卡片都是一则独立的 Zettelkasten 笔记。每张卡片只记录一条可复用经验。

规范限制

在整个技能包中统一遵守以下限制：

• 回忆时加载 1-3 张主要卡片。
• 最多加载 2 张相关卡片。
• 总共最多加载 5 张卡片。
• 每张卡片使用 0-2 个 related 链接。
• 每张卡片使用 3-6 个标签。
• confidence 必须在 0.0-0.9 的闭区间内。

如果其他文件与这些限制冲突，以本文件为准。

回忆阶段

在编写代码之前运行此阶段。

1. 提取任务关键词（技术、故障模式、领域术语）。
2. 确定经验存储是否存在：
   • 如果 docs/lessons/ 不存在，则视为首次运行状态，跳过回忆。
   • 如果 docs/lessons/ 存在但 _index.md 不存在，则在本次回忆过程中直接读取现有卡片的 frontmatter，并提醒应在下次记录／更新维护时重建 _index.md。
3. 根据任务上下文确定工作范围：
   • project：涉及跨领域或整个仓库的问题
   • module：涉及包或目录级的问题
   • feature：涉及特定流程或组件的问题
4. 读取 docs/lessons/_index.md。
5. 从 docs/lessons/ 中的卡片构建常规回忆候选项。
   • 仅排除明确设置了 confidence: 0.0 的卡片。
   • 缺少 confidence 的卡片仍符合条件，并使用旧版回退规则。
   • confidence: 0.0 的卡片仍保留在 docs/lessons/ 中，供明确的历史查询使用。
   • 只有用户明确要求查看常规回忆中排除的卡片时，才加载这些卡片。
6. 按以下顺序对符合条件的候选项排序： 标签匹配 -> 范围匹配 -> confidence（降序） -> 日期（降序）。
   • 仅当缺少 confidence 时才使用旧版回退规则：根据 source 推导其值（user-correction=0.7、bug-fix=0.5、 retrospective=0.3）。如果两者都缺失，则使用 0.3。
7. 加载 1-3 张主要卡片。
8. 根据主要卡片中的 related 链接扩展，最多再加载 2 张卡片。
9. 遵守硬性上限：主要卡片与相关卡片总数不得超过 5 张。
10. 将加载的经验教训作为当前工作的约束，并简要提及已加载的卡片 ID。
11. 回忆时将 confidence 视为只读：
    • 不得因加载了某条经验教训而更改 confidence。
    • 不得因未加载某条经验教训而更改 confidence。
    • 不得因某条经验教训近期未被使用而更改 confidence。

如果没有匹配的卡片，则继续工作，不受经验教训约束。

回忆警告

这些情况不会阻塞流程，请继续：

• 首次运行时缺少 docs/lessons/。
• 缺少 _index.md，因此本次回忆阶段使用了卡片元数据。
• 已加载的卡片缺少 confidence，需要使用旧版回退逻辑。
• 缺少一个 related 目标。

捕获阶段

满足以下任一条件时运行此阶段：

• 用户纠正了你的处理方式
• 用户要求进行捕获
• 修复漏洞时发现了可复用的模式
• 任务完成时发现了不明显但可复用的经验

此阶段适用于两种记忆维护：

• 当前工作发现了可复用的新经验时，创建新的经验卡片
• 当前工作表明已回忆或相关卡片适用性较低、部分过时或不再有效时，更新现有经验卡片

第 1 步 — 决定是否捕获

询问：“这条经验能否在下次遇到类似任务时节省时间？”

分别针对以下两项作出决定：

• 是否创建新的经验卡片
• 是否更新现有经验卡片

跳过创建新卡片，并不意味着跳过对现有卡片的纠正性更新。 如果当前工作表明已回忆或相关卡片需要修正，即使没有捕获新经验，也要继续执行第 2 步，更新该现有卡片。

仅捕获不明显的经验。优先记录以下内容：

• 文件／模块之间隐藏的关联。
• 与代码结构所暗示的不同的执行路径。
• 不明显的配置、环境变量、标志或顺序约束。
• 错误消息具有误导性时发现的关键突破。
• 工具／API 的特性及必要的变通方法。
• 附近文档未提及的构建／测试命令或运行前提。
• 为确保正确性而必须同时修改的文件。

满足以下条件时进行捕获：

• ✅ 可复用的模式或决策规则
• ✅ 代价高昂的错误，且有明确的预防策略
• ✅ 容易遗忘的关键参数、配置或前提条件
• ✅ 经多次尝试找到的解决方案（包括失败原因和成功条件）

满足以下条件时更新现有卡片：

• ✅ 当前工作表明，已回忆或相关卡片的适用性不如从前
• ✅ 当前工作表明，已回忆或相关卡片部分过时
• ✅ 当前工作表明，已回忆或相关卡片不应再参与常规回忆

以下情况跳过：

• ❌ 一次性问答，没有可复用的流程
• ❌ 纯概念解释，没有可执行的指导
• ❌ 不可复现、仅适用于特定情境的结论
• ❌ 没有隐藏约束的显而易见的框架／语言行为
• ❌ 不太可能重复出现的会话专属备注

这些跳过规则适用于创建新卡片。当现有证据表明某张卡片应重写或应调整其 confidence 时，这些规则不会阻止对现有卡片进行纠正性更新。

步骤 2 — 编写 Zettel 卡片

创建新卡片时，生成一个描述该经验的语义化 kebab-case ID（例如，api-timeout-retry-pattern）。

写入或更新卡片前，检查是否存在语义相似的卡片，并明确说明决定：

• 当不存在相似卡片，且应记录一条新经验时，使用 decision=create。
• 当相似卡片已涵盖相同经验，或当前工作修正了现有卡片时，使用 decision=update。

仅当一次记录操作中所有受影响的卡片都属于同一种结果时，才使用 decision=create 或 decision=update。如果一次记录操作既创建又更新卡片，只报告 created=<n> 和 updated=<n> 数量。

当一次记录操作影响多个卡片时，报告 created=<n> 和 updated=<n> 数量。如果一次记录操作既创建又更新卡片，请勿包含 decision=。

写入卡片前，先指定 scope：

• project：适用于整个仓库的约束
• module：适用于包或目录级别的约束
• feature：适用于单个流程或组件

根据 source 指定初始 confidence：

• user-correction：0.7
• bug-fix：0.5
• retrospective：0.3

仅在记录或更新时调整置信度，回忆时不得调整。

如果用户明确确认某条经验仍然有用，则将 confidence 增加 +0.1（最高 0.9）。

后续证据表明某条经验的适用性降低时，将 confidence 减少 -0.1。

如果某条经验部分过时，先更新卡片内容，然后仅在需要时降低 confidence。

仅当卡片不应再参与常规回忆时，才将 confidence 直接设为 0.0。

不得仅因近期未使用某条经验而降低 confidence。

使用 references/card-template.md 中的模板，将卡片写入 docs/lessons/<id>.md。

创建新卡片前，检查是否存在语义重复：

• 如果现有卡片在语义上相似，则更新该卡片，而不是创建重复卡片。
• 更新时保留现有卡片 ID。

当当前工作削弱了被回忆起或相关的卡片时：

• 即使未创建新的经验卡片，也要更新现有卡片
• 如果经验仅部分过时，先更新卡片内容
• 然后仅当该经验的默认适用性比以前降低时，才降低 confidence
• 仅当卡片不应再参与常规回忆时，才将 confidence 设为 0.0

最简更正记录示例：

经验记录报告：decision=update，updated=1（db-migration-run-order），confidence=0.7->0.6（当前配置下适用性降低），skipped=0

卡片字段：

字段	用途
id	语义化 kebab-case slug，同时也是文件名
date	记录该经验时的 ISO 日期
scope	适用范围：project / module / feature
tags	用于回忆匹配的 3–6 个小写标签
source	user-correction / bug-fix / retrospective
confidence	用于回忆排序的数值置信度分数
related	0–2 条高相关度经验引用，使用 [[card-id]]
标题	对该经验的一行概述
背景	发生错误时的情况
错误	出错之处
经验	提炼出的规则或最佳实践
适用场景	该经验适用的未来场景

任务结束时的行为：

• 如果符合记录条件，则自动记录，无需事先征求许可。
• 记录后，报告创建或更新的内容。
• 面向普通用户的输出优先采用简短的记录摘要。
• 除非用户要求查看，否则不要复述完整的卡片内容。

步骤 3 — 更新索引

在 docs/lessons/_index.md 中为每个卡片 ID 新增或更新一行。

如果 _index.md 不存在，则按以下结构创建：

# Lessons Index

> Auto-generated by lessons-learned skill. Do not edit manually.

| Card | Scope | Tags | Date |
|---|---|---|---|

然后按 Date 降序排列各行（最新的在前）。

步骤 4 — 向用户确认

使用简洁的报告告知用户记录了哪些内容，例如：

Lessons 记录报告：已创建=1（api-timeout-retry-pattern）、已更新=1（db-migration-run-order）、已跳过=1（明显行为）

如果所有受影响卡片的结果类型相同，请在报告中加入 decision=create 或 decision=update。如果一次记录同时创建和更新了卡片，只报告 created=<n> 和 updated=<n> 数量。

如果记录或更新改变了置信度，请为每张受影响的卡片注明置信度变化 old->new，并附上简短原因。

对于新卡片，使用 none-><value>。

如果变化结果为 0.0，请明确说明该卡片已从正常召回中排除。

示例：

• Lessons 记录报告：decision=create，created=1（\api-timeout-retry-pattern`），confidence=none->0.5（新的可复用模式）`
• Lessons 记录报告：decision=update，updated=1（\db-migration-run-order`），confidence=0.7->0.6（在当前配置下适用性较弱）`
• Lessons 记录报告：decision=update，updated=1（\legacy-bootstrap-flow`），confidence=0.1->0.0（已从正常召回中排除）`

确认信息应简短。优先说明决策、受影响的卡片 ID，以及一行规则摘要。正常情况下，避免倾倒完整的 Markdown 卡片或索引内容。

链接规则

仅为高价值卡片添加 related 链接。

当以下 4 项条件中至少满足 2 项 时，创建 related 链接：

1. 可复用于不同任务。
2. 代表代价高昂的错误（多次尝试或显著的时间损失）。
3. 依赖关键参数、配置或决策细节。
4. 与至少两张现有经验卡片有自然关联。

链接限制：

• 每张卡片添加 0–2 个 related 链接，仅在关联性强时添加。
• 使用 references/linking-heuristics.md 中的确定性排序规则。
• 不要添加关联较弱或推测性的链接。

失效的 related 目标不会阻塞流程：

• 如果 related 目标缺失，请忽略它并发出警告。
• 继续召回或记录流程。

反模式

• 记录没有隐藏约束的明显语言或框架行为。
• 记录仅限当前会话的笔记（临时日志、临时本地路径、一次性环境噪声）。
• 编写冗长叙述，却没有可执行的预防规则。
• 在更新现有卡片即可解决时，创建近似重复的卡片。
• 记录宽泛建议，却未在 When to Apply 中给出具体触发条件。

验证

记录或更新时应用以下检查。除非其他位置明确列为警告，否则这些检查失败会阻塞流程。

• 卡片文件名与 id slug 一致。
• date 格式为 ISO YYYY-MM-DD。
• scope 是 project、module 或 feature 之一。
• tags 数量为 3–6。
• source 是有效枚举值。
• confidence 是数值，且范围为 0.0-0.9。
• related 数量为 0–2，且每个目标都指向现有卡片。
• 索引行存在，且与卡片元数据一致，包括 scope。
• _index.md 中的行按 Date 降序排列（最新的在前）。

集成指南

在同一会话中与其他技能配合使用时，以 Trigger Contract 作为唯一事实来源：

• 任务开始 -> 召回
• 工作期间用户纠正 -> 记录
• 任务结束 -> 评估是否记录

这是一个不可替代的步骤——经验记录不能由待办事项跟踪器、进度文件或其他技能产物替代。