self-improvement

自我改进

此技能有两种模式：

1. 被动记录（始终启用，无需调用技能）——每次出现错误、纠正、建议或经验教训时，都会立即记录到 ~/.learnings/。这通过 CLAUDE.md 融入 Claude 的行为中，无需触发此技能。

2. 主动审查与提升（通过 /self-improvement 触发）——审查累积的经验教训，将有价值的内容提升到 CLAUDE.md，分析 GitHub PR 和问题，并进行会话结束回顾。提升只会在此处发生，绝不会自动进行。

日志文件

在 ~/.learnings/ 中维护三个结构化的 Markdown 文件（如果目录不存在，则创建它）：

• ~/.learnings/LEARNINGS.md ——纠正、知识盲区、最佳实践、建议
• ~/.learnings/ERRORS.md ——命令失败、异常、意外行为
• ~/.learnings/FEATURE_REQUESTS.md ——用户提出但你无法提供的功能
• ~/.learnings/CHANGELOG.md ——记录每次提升（及撤销）到 CLAUDE.md 的永久追加式记录
• ~/.learnings/ARCHIVE.md ——所有已审查的条目（已提升或已跳过）都会移至此处。除非用户明确要求查看，否则不会载入上下文。

被动记录（始终启用）

每次出现错误、纠正、建议或经验教训时，都要立即记录——没有例外，也不需要判断是否“值得”记录。这样做的目的就是建立完整记录。后续会话可以筛选；当前会话的任务是记录下来。

立即记录——不要征求许可，也不要等待停顿。事件刚发生后，相关上下文最清晰。记录后，简短告知用户记录了什么（一行即可，例如“已将端口冲突记录到 ERRORS.md”）。不必赘述。

哪些情况需要记录

• 用户纠正：“其实应该是……”“不，别……”“那不对，因为……” → LEARNINGS.md
• 知识盲区：你提供了过时信息、遗漏了项目约定，或需要被纠正 → LEARNINGS.md
• 建议：用户建议采用更好的方法、工具或模式 → LEARNINGS.md
• 命令/工具失败：Shell 命令失败、API 调用报错、文件操作未按预期执行 → ERRORS.md
• 功能请求：用户提出了你无法实现的功能 → FEATURE_REQUESTS.md
• 重复出现的模式：同一会话中重复犯同一个错误 → LEARNINGS.md（提高优先级）

哪些情况无需记录

• 不会再次发生的拼写错误或轻微的自我纠正
• 由短暂状况导致的失败（网络瞬时中断、服务器暂时宕机）
• 项目的 CLAUDE.md 中已包含完全相同的细节

条目格式

每个条目 ID 使用 6 位随机十六进制哈希（例如 a3f7c1），以避免不同会话和项目之间发生冲突。在记录时生成哈希——任何方法都可以（随机生成、截断 SHA 等），只要包含 6 位十六进制字符即可。

LEARNINGS.md

## [LRN-a3f7c1] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | promoted
- **Area**: frontend | backend | infra | tests | docs | config | workflow | other
- **What happened**: Brief description of the correction or gap
- **Lesson**: The concrete takeaway
- **Source**: e.g., "User correction in conversation", "PR #42", "Issue #17"
- **Suggested fix**: Specific action or rule change

ERRORS.md

## [ERR-b2e9d4] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | resolved
- **Area**: (same categories as above)
- **Command/action**: What was attempted
- **Error**: The failure message or description
- **Root cause**: Why it failed (once known)
- **Fix**: What resolved it or what to do differently next time
- **Reproduction**: Steps to reproduce (if useful)

FEATURE_REQUESTS.md

## [FEAT-c8d2a5] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | implemented | promoted
- **Area**: (same categories)
- **Request**: What the user asked for
- **Context**: Why they needed it, what they were trying to accomplish
- **Workaround**: What was done instead, if anything

提升（仅通过 /self-improvement）

提升是指将一条经验写入 CLAUDE.md 文件，使其在之后的所有对话中持续生效。提升绝不会自动发生——只有用户明确运行 /self-improvement 并审查要提升的内容时才会进行。

这是有意为之：自动提升会导致 CLAUDE.md 变得臃肿，并加入用户不想要的条目。对于哪些内容成为永久指引，用户应始终参与决定。

当用户运行 /self-improvement

1. 读取 ~/.learnings/ 中所有待处理条目（状态：pending）
2. 按主题分组，汇总值得提升的候选条目
3. 对每个候选条目，说明它可能值得提升的原因及目标位置
4. 等待用户逐项批准、拒绝或修改
5. 仅提升用户明确批准的条目
6. 归档所有已审阅条目——已提升和跳过的条目都会移至 ~/.learnings/ARCHIVE.md，并从其源文件中删除（见下文“归档”）

