capture-learning

捕获经验

分析近期对话上下文并捕获经验——将其记录到项目知识文件，或记录到可跨项目复用的技能／命令／子代理中。

核心工作流

步骤 1：分析近期上下文

回顾当前对话，找出：

1. 遇到的问题 - 出了什么问题，或有什么令人困惑的地方？
2. 根本原因 - 为什么会发生？
3. 解决方案 - 如何解决的？
4. 预防措施 - 今后如何避免？

提取具体、可执行的经验，而不是含糊的总结。

好的经验：

When running `npm install` on Node 20+, the `--legacy-peer-deps` flag
is required due to React 18 peer dependency conflicts.

不好的经验：

Had some issues with npm install, fixed it eventually.

步骤 2：确定经验范围

在决定记录到哪里之前，先问：这条经验是特定于项目，还是通用的？

范围	特征	记录位置
特定于项目	涉及此代码库的架构、约定、依赖项或本地设置	项目知识文件（.claude/CLAUDE.md、.claude/docs/）
通用	适用于所有项目——语言模式、框架最佳实践、工具用法、API 特性	技能、命令或子代理

判断问题：

1. 使用相同语言／框架的其他项目能从中受益吗？
2. 这是通用技巧，还是此代码库的特定实现？
3. 现有技能是否已涵盖此领域？

示例：

经验	范围	目标位置
“此代码库使用 ApiError 类处理错误”	特定于项目	.claude/CLAUDE.md
“SwiftUI 的 matchedGeometryEffect 只应应用于背景形状，而不是内容”	通用	swiftui-excellence 技能
“此项目需要运行 npm install --legacy-peer-deps”	特定于项目	.claude/CLAUDE.md
“React Server Components 不能使用 useState”	通用	react-component-dev 技能或类似技能
“CI 流水线要求 NODE_ENV=test”	特定于项目	.claude/docs/setup.md
“Playwright 的 page.waitForSelector 在缺少恰当错误处理时会静默超时”	通用	playwright-qa-tester Agent 或新技能

**如果是通用经验：**前往适当的技能／命令／子代理文件，并按照其现有结构进行更新。然后在保存前向用户确认。

**如果是特定于项目的经验：**继续执行步骤 3。

步骤 3：查找知识文件（特定于项目的经验）

检查项目的 .claude/ 目录中是否存在知识文件：

# Primary targets (most common)
.claude/CLAUDE.md          # Main project instructions
./CLAUDE.md                # Root-level alternative

# Secondary targets
.claude/docs/*.md          # Reference documentation
.claude/docs/**/*.md       # Nested docs

