capture-learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capture Learning

学习内容捕获

Analyze recent conversation context and capture learnings—either to project knowledge files or to skills/commands/subagents for cross-project reuse.

分析近期对话上下文，将学到的内容捕获到项目知识文件或用于跨项目复用的技能/命令/子代理中。

Core Workflow

核心工作流程

Step 1: Analyze Recent Context

步骤1：分析近期上下文

Review the current conversation to identify:

Problem encountered - What went wrong or was confusing?
Root cause - Why did it happen?
Solution - How was it resolved?
Prevention - How to avoid this in the future?

Extract concrete, actionable insights—not vague summaries.

Good learning:

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

Bad learning:

Had some issues with npm install, fixed it eventually.

回顾当前对话，识别以下内容：

遇到的问题 - 出现了什么错误或困惑？
根本原因 - 为什么会发生？
解决方案 - 如何解决的？
预防措施 - 未来如何避免？

提取具体、可操作的见解，而非模糊的总结。

优质的学习内容：

在Node 20+环境下运行`npm install`时，由于React 18的 peer 依赖冲突，需要使用`--legacy-peer-deps`参数。

劣质的学习内容：

npm install遇到了一些问题，最终解决了。

Step 2: Determine Learning Scope

步骤2：确定学习内容的范围

Before deciding where to capture, ask: Is this learning project-specific or general?

Scope	Characteristics	Capture Target
Project-specific	Involves this codebase's architecture, conventions, dependencies, or local setup	Project knowledge files ( `.claude/CLAUDE.md` , `.claude/docs/` )
General	Applies across all projects—language patterns, framework best practices, tool usage, API quirks	Skills, commands, or subagents

Decision questions:

Would this help in other projects using the same language/framework?
Is this a general technique vs. this repo's specific implementation?
Does an existing skill already cover this domain?

Examples:

Learning	Scope	Target
"This repo uses `ApiError` class for error handling"	Project-specific	`.claude/CLAUDE.md`
"SwiftUI `matchedGeometryEffect` should only apply to background shapes, not content"	General	`swiftui-excellence` skill
"Run `npm install --legacy-peer-deps` for this project"	Project-specific	`.claude/CLAUDE.md`
"React Server Components can't use `useState` "	General	`react-component-dev` skill or similar
"The CI pipeline requires `NODE_ENV=test` "	Project-specific	`.claude/docs/setup.md`
"Playwright's `page.waitForSelector` times out silently without proper error handling"	General	`playwright-qa-tester` agent or new skill

If general: Navigate to the appropriate skill/command/subagent file and update it following its existing structure. Then confirm with user before saving.

If project-specific: Continue to Step 3.

在决定捕获位置之前，先问自己：这个知识点是项目特定的还是通用的？

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

决策问题：

这对使用相同语言/框架的其他项目有帮助吗？
这是通用技术还是此仓库的特定实现？
是否已有技能覆盖此领域？

示例：

学习内容	范围	目标
"此仓库使用 `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` 代理或新技能

如果是通用内容： 导航到相应的技能/命令/子代理文件，按照其现有结构进行更新。然后在保存前与用户确认。

如果是项目特定内容： 继续步骤3。

Step 3: Scan for Knowledge Files (Project-Specific Learnings)

步骤3：扫描知识文件（项目特定学习内容）

Detect existing knowledge files in the project's

.claude/

directory:

bash

undefined

检测项目

.claude/

目录中的现有知识文件：

bash

undefined

Primary targets (most common)

主要目标（最常见）

.claude/CLAUDE.md # Main project instructions ./CLAUDE.md # Root-level alternative

.claude/CLAUDE.md # 主要项目说明 ./CLAUDE.md # 根目录替代方案

Secondary targets

次要目标

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

.claude/docs/.md # 参考文档 .claude/docs/**/.md # 嵌套文档

