lesson-capture

lesson-capture

核心定位：沉淀那些"光烧 token 无法高效解决"的经验。简单的代码题、走通流程、参数调整不在范围内。

一、触发时机

自动触发（AI 主动判断）

刚完成以下任一动作 → 进入「评估流程」：

• 帮用户做了 git commit + git push，且对应工作量 ≥ 1 个有意义的 feature/fix
• 帮用户开了 PR / MR / CR（gh pr create / 飞书 meego 等）
• 一段较长的调试会话刚收尾（用户说"修好了 / 通了 / 跑起来了"）

手动触发

用户说：

• 「这段值不值得沉淀」
• 「复盘一下刚才的工作」
• 「提了 MR / 推完了」
• 「commit 完了能不能总结一下」

二、价值判别（启发式）

目的：过滤掉绝大多数没沉淀价值的工作，只对真正有价值的提案。宁可漏报，不可误报。

加分信号（命中 ≥ 2 个即考虑提案）

信号	例子
巨大的「假象 → 真相」落差	最终修法只有几行，但花了几小时找
跨边界问题（不只是看自己代码）	前后端契约不一致 / 跨端数据隔离 / 上下游版本错配
走过 ≥ 2 个错误方向	先怀疑环境 → 再怀疑前端 → 最后是后端字段缺失
关键转折点是「换视角才看出来」	把 platformCode 改成 iOS 才发现接口隔离 / 抓双端 diff 才看出契约错位
静默错误 / 隐式行为	NaN 在 JS 里不报错 / undefined 进 Number() / promise 吞错
修复涉及兜底约定（不只是修一个具体 bug）	决定"所有 sparse 响应都 ?? 0 兜底"这类通用约定
后端 / 设计 / 协议侧也得改	不是纯前端能 fix 的，需要跨角色沟通

减分信号（命中即倾向跳过）

信号	例子
纯写新功能、按 PRD 直译，没卡点	加个按钮、加个 store action
简单 typo / 格式 / lint 修复	rename、调样式、改 import 路径
一次 grep 就找到的 bug	"某常量写错值"、"if 写反了"
重构 / 抽包 / 升级依赖	没暴露未知问题的纯结构性改动
用户已经知道答案、AI 只是执行	"把 X 改成 Y" 类指令式任务

决策

• 加分 ≥ 2 且 没有压倒性减分信号 → 进入提案流程
• 否则 → 静默跳过，不要发任何"无值得沉淀"的客气话，直接让对话流自然继续

三、提案流程

Step 1：收集素材

并行执行：

1. git log --oneline -5（看最近 commit）
2. git diff HEAD~1 或针对相关 commit 的 git show --stat（看实际改动规模）
3. 翻阅当前会话上下文，找：
   • 用户表达过的"奇怪 / 怎么会这样 / 不应该"等惊讶
   • AI 走过的死胡同 / 被推翻的假设
   • 关键转折点的工具调用（哪个命令一执行就破案）

Step 2：起草

按 模板 生成 200-400 字草稿，不要塞细节代码——重点是认知结构：

• 现象（用户感知）
• 根因（一句话）
• 走过的弯路 + 为啥卡这么久
• 关键转折点
• 下次如何避免（行动建议，不是空话）

Step 3：判路径

• 强项目特异（只对此需求/此模块有效）→ 写到 需求/<需求名>/复盘/<标题>.md
• 跨项目通用（同类型 bug 在别处也可能出现）→ 写到 经验/<分类>/<标题>.md

分类目录建议：

• 经验/前后端契约/
• 经验/跨端/
• 经验/调试方法/
• 经验/静默错误/
• 经验/工具与流程/

Step 4：向用户提案

用这个格式（保持简短，3-5 句话就够）：

🔍 这段工作有沉淀价值：
   <一句话标题>

   命中信号：<2-3 个加分信号>
   建议位置：<vault 路径>

   要我写入吗？（y / 调整 / 跳过）

Step 5：写入

用户同意后：

1. 用 Read 检查目标路径是否已有同主题文档（避免重复）
2. 用 Write 创建新文件（按模板）
3. 如果是项目特异，同时在该需求的 index.md 里加一行链接
4. 报告写入的相对路径

四、Vault 路径自检测

不要硬编码。按下面顺序探测：

1. 当前工作目录或祖先目录里有 CLAUDE.md 包含 Dots Vault 字样 → 该目录即 vault 根
2. ~/Desktop/dots-vault/ 存在 → 用它
3. ~/Documents/Obsidian/dots-vault/ 存在 → 用它
4. 都没找到 → 问用户 vault 在哪

五、模板

---
type: lesson
created: YYYY-MM-DD
source_commit: <sha or 多个>
source_pr: <url 或空>
category: <前后端契约 | 跨端 | 静默错误 | 调试方法 | 工具与流程 | ...>
time_wasted: <~30min | ~半天 | ~1天>
related_module: <需求名/模块 或 cross-project>
tags: [关键词1, 关键词2]
---

# <一句话标题>（最好包含"看似 X 实则 Y"的对比）

## 现象

<用户/开发者第一眼看到的"不对劲"。1-2 段。>

## 根因

<最终查明的真实原因，一句话或最多两段。>

## 走过的弯路（为什么卡这么久）

| 弯路 | 实际占用 |
|---|---|
| <弯路 1> | <~xx min> |
| <弯路 2> | <~xx min> |

## 关键转折点

<哪个操作 / 哪个视角切换让真相显现。这是"下次该怎么做"的种子。>

## 下次如何避免（沉淀 N 条）

1. **<条目标题>**：<具体可执行的做法，不是空话>
2. ...

## 关联

- commit: <sha>
- PR/MR: <url>
- 相关代码：<file:line>

六、行为约束（重要）

1. 不要每次都触发——多数功能开发没沉淀价值，强行写只会污染知识库
2. 没值得说就完全沉默——不发"暂无可沉淀内容"这类客气话
3. 草稿必须基于真实素材——不要从训练数据"想象"用户可能踩了什么坑，必须从 git diff / 会话上下文找证据
4. 去重——写之前检查 经验/ 和相关 需求/.../复盘/ 下是否已有同主题文档；有就提"已有 X，是否补充而不是新建"
5. 不要替用户决定路径——项目特异 vs 跨项目通用 边界模糊时，让用户选
6. 写入后立刻给文件路径，方便用户即时 review 和编辑

七、与其他 skill 的协作

• 配合 ai-coding-workflow：本 skill 写到的 vault 就是 ai-coding-workflow 管理的同一个 Obsidian 知识库
• 如果 ai-coding-workflow 已在为当前会话工作 → 直接复用它已识别的 vault 路径，不要重复探测