# Tertiary (check but don't modify without explicit request)
.claude/plans/*.md         # Planning docs (usually ephemeral)

更新优先级：

1. CLAUDE.md（项目根目录或 .claude/）- 通用经验、设置问题
2. .claude/docs/troubleshooting.md - 若存在，用于记录调试经验
3. .claude/docs/setup.md - 若存在，用于记录环境／构建问题
4. 仅在用户要求时创建新文件

步骤 4：为经验分类

确定经验应归入哪个部分：

经验类型	目标部分	示例
构建／依赖问题	## Build & Setup 或 ## Troubleshooting	npm 标志、版本要求
环境设置	## Environment 或 ## Prerequisites	环境变量、工具版本
代码模式	## Patterns 或 ## Conventions	命名、架构决策
已知问题	## Known Issues 或 ## Gotchas	特性、变通方法
调试经验	## Debugging	如何诊断特定问题

如果目标部分不存在，则提议在合适的位置创建该部分。

步骤 5：起草更新内容

按照以下格式编写文档中的经验：

基于问题的经验结构：

### [Short descriptive title]

**Problem:** [What went wrong]
**Cause:** [Why it happened]
**Solution:** [How to fix/prevent]

模式／约定类经验结构：

### [Pattern name]

[Brief description of when/why to use this pattern]

```code
[Example if applicable]

**Structure for quick tips:**
```markdown
- [Concise actionable tip]

条目应：

• 便于浏览 - 使用标题、项目符号、代码块
• 可执行 - 提供具体步骤或命令
• 结合上下文 - 解释为什么，而不只是是什么

步骤 6：提交更改以供确认

修改任何文件之前，向用户展示：

1. 目标文件 - 将要更新的文件
2. 位置 - 所在章节（现有章节或新章节）
3. 拟添加内容 - 将要添加的确切文本
4. 差异预览 - 展示插入位置附近的上下文

确认提示示例：

I'll add this to `.claude/CLAUDE.md` under "## Troubleshooting":

### Node 20 Peer Dependency Fix

**Problem:** `npm install` fails with peer dependency conflicts
**Cause:** React 18 has strict peer deps incompatible with some packages
**Solution:** Run `npm install --legacy-peer-deps`

Should I apply this update?

等待用户明确批准后再写入。

步骤 7：应用更新

获得确认后：

1. 读取目标文件
2. 找到合适的插入位置
3. 按正确格式添加新内容
4. 写入更新后的文件
5. 确认已应用更新

如果要创建新章节，请按逻辑顺序放置：

• 设置／构建章节放在靠前位置
• 故障排除章节放在靠后位置
• 模式／约定放在中间

文件检测详情

扫描策略

# Check for .claude directory
ls -la .claude/ 2>/dev/null

# Find all markdown files in .claude
find .claude -name "*.md" -type f 2>/dev/null

# Check root for CLAUDE.md
ls CLAUDE.md 2>/dev/null

文件用途识别

根据以下信息推断文件用途：

1. 文件名 - troubleshooting.md、setup.md、patterns.md
2. 位置 - .claude/docs/ 用于参考文档，.claude/plans/ 用于规划
3. 内容 - 现有章节标题表明文件的涵盖范围
4. CLAUDE.md 特殊处理 - 始终是记录一般经验的有效目标

不存在合适的文件时

如果 .claude/CLAUDE.md 不存在：

1. 检查项目根目录中的 ./CLAUDE.md
2. 如果两者都不存在，询问用户：
   • 是否创建 .claude/CLAUDE.md？
   • 是否创建特定文档文件（例如 .claude/docs/troubleshooting.md）？
   • 是否跳过本次记录？

经验提取模式

构建／设置问题

查找对话中的以下模式：

• 错误消息及其解决方法
• “通过……修复”或“解决方案是……”
• 特定版本的变通方法
• 缺少依赖项或配置

提取：错误、根本原因以及修复命令／步骤。

代码模式

查找：

• “此代码库使用……”的发现
• 对架构决策的说明
• 已确定的命名约定
• 特定框架的模式

提取：模式说明及其理由。

调试见解

查找：

• 多步骤调试过程
• 不明显的根本原因
• 诊断命令或技巧
• “问题实际上是……”

提取：症状、调查步骤、根本原因。

示例

示例 1：构建问题

上下文： 会话中修复了由 TypeScript 版本不匹配导致的构建失败。

记录的经验：

### TypeScript Version Requirement

**Problem:** Build fails with "Cannot find module 'typescript'"
**Cause:** Project requires TypeScript 5.3+ but system has 5.0
**Solution:**
```bash
npm install typescript@^5.3.0 --save-dev

### Example 2: Environment Setup

**Context:** Session discovered required environment variables.

**Captured learning:**
```markdown
### Required Environment Variables

The following must be set in `.env.local`:
- `DATABASE_URL` - PostgreSQL connection string
- `NEXTAUTH_SECRET` - Generate with `openssl rand -base64 32`
- `NEXTAUTH_URL` - Set to `http://localhost:3000` for development

示例 3：代码模式

上下文： 会话中发现了项目的错误处理约定。

记录的经验：

### Error Handling Pattern

All API routes use the `ApiError` class for consistent error responses:
```typescript
throw new ApiError(404, "Resource not found");

错误处理器中间件会将这些内容转换为 JSON 响应。

## Edge Cases

### Multiple Learnings

If the session contains multiple distinct learnings:
1. List them for the user
2. Ask which to capture (or all)
3. Process each separately with confirmation

### Conflicting Information

If new learning contradicts existing documentation:
1. Show both versions
2. Ask user which is correct
3. Update or replace as directed

### Sensitive Information

Never capture:
- API keys, tokens, or secrets
- Passwords or credentials
- Personal information
- Internal URLs that shouldn't be documented

If a learning involves secrets, document the *pattern* without the actual values.

## Quick Reference

**Trigger phrases:** "capture this", "remember this", "update docs", "document this", "add to CLAUDE.md", "save this knowledge"

**First question:** Is this project-specific or general?

**Project-specific targets:** `.claude/CLAUDE.md` (primary), `.claude/docs/*.md` (secondary)

**General targets:** Skills (`~/.claude/skills/`), commands (`~/.claude/commands/`), subagents (plugin agents)

**Always confirm:** Show exact changes before writing

**Format:** Problem → Cause → Solution (for issues), Description → Example (for patterns)

## Additional Resources

### Reference Files

- **[references/section-templates.md](references/section-templates.md)** - Complete templates for common documentation sections (Troubleshooting, Build & Setup, Environment, Patterns, Known Issues, Debugging). Consult when creating new sections or structuring complex learnings.