Tertiary (check but don't modify without explicit request)

三级目标（仅检查，无明确请求不修改）

.claude/plans/*.md # Planning docs (usually ephemeral)


**Priority order for updates:**
1. `CLAUDE.md` (project root or `.claude/`) - General learnings, setup issues
2. `.claude/docs/troubleshooting.md` - If exists, for debugging insights
3. `.claude/docs/setup.md` - If exists, for environment/build issues
4. Create new file only if user requests it

.claude/plans/*.md # 规划文档（通常为临时文件）


**更新优先级：**
1. `CLAUDE.md`（项目根目录或`.claude/`下）- 通用学习内容、设置问题
2. `.claude/docs/troubleshooting.md`（如果存在）- 用于调试见解
3. `.claude/docs/setup.md`（如果存在）- 用于环境/构建问题
4. 仅在用户要求时创建新文件

Step 4: Categorize the Learning

步骤4：对学习内容进行分类

Determine which section the learning belongs in:

Learning Type	Target Section	Example
Build/dependency issues	`## Build & Setup` or `## Troubleshooting`	npm flags, version requirements
Environment setup	`## Environment` or `## Prerequisites`	env vars, tool versions
Code patterns	`## Patterns` or `## Conventions`	naming, architecture decisions
Known issues	`## Known Issues` or `## Gotchas`	quirks, workarounds
Debugging insights	`## Debugging`	how to diagnose specific problems

If the target section doesn't exist, propose creating it in a logical location.

确定学习内容所属的章节：

学习内容类型	目标章节	示例
构建/依赖问题	`## 构建与设置` 或 `## 故障排除`	npm参数、版本要求
环境设置	`## 环境` 或 `## 先决条件`	环境变量、工具版本
代码模式	`## 模式` 或 `## 约定`	命名规范、架构决策
已知问题	`## 已知问题` 或 `## 注意事项`	特殊情况、解决方法
调试见解	`## 调试`	如何诊断特定问题

如果目标章节不存在，建议在逻辑位置创建该章节。

Step 5: Draft the Update

步骤5：起草更新内容

Format the learning for documentation:

Structure for issue-based learnings:

markdown

undefined

为文档格式化学习内容：

基于问题的学习内容结构：

markdown

undefined

[Short descriptive title]

[简短描述性标题]

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


**Structure for pattern/convention learnings:**
```markdown

问题： [出现了什么问题] 原因： [为什么会发生] 解决方案： [如何修复/预防]


**基于模式/约定的学习内容结构：**
```markdown

[Pattern name]

[模式名称]

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

code

[Example if applicable]


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

Keep entries:

Scannable - Use headers, bullets, code blocks
Actionable - Provide concrete steps or commands
Contextual - Explain why, not just what

[简要描述何时/为何使用此模式]

code

[如有适用的示例]


**快速提示结构：**
```markdown
- [简洁的可操作提示]

保持条目：

易于扫描 - 使用标题、项目符号、代码块
可操作 - 提供具体步骤或命令
上下文明确 - 解释原因，而非仅说明内容

Step 6: Present Changes for Confirmation

步骤6：展示变更以确认

Before modifying any file, show the user:

Target file - Which file will be updated
Location - Which section (existing or new)
Proposed content - Exact text to be added
Diff preview - Show context around insertion point

Example confirmation prompt:

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

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

目标文件 - 将更新哪个文件
位置 - 哪个章节（现有或新增）
提议内容 - 要添加的确切文本
差异预览 - 展示插入点周围的上下文

示例确认提示：

我会将此内容添加到`.claude/CLAUDE.md`的“## 故障排除”章节下：

Node 20 Peer Dependency Fix

Node 20 Peer依赖修复

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?


Wait for explicit user approval before writing.

问题：

npm install

因peer依赖冲突失败 原因： React 18的严格peer依赖与部分包不兼容 解决方案： 运行

npm install --legacy-peer-deps

是否应用此更新？


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

Step 7: Apply the Update

步骤7：应用更新

After confirmation:

Read the target file
Find the appropriate insertion point
Add the new content with proper formatting
Write the updated file
Confirm the update was applied

If creating a new section, place it logically:

Setup/build sections near the top
Troubleshooting sections near the bottom
Patterns/conventions in the middle

确认后：

读取目标文件
找到合适的插入点
添加格式正确的新内容
写入更新后的文件
确认更新已应用

如果创建新章节，需放置在逻辑位置：

设置/构建章节靠近顶部
故障排除章节靠近底部
模式/约定章节在中间

File Detection Details

文件检测细节

Scanning Strategy

扫描策略

bash

undefined

bash

undefined

Check for .claude directory

检查.claude目录

ls -la .claude/ 2>/dev/null

Find all markdown files in .claude

查找.claude中的所有markdown文件

find .claude -name "*.md" -type f 2>/dev/null

Check root for CLAUDE.md

检查根目录下的CLAUDE.md

ls CLAUDE.md 2>/dev/null

undefined

ls CLAUDE.md 2>/dev/null

undefined

File Purpose Recognition

文件用途识别

Infer file purpose from:

Filename -
```
troubleshooting.md
```
,
```
setup.md
```
,
```
patterns.md
```
Location -
```
.claude/docs/
```
for references,
```
.claude/plans/
```
for planning
Content - Existing section headers indicate file's scope
CLAUDE.md special handling - Always a valid target for general learnings

从以下方面推断文件用途：

文件名 -
```
troubleshooting.md
```
、
```
setup.md
```
、
```
patterns.md
```
位置 -
```
.claude/docs/
```
用于参考文档，
```
.claude/plans/
```
用于规划文档
内容 - 现有章节标题表明文件的范围
CLAUDE.md特殊处理 - 始终是通用学习内容的有效目标

When No Suitable File Exists

当没有合适的文件存在时

.claude/CLAUDE.md

doesn't exist:

Check for
```
./CLAUDE.md
```
in project root
If neither exists, ask user:
- Create
```
.claude/CLAUDE.md
```
  ?
- Create a specific doc file (e.g.,
```
.claude/docs/troubleshooting.md
```
  )?
- Skip capturing this time?

如果

.claude/CLAUDE.md

不存在：

检查项目根目录下的
```
./CLAUDE.md
```
如果两者都不存在，询问用户：
- 是否创建
```
.claude/CLAUDE.md
```
  ？
- 是否创建特定文档文件（例如
```
.claude/docs/troubleshooting.md
```
  ）？
- 这次跳过捕获？

Learning Extraction Patterns

学习内容提取模式

Build/Setup Issues

构建/设置问题

Look for conversation patterns:

Error messages followed by resolution
"Fixed by..." or "The solution was..."
Version-specific workarounds
Missing dependencies or configuration

Extract: The error, root cause, and fix command/steps.

寻找对话模式：

错误消息后跟解决方案
“通过...修复”或“解决方案是...”
特定版本的解决方法
缺失的依赖项或配置

提取内容：错误信息、根本原因和修复命令/步骤。

Code Patterns

代码模式

Look for:

"This codebase uses..." discoveries
Architecture decisions explained
Naming conventions identified
Framework-specific patterns

Extract: Pattern description and rationale.

寻找：

“此代码库使用...”的发现
架构决策的解释
识别出的命名约定
框架特定模式

提取内容：模式描述和原理。

Debugging Insights

调试见解

Look for:

Multi-step debugging processes
Non-obvious root causes
Diagnostic commands or techniques
"The issue was actually..."

Extract: Symptoms, investigation steps, root cause.

寻找：

多步骤调试过程
非显而易见的根本原因
诊断命令或技术
“问题实际上是...”

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

Examples

示例

Example 1: Build Issue

示例1：构建问题

Context: Session involved fixing a failing build due to TypeScript version mismatch.

Captured learning:

markdown

undefined

上下文： 会话涉及修复因TypeScript版本不匹配导致的构建失败。

捕获的学习内容：

markdown

undefined

TypeScript Version Requirement

TypeScript版本要求

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

undefined

问题： 构建失败，提示“Cannot find module 'typescript'” 原因： 项目需要TypeScript 5.3+，但系统安装的是5.0版本 解决方案：

bash

npm install typescript@^5.3.0 --save-dev

undefined

Example 2: Environment Setup

示例2：环境设置

Context: Session discovered required environment variables.

Captured learning:

markdown

undefined

上下文： 会话发现了所需的环境变量。

捕获的学习内容：

markdown

undefined

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

undefined

以下变量必须在

.env.local

中设置：

```
DATABASE_URL
```
- PostgreSQL连接字符串
```
NEXTAUTH_SECRET
```
- 使用
```
openssl rand -base64 32
```
生成
```
NEXTAUTH_URL
```
- 开发环境设置为
```
http://localhost:3000
```

undefined

Example 3: Code Pattern

示例3：代码模式

Context: Session uncovered project's error handling convention.

Captured learning:

markdown

undefined

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

捕获的学习内容：

markdown

undefined

Error Handling Pattern

错误处理模式

All API routes use the

ApiError

class for consistent error responses:

typescript

throw new ApiError(404, "Resource not found");

The error handler middleware converts these to JSON responses.

undefined

所有API路由使用

ApiError

类实现一致的错误响应：

typescript

throw new ApiError(404, "Resource not found");

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

undefined

Edge Cases

边缘情况

Multiple Learnings

多个学习内容

If the session contains multiple distinct learnings:

List them for the user
Ask which to capture (or all)
Process each separately with confirmation

如果会话包含多个不同的学习内容：

向用户列出所有内容
询问要捕获哪些（或全部）
分别处理每个内容并确认

Conflicting Information

信息冲突

If new learning contradicts existing documentation:

Show both versions
Ask user which is correct
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.

切勿捕获：

API密钥、令牌或机密
密码或凭据
个人信息
不应记录的内部URL

如果学习内容涉及机密，仅记录模式而非实际值。

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)

触发短语： "捕获这个"、"记住这个"、"更新文档"、"记录这个"、"添加到CLAUDE.md"、"保存这个知识"

第一个问题： 这是项目特定的还是通用的？

项目特定目标：

.claude/CLAUDE.md

（主要）、

.claude/docs/*.md

（次要）

通用目标： 技能（

~/.claude/skills/

）、命令（

~/.claude/commands/

）、子代理（插件代理）

始终确认： 在写入前展示确切变更

格式： 问题→原因→解决方案（针对问题），描述→示例（针对模式）

Additional Resources

其他资源

Reference Files

参考文件

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.

references/section-templates.md - 常见文档章节（故障排除、构建与设置、环境、模式、已知问题、调试）的完整模板。创建新章节或构建复杂学习内容时参考。