learning

持续学习技能

本技能用于从开发会话中提取可复用的模式和知识，实现持续学习和改进。

快速参考

• 核心职责: 从开发会话中提取可复用模式（错误解决、调试技巧、变通方案、项目知识）
• 学习模式: 错误解决模式、调试技巧、变通方案、项目特定知识
• 本能系统: 观察 → 记录 → 本能 → 演化（置信度 0.3~0.9）
• 自动化: 会话评估 Hook（evaluate-session.js）+ 观察 Hook（observe-patterns.js）
• 子文件引用:
• [extraction-guide.md](extraction-guide.md) — 会话学习方法论（知识分类、置信度系统）

<!-- 详细内容 -->

目录

• [子文件](#子文件)
• [触发条件](#触发条件)
• [学习模式类型](#学习模式类型)
• [评估清单](#评估清单)
• [知识库结构](#知识库结构)
• [知识文档模板](#知识文档模板)
• [自动化集成](#自动化集成)
• [本能系统（进阶）](#本能系统进阶)
• [最佳实践](#最佳实践)

子文件

• [extraction-guide.md](extraction-guide.md) - 会话学习方法论（知识分类、置信度系统）

触发条件

• 会话结束时评估
• 发现新的调试技巧
• 解决了复杂问题
• 创建了可复用的解决方案
• 学到了项目特定知识

学习模式类型

1. 错误解决模式

当解决了一个错误，记录：

• 错误信息
• 根本原因
• 解决方案
• 预防措施

## 错误: Cannot read property 'xxx' of undefined

### 场景

访问嵌套对象属性时

### 根本原因

异步数据未加载完成就访问

### 解决方案

// 使用可选链 const value = obj?.nested?.property;

// 或提供默认值 const value = obj?.nested?.property ?? defaultValue;

预防

• 始终使用可选链访问可能为空的属性
• 在组件中添加加载状态检查

### 2. 调试技巧

技巧: 调试 Next.js API 路由

场景

API 路由返回意外结果

技巧

1. 在 route.ts 开头添加日志

export async function GET(request: NextRequest) {
  console.log('[API] GET /api/xxx', {
    url: request.url,
    headers: Object.fromEntries(request.headers)
  })
  // ...
}

1. 使用 Postman/curl 直接测试
2. 检查中间件是否拦截

### 3. 变通方案

变通: Prisma 不支持的复杂查询

场景

需要执行 Prisma 不原生支持的 SQL

变通方案

// 使用 $queryRaw 执行原生 SQL
const result = await prisma.$queryRaw`
  SELECT * FROM users
  WHERE LOWER(name) LIKE ${`%${search.toLowerCase()}%`}
`

// 或使用 $executeRaw 执行命令
await prisma.$executeRaw`
  UPDATE users SET updated_at = NOW()
  WHERE id = ${userId}
`

注意

• 需要手动处理 SQL 注入防护
• 返回类型需要手动指定

### 4. 项目特定知识

项目: 用户认证流程

流程

1. 用户提交凭证 → POST /api/auth/login
2. 验证凭证 → 检查数据库
3. 生成 JWT → 设置 httpOnly cookie
4. 返回用户信息

关键文件

• src/app/api/auth/login/route.ts - 登录接口
• src/lib/auth.ts - 认证工具函数
• src/middleware.ts - 路由保护

注意事项

• Token 有效期 7 天
• 刷新 Token 在 /api/auth/refresh
• 受保护路由在 middleware.ts 配置

## 评估清单

会话结束时，检查以下内容：

### 值得记录的模式

• [ ] 解决了一个复杂的 Bug？
• [ ] 发现了一个调试技巧？
• [ ] 创建了一个可复用的代码片段？
• [ ] 学到了框架/库的新用法？
• [ ] 遇到并解决了性能问题？
• [ ] 找到了一个变通方案？
• [ ] 了解了项目特定的知识？

### 不值得记录的模式

• [ ] 简单的拼写错误
• [ ] 一次性的配置问题
• [ ] 外部 API 临时故障
• [ ] 已知的简单问题

## 知识库结构

.claude/ └── learned/ ├── errors/ │ ├── prisma-connection-issues.md │ └── react-hydration-mismatch.md ├── debugging/ │ ├── next-api-routes.md │ └── database-query-slow.md ├── workarounds/ │ ├── prisma-raw-queries.md │ └── nextauth-custom-session.md ├── patterns/ │ ├── error-handling.md │ └── api-response-format.md └── project/ ├── auth-flow.md └── data-models.md

## 知识文档模板

title: [标题] category: [errors|debugging|workarounds|patterns|project] tags: [tag1, tag2] created: YYYY-MM-DD updated: YYYY-MM-DD

[标题]

场景

[描述遇到这个问题/使用这个模式的场景]

问题/需求

[具体的问题描述或需求说明]

解决方案

[详细的解决方案，包括代码示例]

相关文件

• path/to/file.ts - [说明]

参考

• [链接1](url)
• [链接2](url)

注意事项

[使用时需要注意的点]

## 自动化集成

### 会话评估 Hook

会话评估已通过 Node.js Hook 自动化，无需手动触发：

- **脚本**: `scripts/node/hooks/evaluate-session.js`（运行 `--help` 查看详情）
- **触发时机**: Stop 事件（会话结束时）
- **功能**: 自动评估会话长度，提示提取可复用模式

### 配置文件

{ "min_session_length": 10, "extraction_threshold": "medium", "auto_approve": false, "learned_skills_path": "~/.claude/learned/", "patterns_to_detect": [ "error_resolution", "debugging_techniques", "workarounds", "project_specific" ], "ignore_patterns": ["simple_typos", "one_time_fixes", "external_api_issues"] }

## 本能系统（进阶）

本能是介于"观察"和"正式技能"之间的中间状态，用于捕捉重复出现的模式。

### 本能的生命周期

观察 ──→ 记录 ──→ 本能 ──→ 演化 │ │ │ │ │ │ │ └─→ 技能/命令/智能体 │ │ └─→ 置信度评估 │ └─→ observations.jsonl └─→ Hook 自动捕获

### 置信度评分

| 置信度 | 含义     | 动作                |
| ------ | -------- | ------------------- |
| 0.3    | 首次观察 | 记录但不采取行动    |
| 0.5    | 重复出现 | 形成初步本能        |
| 0.7    | 多次验证 | 考虑演化为技能      |
| 0.9    | 高度可靠 | 正式演化为技能/命令 |

### 本能记录格式

本能: [名称]

触发模式

[什么情况下触发]

推荐行为

[应该如何响应]

置信度: 0.X

[基于多少次观察]

观察记录

• 2025-01-20: [场景1]
• 2025-01-22: [场景2]

演化候选

• [ ] 升级为技能
• [ ] 升级为命令
• [ ] 写入 CLAUDE.md

### 自动观察 Hook

通过 PostToolUse hook 自动捕获工具调用模式，无需手动触发。

- **脚本**: `scripts/node/hooks/observe-patterns.js`（运行 `--help` 查看详情）
- **输出**: `memory-bank/observations.jsonl`（JSONL 格式，自动轮转）
- **触发**: Write、Edit、Bash 操作后自动运行
- **检测模式**: error_fix、repeated_search、multi_file_edit、test_after_edit
- **与 /learn 配合**: `/learn` 命令在 Step 0 自动读取观察数据作为分析输入

---

## 最佳实践

1. **及时记录** - 解决问题后立即记录，不要等
2. **结构化** - 使用统一的模板格式
3. **具体示例** - 包含代码示例和文件路径
4. **定期回顾** - 定期整理和更新知识库
5. **团队共享** - 有价值的知识分享给团队
6. **版本控制** - 将知识库纳入版本控制
7. **标签分类** - 使用标签便于搜索
8. **保持简洁** - 只记录有价值的内容
9. **更新过时** - 及时更新过时的信息
10. **关联项目** - 记录项目特定的上下文
11. **本能演化** - 重复模式升级为正式技能

---

> **记住**: 每次调试都是学习机会。记录下来，下次就能更快解决类似问题。本能系统让学习更系统化，从观察到技能的演化让知识沉淀更有效。