提升标准（用于提出建议）

建议提升符合以下条件的条目：

1. 适用范围广——不局限于某次对话或某个文件
2. 可能会再次遇到——未来的 Claude 很可能会遇到相同问题
3. 尚未记录——先检查目标 CLAUDE.md

提升到何处

项目 CLAUDE.md（项目根目录中）——用于记录项目特定的约定、模式和易错点。

用户 CLAUDE.md（~/.claude/CLAUDE.md）——用于记录适用于任何项目的跨项目知识。

经验法则：“这对一个完全不同的项目也有用吗？”如果有 → 用户 CLAUDE.md。如果没有 → 项目 CLAUDE.md。

如何提升（用户批准后）

1. 阅读目标 CLAUDE.md，找到合适的章节（如果需要，也可以新建章节）
2. 编写简洁、完整的条目——即使没有原始对话，也应能独立理解
3. 在 ~/.learnings/CHANGELOG.md 中追加一条记录（格式见下文）
4. 归档源条目（见下文“归档”）
5. 告知用户提升了什么内容以及目标位置

归档已审阅条目

在 /self-improvement 期间审阅的每个条目——无论是否提升——都要归档。这样可以让活跃的学习文件保持精简（只包含未审阅条目），同时保留完整历史记录。

1. 移动源文件（LEARNINGS.md、ERRORS.md 或 FEATURE_REQUESTS.md）中的完整条目至 ~/.learnings/ARCHIVE.md
2. 在归档条目中添加 - **Disposition**: promoted to <target> | skipped (<reason>) 字段
3. 从源文件中删除该条目

归档文件仅追加内容，除非用户明确要求（例如，“给我看看归档”“上次跳过了什么”“在归档中搜索 X”），否则绝不会加载到上下文中。这样可以避免占用上下文窗口。

提升变更日志

每次提升都会记录到 ~/.learnings/CHANGELOG.md，作为永久的、仅追加内容的审计跟踪。

## [PROMO-f4a8e2] Short title matching the source entry
- **Timestamp**: ISO-8601
- **Source**: LRN-a3f7c1 (or ERR-, FEAT- reference)
- **Target**: project CLAUDE.md | user CLAUDE.md (~/.claude/CLAUDE.md)
- **Section**: Which section of the target file it was added to
- **What was promoted**: The exact text or a close summary of what was written
- **Why**: One sentence on why this deserved promotion

绝不要编辑或删除变更日志条目——如果发现某次提升有误，请添加新的 [REVERT-<hex>] 条目，说明移除了什么以及原因，然后从目标 CLAUDE.md 中移除该内容。

保持提升后的条目精简。如果有帮助，可用一两个句子概括，并附上具体示例。

不应提升的内容

• 针对临时情况的一次性变通方案
• 仅适用于单个文件或狭窄场景的内容
• 已包含在修复中的调试步骤（代码本身就是文档）
• 目标 CLAUDE.md 中已有的任何内容（请先检查！）

从 GitHub PR 和 Issue 中学习

当用户要求你从 GitHub 历史记录（PR、Issue、讨论）中学习时，使用 gh CLI 分析模式：

# Fetch closed PRs with review comments
gh pr list --state closed --limit 50 --json number,title,reviews,comments

# Look at a specific PR's review feedback
gh pr view <number> --json reviews,comments,body

提取以下内容：

• 审查者反复提出的问题 → 写入 LEARNINGS.md 的经验教训
• 被拒绝的方案（及原因）→ 应避免的模式
• Issue 中常见的错误模式 → 写入 ERRORS.md 的条目
• 经常被请求的功能 → 写入 FEATURE_REQUESTS.md

重点关注多个 PR/Issue 中出现的模式，而非个别事件。务必在条目中注明来源 PR 或 Issue 编号。

原则

记录所有内容，有选择地晋升。 记录每个错误、更正、建议和经验教训——不做筛选，也不判断重要性。日志是一份完整记录。晋升到 CLAUDE.md 才是有选择的步骤，而且只有用户提出要求时才会进行。

具体，不要含糊。 “不要使用已弃用的 API”毫无用处。“不要在此代码库中使用 os.path.join——这里处处使用 pathlib.Path（参见 utils.py）”才有用。

记录原因。 未来的 Claude 不会记得上下文。要把经验教训写得足够完整，即使没有原始对话，也能让人理解。

关联相关条目。 如果某个错误与一条经验教训或功能请求有关，请交叉引用它们。

无需询问即可记录，经许可后再晋升。 记录会自动、顺畅地进行——直接记录，并简要告知用户。晋升则需要用户通过 /self-improvement 明确批准。