insight-extraction

洞察提取技能

概述

分析已完成的编码会话，并为记忆系统提取结构化经验。洞察能帮助未来的会话避免错误、遵循既定模式，并更快了解代码库。

核心原则： 提取可执行的知识，而不是日志。每条洞察都应帮助未来的会话把事情做得更好。

适用场景

始终适用：

• 完成编码任务后
• 修复 Bug 后
• 发现新模式后
• 尝试失败后（尤其有价值）

例外情况：

• 没有经验可总结的琐碎更改
• 仅涉及文档的更改

铁律

NO SESSION END WITHOUT INSIGHT EXTRACTION FOR NON-TRIVIAL WORK

非琐碎的会话应在上下文丢失前记录经验。

所需输入

提取洞察需要：

1. Git diff - 哪些文件发生了更改，以及如何更改
2. 任务描述 - 正在实现什么
3. 尝试历史 - 之前的尝试（如有）以及采用过的方法
4. 会话结果 - 成功或失败

工作流

阶段 1：收集会话数据

# Get the diff of changes
git diff HEAD~1 --stat
git diff HEAD~1

# Get commit message
git log -1 --pretty=format:"%s%n%n%b"

# Get list of modified files
git diff HEAD~1 --name-only

阶段 2：分析文件洞察

针对每个已修改的文件，提取：

• 用途：此文件发挥什么作用？
• 所做更改：做了什么修改？重点说明“为什么”，而不只是“是什么”
• 所用模式：应用了哪些编码模式？
• 注意事项：此文件有哪些特定陷阱？

良好示例：

{
  "path": "src/stores/terminal-store.ts",
  "purpose": "Zustand store managing terminal session state with immer middleware",
  "changes_made": "Added setAssociatedTask action to link terminals with tasks",
  "patterns_used": ["Zustand action pattern", "immer state mutation"],
  "gotchas": ["State changes must go through actions, not direct mutation"]
}

不良示例（过于笼统）：

{
  "path": "src/stores/terminal-store.ts",
  "purpose": "A store file",
  "changes_made": "Added some code",
  "patterns_used": [],
  "gotchas": []
}

阶段 3：提取模式

只提取可复用的模式：

• 必须能适用于不止当前这一个案例
• 说明适用的场景和时机
• 引用代码库中的具体示例

良好示例：

{
  "pattern": "Use e.stopPropagation() on interactive elements inside containers with onClick handlers",
  "applies_to": "Any clickable element nested inside a parent with click handling",
  "example": "Terminal.tsx header - dropdown needs stopPropagation to prevent focus stealing"
}

阶段 4：记录注意事项

必须具体且可执行：

• 说明什么情况会触发问题
• 说明如何解决或避免问题
• 避免泛泛而谈的建议（“使用 X 时要小心”）

良好示例：

{
  "gotcha": "Terminal header onClick steals focus from child interactive elements",
  "trigger": "Adding buttons/dropdowns to Terminal header without stopPropagation",
  "solution": "Call e.stopPropagation() in onClick handlers of child elements"
}

阶段 5：记录方法结果

总结成功或失败带来的经验：

• 如果成功：这种方法为何有效？关键因素是什么？
• 如果失败：失败原因是什么？什么方法原本可以奏效？
• 尝试过的替代方案：还尝试了哪些其他方法？

这有助于未来的会话从过去的尝试中学习。

阶段 6：生成建议

为未来的工作提供具体、可执行的建议：

• 未来的会话必须能够据此采取行动
• 应针对当前代码库，而不是泛泛而谈
• 着重说明后续工作或需要留意的事项

良好示例：“为 Terminal 标题栏添加更多控件时，沿用本次会话中的下拉菜单模式——使用 stopPropagation，并相对于标题栏定位”

不良示例：“编写优质代码”或“充分测试”

阶段 7：输出结构化洞察

创建结构化的洞察输出：

# Session Insights: [Task Name]

## Date

[timestamp]

## Task

[Description of what was being implemented]

## Outcome

[SUCCESS/FAILURE]

## File Insights

### [file-path]

- **Purpose**: [what this file does]
- **Changes**: [what was changed and why]
- **Patterns**: [patterns used]
- **Gotchas**: [things to watch out for]

