lessons-learned

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lessons Learned

经验总结

Identify what was learned in this session and persist it so future sessions benefit.

识别本次会话中学到的内容并留存，以便后续会话从中受益。

When to Run

运行时机

User explicitly asks (
```
/lessons-learned
```
, "save what we learned")
End of a complex multi-session task (suggest proactively)
After a significant debugging session that uncovered non-obvious behavior
After a council-of-bots review that surfaced actionable fixes

用户明确提出请求（如输入"/lessons-learned"、"save what we learned"）
复杂多会话任务结束时（主动建议使用）
完成重大调试会话并发现非直观问题后
机器人评审会（council-of-bots review）提出可执行修复方案后

Selectivity Principle

筛选原则

Default to NOT saving. Memory files accumulate over time and consume context in every future session. Each entry must earn its place. Ask: "Would a fresh Claude session clearly benefit from knowing this?" If the answer is "maybe" — skip it.

Most sessions produce 0–2 lessons worth persisting. A session that yields 5+ is rare and should prompt extra scrutiny. Prefer fewer high-signal entries over comprehensive logs of everything that happened.

默认不保存。记忆文件会随时间积累，占用后续所有会话的上下文空间。每条记录都必须有留存的价值。请自问："一个全新的Claude会话是否能明确从这条记录中受益？"如果答案是"可能"——就跳过它。

大多数会话只会产生0-2条值得留存的经验。一次会话产生5条及以上经验的情况非常罕见，需要额外严格审查。宁可保留少量高价值记录，也不要全面记录所有发生的事情。

Workflow

工作流

1. Mine the session for lessons

1. 挖掘会话中的经验

Review the conversation for insights that are non-obvious, actionable, and verified. Skip anything a competent developer would figure out in context.

回顾对话内容，找出非直观、可执行且已验证的洞察。跳过任何有能力的开发者能在上下文里自行发现的内容。

2. Scope and filter each candidate

2. 界定范围并筛选候选记录

Every candidate lesson has a scope:

Scope	Bar	Destination	Example
Global	Applies across most projects/sessions	`~/.claude/CLAUDE.md` or skill files	"R CMD check: use `--no-tests --no-vignettes` for fast iteration on compilation issues"
Project	Specific to this repo's setup/conventions	project MEMORY.md or topic file	"Air formatter pre-commit hook: re-stage then new commit"

Global lessons have a higher bar: they must be useful regardless of which project you're working on. Package-specific migration steps, repo-specific remote configs, or one-time setup details are NOT global — they're project-specific at best, and often not worth saving at all.

Drop aggressively. Filter out:

One-time configuration steps unlikely to recur (e.g., "added flag X to Makevars")
Project-specific facts with no transferable insight (e.g., "origin = user/repo")
Details that are easily re-discoverable from docs or
```
--help
```
Anything that duplicates existing memory or skill content

每条候选经验都有对应的适用范围：

范围	标准	存储位置	示例
全局	适用于大多数项目/会话	`~/.claude/CLAUDE.md` 或技能文件	"R CMD check：使用 `--no-tests --no-vignettes` 快速迭代编译问题"
项目专属	仅适用于当前仓库的设置/规范	项目的MEMORY.md或主题文件	"Air格式化工具的pre-commit钩子：重新暂存后再提交新的commit"

全局经验的标准更高：必须在任何项目中都有用。特定包的迁移步骤、仓库专属的远程配置，或是一次性的设置细节都不属于全局经验——最多属于项目专属经验，而且通常不值得保存。

果断舍弃以下内容：

不太可能重复发生的一次性配置步骤（如"给Makevars添加了参数X"）
无迁移价值的项目专属事实（如"origin = user/repo"）
可从文档或
```
--help
```
轻松找回的细节
与现有记忆或技能内容重复的内容

3. Check for duplicates

3. 检查重复内容

Before writing anything:

Read the current MEMORY.md and
```
~/.claude/CLAUDE.md
```
Read any relevant topic files linked from MEMORY.md
Read the SKILL.md of any skill you plan to update
Skip lessons already captured (even if worded differently)

在写入任何内容前：

