Self Improvement (done properly)

核心功能

Self-Improvement 是一套持续学习基础设施，专为AI代理设计，用于捕获、沉淀和复用从错误中获得的 durable lessons。它区别于简单的日志系统，强调可复用性而非记录每件事。

主要用法

技能围绕三种核心记录类型构建：

• Learning：用户纠正、项目约定、知识盲区
• Error：非显而易见的工具/API失败、调试后的问题
• Feature Request：缺失能力、反复出现的摩擦点

使用Python CLI工具（learnings.py）初始化工作区、搜索历史记录、创建条目，最终将验证有效的规则提升为项目记忆文件（CLAUDE.md、AGENTS.md等）或提取为独立技能。

显著优点

1. 结构性抗重复：通过强制搜索（search-first）、稳定Pattern-Key、See Also链接，有效防止条目碎片化
2. 渐进式沉淀：capture → dedupe → promote → extract 的闭环设计，确保知识从临时记录流向持久基础设施
3. 双根模型清晰分离：技能资源（scripts/、references/）与项目工作区（.learnings/、CLAUDE.md）严格隔离，避免污染
4. 评估驱动：预留 evals/ 和 trigger/output eval 框架，支持技能自身的持续改进

局限性与风险

• 工具链依赖：需要Python 3.11+，部分hook依赖bash；纯手动使用虽可行但体验下降
• 推广门槛："promote aggressively" 要求代理具备判断何时规则已"验证有效"的能力，实践中可能过度推广或保守
• 无内置同步：.learnings/ 是本地文件，多设备/多协作者场景下无合并策略
• 静默日志风险：规则7要求"do not interrupt the user"，但某些关键学习可能需要用户确认以避免错误假设

适合人群

• 长期使用Claude Code、OpenClaw等AI编程工具的专业开发者
• 维护复杂代码库、需要跨会话保持上下文的团队
• 希望将个人调试经验转化为可复用技能的"技能作者"

常规风险

| 风险 | 缓解 |

|------|------|

| 条目膨胀、低信噪比 | 严格过滤规则（排除trivial typos、straightforward retries）+ 搜索优先 |

| 推广规则未经充分验证 | 建议设置观察期，高频复发后再推广 |

| 模式键（Pattern-Key）冲突 | 使用带日期前缀的确定性ID |

| 敏感信息泄露 | 学习记录可能包含错误日志、文件路径，需注意`.learnings/`的gitignore配置 |

核心概述

Self-Improvement 是一款纯本地运行的智能学习捕获工具，专为 AI Agent 设计，用于从调试过程、用户纠错、能力缺失和重复工作摩擦中提取可复用的经验。该工具通过结构化的日志系统（Learnings/Errors/Feature Requests）构建项目的"组织记忆"，实现"捕获→去重→提升→提取→评估"的完整闭环。

核心用法

双根架构：区分 Skill 根（安装目录）和 Workspace 根（项目目录），所有学习记录写入工作区的 .learnings/ 目录，避免污染技能本身。

三种记录类型：

• Learning：记录纠正、知识缺口和最佳实践
• Error：记录非显而易见的失败和异常
• Feature Request：记录缺失能力和改进建议

标准工作流：
1. 确定 Workspace Root（优先 .git 或 CLAUDE.md 所在目录）
2. 初始化 .learnings/ 目录结构
3. 高风险操作前检索历史记录
4. 记录前搜索去重，使用 Pattern-Key 链接相关问题
5. 将验证过的规则提升为项目记忆（CLAUDE.md、AGENTS.md 等）
6. 通用模式提取为新 Skill

显著优点

• 零依赖安全：纯 Python/Bash 标准库，无第三方包风险
• 完全离线：无网络请求，数据完全本地留存
• 路径安全：严格的输入验证防止目录遍历攻击
• 智能去重：搜索优先策略避免条目碎片化
• 可演进架构：支持从单项目经验升级为可复用 Skill
• 非侵入式：静默记录不中断用户工作流

潜在局限

• 依赖手动触发：需要 Agent 主动识别"可复用学习"场景，存在漏记风险
• 无自动关联：相似问题的链接依赖人工判断
• 推广门槛高：从项目记忆提取为独立 Skill 需要人工评估通用性
• 无可视化界面：纯命令行交互，回顾依赖文本检索
• 规模瓶颈：高频使用下 Markdown 文件的检索效率可能下降

适合人群

• 长期项目维护者：需要跨会话保持上下文一致性
• 团队协作场景：需要沉淀项目特定约定和已知问题
• AI Agent 重度用户：希望减少重复解释相同约束
• 流程优化者：追求"一次解决，永久受益"的工作方式
• 安全敏感环境：无法使用联网工具的企业内网场景

常规风险

• 记录膨胀：缺乏自动归档机制，历史条目可能累积过多
• 模式误判：Agent 可能将一次性问题误判为可复用模式
• 提升滞后：已验证的规则若未及时推广，仍会造成重复错误
• 迁移成本：项目目录变更时，.learnings/ 需手动迁移
• 版本兼容：Python 3.11+ 要求可能限制部分旧环境使用