## Patterns Discovered

### [Pattern Name]

- **Pattern**: [description]
- **Applies to**: [when to use]
- **Example**: [file or code reference]

## Gotchas Discovered

### [Gotcha Name]

- **Issue**: [what to avoid]
- **Trigger**: [what causes it]
- **Solution**: [how to handle]

## Approach Analysis

### What Worked

[Description of successful approach]

### What Failed (if applicable)

[Description of failed approaches and why]

### Alternatives Tried

[List of other approaches attempted]

## Recommendations for Future Sessions

1. [Specific recommendation 1]
2. [Specific recommendation 2]

保存到 .claude/context/memory/learnings.md（追加）。

边界情况处理

diff 为空或改动极少

如果 diff 很小或为空：

• 如果能推断文件用途，仍应提取相关信息
• 说明本次会话只做了少量更改
• 着重为后续步骤提出建议

会话失败

如果会话失败：

• 着重分析失败原因——这是最有价值的洞察
• 总结从失败中学到的内容
• 建议应说明下次如何成功

更改了多个文件

• 优先处理最重要的 3-5 个文件
• 跳过样板文件的更改（如 package-lock.json 等）
• 着重分析与功能直接相关的文件

验证清单

完成洞察提取前：

• 已分析 Git diff
• 已提取关键文件的洞察
• 已记录可复用模式
• 已记录注意事项，并说明触发条件和解决方法
• 已记录方法结果
• 建议具体且可执行
• 洞察已保存到记忆文件

常见错误

过于笼统

为什么不对：“修复了 Bug”对任何人都没有帮助。

应这样做：“在 useEffect 中添加清理函数，修复了竞态条件。模式：异步 effect 始终应返回清理函数。”

通用建议

为什么不对：“测试你的代码”不可执行。

应该这样做：“更改存储逻辑后，运行 npm test src/stores——测试会捕获状态管理错误。”

缺少上下文

**为什么不对：**后续会话无法理解其中的原因。

**应该这样做：**包含文件路径、函数名称和具体场景。

与其他技能集成

此技能适用于：

• session-handoff：在交接文档中使用洞见
• summarize-changes：用洞见补充变更摘要
• debugging：从调试会话中提取洞见

铁律

1. 始终在任务完成后立即提取洞见——延迟提取会丢失上下文；“做了什么”可以重建，但“为什么”会在会话中逐渐消失。
2. 绝不记录做了什么——只记录学到了什么；活动日志应放在任务元数据中，而不是学习系统中。
3. 始终在写入前检查是否有重复洞见——追加近似重复的洞见会污染记忆索引，降低未来检索质量。
4. 绝不写“X 很好”这类缺乏具体上下文、文件路径或示例的模糊洞见——模糊的洞见无法查找，也无法为后续会话提供帮助。
5. 始终为洞见标注领域类别（[CODE]、[WORKFLOW]、[SECURITY] 等）——未标注的洞见对于按领域搜索的 Agent 来说实际上不可见。

反模式

反模式	失败原因	正确做法
记录活动（“实现了身份验证”），而不是经验教训	Agent 可以从 git 重建历史记录，却无法重建隐性知识	记录“原因”和“注意事项”：“Fiber 的 CSRF 中间件必须放在路由注册之前，而不是之后”
跳过重复项检查	重复条目会增加记忆大小，并使检索混乱	追加前运行 grep -i "keyword" learnings.md；如果找到现有条目，则更新它
洞见模糊，缺少文件或函数上下文	后续会话无法定位或应用该洞见	提供具体路径：“在 .claude/hooks/routing/routing-guard.cjs 第 47 行：解析错误时退出码为 0”
只在会话结束时提取	会话过长会丢失早期上下文；关键注意事项也会被遗忘	每项重要任务完成后都提取，而不只是等到会话结束
只将洞见存储在任务元数据中	后续会话或 Agent 不会读取任务元数据	始终使用带标签的格式写入 .claude/context/memory/learnings.md

记忆协议

开始之前： 读取 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设会被打断：如果没有记录在记忆中，就等于没有发生。