阅读当前的MEMORY.md和
```
~/.claude/CLAUDE.md
```
阅读MEMORY.md中链接的所有相关主题文件
阅读计划更新的技能对应的SKILL.md
跳过已存在的经验（即使表述不同）

4. Present lessons to user for approval

4. 呈现候选经验供用户确认

Show candidates grouped by scope, with clear destinations:

Global (applies across projects):
  1. [lesson] → ~/.claude/CLAUDE.md

Project-specific:
  2. [lesson] → MEMORY.md

Nothing else worth persisting from this session.

Ask which to persist. Default: all shown (but the list should already be selective). If no lessons pass the bar, say so — an empty result is fine.

按适用范围分组展示候选经验，并明确存储位置：

全局（适用于所有项目）:
  1. [经验内容] → ~/.claude/CLAUDE.md

项目专属:
  2. [经验内容] → MEMORY.md

本次会话没有其他值得留存的内容。

询问用户要保存哪些内容。默认保存所有展示的内容（但展示的列表应该已经经过严格筛选）。如果没有经验符合标准，直接说明即可——空结果是正常的。

5. Persist

5. 执行保存

Global (

~/.claude/CLAUDE.md

~/.claude/skills/

Read the target file first.
Add concisely in the most natural location.
Skills are loaded into context on every trigger — keep additions minimal.
For skills with reference files, prefer adding there over bloating SKILL.md.
Always use
/skill-creator
to edit skill files. Never edit SKILL.md directly without invoking the skill-creator skill first.

Project memory (

~/.claude/projects/<project>/memory/

MEMORY.md: Keep concise (<200 lines). One-liners. Link to topic files for detail.
Topic files (e.g.,
```
sim-patterns.md
```
): Longer explanations with code examples.
If MEMORY.md is approaching 200 lines, consolidate or move detail to topic files.

全局内容（

~/.claude/CLAUDE.md

、

~/.claude/skills/

）：

先读取目标文件。
以最自然的方式简洁添加内容。
技能会在每次触发时加载到上下文中——请尽量精简新增内容。
对于带有参考文件的技能，优先添加到参考文件中，避免膨胀SKILL.md。
必须使用
/skill-creator
编辑技能文件。在未先调用skill-creator技能的情况下，绝不要直接编辑SKILL.md。

项目记忆（

~/.claude/projects/<project>/memory/

）：

MEMORY.md：保持简洁（少于200行）。尽量用单行表述。详情链接到主题文件。
主题文件（如
```
sim-patterns.md
```
）：可包含较长的解释和代码示例。
如果MEMORY.md接近200行，整理内容或将详情迁移到主题文件中。

6. Confirm

6. 确认保存结果

Summarize what was written and where:

Persisted 2 lessons:
- ~/.claude/CLAUDE.md: 1 item (R CMD check fast iteration)
- MEMORY.md: 1 item (Air formatter hook behavior)

总结已保存的内容及其位置：

已留存2条经验:
- ~/.claude/CLAUDE.md: 1条内容（R CMD check快速迭代方法）
- MEMORY.md: 1条内容（Air格式化工具钩子特性）

Quality Bar

质量标准

See

references/quality-guide.md

for examples of good vs bad lessons.

Key principles:

Actionable over observational: "Use
```
on.exit()
```
to save/restore RNG" not "RNG can be tricky"
Specific over vague: Include the code pattern, the file path, the exact error message
Non-obvious over common knowledge: Skip things any competent developer would know
Verified over speculative: Only persist what was confirmed in this session
Concise over thorough: A 2-line lesson that's always read beats a 20-line essay that's skipped

请查看

references/quality-guide.md

中的优劣经验示例。

核心原则：

优先可执行，而非观察性描述：比如写"使用
```
on.exit()
```
保存/恢复RNG"，而不是"RNG可能很棘手"
优先具体，而非模糊表述：包含代码模式、文件路径、确切的错误信息
优先非直观内容，而非常识：跳过任何有能力的开发者都知道的内容
优先已验证内容，而非推测性内容：只保存本次会话中已确认的内容
优先简洁，而非详尽：一条会被认真阅读的2行经验，胜过一条会被跳过的20行长篇大论