名称： self-improvement
描述： "记录学习心得、错误与修正，以实现持续改进。适用于以下场景：(1) 命令或操作意外失败，(2) 用户纠正 Claude（如'不，那是错的...'、'实际上...'），(3) 用户请求不存在的功能，(4) 外部 API 或工具失败，(5) Claude 意识到其知识已过时或不正确，(6) 为重复性任务发现了更好的方法。在开始重要任务前也应回顾学习记录。"

自我改进技能

将学习心得和错误记录到 Markdown 文件中，以实现持续改进。后续编码代理可将其处理为修复方案，重要的学习内容可提升至项目记忆。

快速参考

设置

如果项目根目录下不存在 .learnings/ 目录，请创建：

mkdir -p .learnings

从 assets/ 复制模板或创建带标题的文件。

记录格式

学习条目

追加到 .learnings/LEARNINGS.md：

## [LRN-YYYYMMDD-XXX] 类别

**记录时间**: ISO-8601 时间戳
**优先级**: 低 | 中 | 高 | 关键
**状态**: 待处理
**领域**: 前端 | 后端 | 基础设施 | 测试 | 文档 | 配置

### 摘要
一行描述所学内容

### 详情
完整上下文：发生了什么、哪里错了、正确的做法是什么

### 建议操作
具体的修复或改进措施

### 元数据
- 来源: 对话 | 错误 | 用户反馈
- 相关文件: 路径/到/文件.ext
- 标签: 标签1, 标签2
- 参见: LRN-20250110-001（若与现有条目相关）

---

错误条目

追加到 .learnings/ERRORS.md：

## [ERR-YYYYMMDD-XXX] 技能_或_命令_名称

**记录时间**: ISO-8601 时间戳
**优先级**: 高
**状态**: 待处理
**领域**: 前端 | 后端 | 基础设施 | 测试 | 文档 | 配置

### 摘要
简要描述失败情况

### 错误

实际错误信息或输出

### 上下文
- 尝试的命令/操作
- 使用的输入或参数
- 相关的环境详情

### 建议修复
如可识别，可能解决此问题的方法

### 元数据
- 可重现: 是 | 否 | 未知
- 相关文件: 路径/到/文件.ext
- 参见: ERR-20250110-001（若为重复出现）

---

功能请求条目

追加到 .learnings/FEATURE_REQUESTS.md：

## [FEAT-YYYYMMDD-XXX] 功能_名称

**记录时间**: ISO-8601 时间戳
**优先级**: 中
**状态**: 待处理
**领域**: 前端 | 后端 | 基础设施 | 测试 | 文档 | 配置

### 请求的功能
用户希望实现什么

### 用户上下文
为什么需要它，他们正在解决什么问题

### 复杂度评估
简单 | 中等 | 复杂

### 建议实现
如何构建，可能扩展什么

### 元数据
- 频率: 首次 | 重复
- 相关功能: 现有_功能_名称

---

ID 生成

格式：TYPE-YYYYMMDD-XXX
- TYPE: LRN（学习）、ERR（错误）、FEAT（功能）
- YYYYMMDD: 当前日期
- XXX: 顺序号或随机 3 字符（例如 001、A7B）

示例：LRN-20250115-001、ERR-20250115-A3F、FEAT-20250115-002

解决条目

当问题修复后，更新条目：

1. 将 **状态**: 待处理 → **状态**: 已解决
2. 在元数据后添加解决块：

### 解决
- **解决时间**: 2025-01-16T09:00:00Z
- **提交/PR**: abc123 或 #42
- **备注**: 简要描述所做工作

其他状态值：
- 进行中 - 正在积极处理
- 不予修复 - 决定不处理（在解决备注中添加原因）
- 已提升 - 已提升至 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升至项目记忆

当学习内容广泛适用（非一次性修复）时，将其提升至永久项目记忆。

何时提升

• 学习内容适用于多个文件/功能
• 任何贡献者（人或 AI）都应了解的知识
• 防止重复错误
• 记录项目特定约定

提升目标

如何提升

1. 提炼 学习内容为简洁规则或事实
2. 添加 到目标文件的适当部分（如需要则创建文件）
3. 更新 原始条目：
   - 将 **状态**: 待处理 → **状态**: 已提升
   - 添加 **提升至**: CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升示例

学习内容（详细）：

项目使用 pnpm 工作区。尝试 npm install 但失败。
锁文件是 pnpm-lock.yaml。必须使用 pnpm install。

在 CLAUDE.md 中（简洁）：

## 构建与依赖
- 包管理器: pnpm（非 npm）- 使用 `pnpm install`

学习内容（详细）：

修改 API 端点时，必须重新生成 TypeScript 客户端。
忘记此步骤会导致运行时类型不匹配。

在 AGENTS.md 中（可操作）：

## API 变更后
1. 重新生成客户端: `pnpm run generate:api`
2. 检查类型错误: `pnpm tsc --noEmit`

重复模式检测

如果记录的内容与现有条目类似：

1. 先搜索：grep -r "关键词" .learnings/
2. 链接条目：在元数据中添加 **参见**: ERR-20250110-001
3. 提高优先级 如果问题持续出现
4. 考虑系统性修复：重复问题通常表明：
   - 缺少文档（→ 提升至 CLAUDE.md 或 .github/copilot-instructions.md）
   - 缺少自动化（→ 添加到 AGENTS.md）
   - 架构问题（→ 创建技术债务工单）

定期回顾

在自然断点处回顾 .learnings/：

何时回顾

• 开始新重要任务前
• 完成功能后
• 在具有过往学习内容的领域工作时
• 活跃开发期间的每周

快速状态检查

# 统计待处理项数量
grep -h "状态\*\*: 待处理" .learnings/*.md | wc -l

# 列出待处理的高优先级项
grep -B5 "优先级\*\*: 高" .learnings/*.md | grep "^## \["

# 查找特定领域的学习内容
grep -l "领域\*\*: 后端" .learnings/*.md

回顾操作

• 解决已修复项
• 提升适用的学习内容
• 链接相关条目
• 上报重复问题

检测触发器

当你注意到以下情况时自动记录：

纠正（→ 类别为 correction 的学习）：
- "不，那不对..."
- "实际上，应该是..."
- "你关于...的说法是错的"
- "那已经过时了..."

功能请求（→ 功能请求）：
- "你还能..."
- "我希望你能..."
- "有没有办法..."
- "为什么你不能..."

知识缺口（→ 类别为 knowledge_gap 的学习）：
- 用户提供你不知道的信息
- 你引用的文档已过时
- API 行为与你的理解不同

错误（→ 错误条目）：
- 命令返回非零退出码
- 异常或堆栈跟踪
- 意外输出或行为
- 超时或连接失败

优先级指南

领域标签

用于按代码库区域筛选学习内容：

最佳实践

1. 立即记录 - 问题发生后上下文最新鲜
2. 具体明确 - 未来的代理需要快速理解
3. 包含重现步骤 - 特别是对于错误
4. 链接相关文件 - 使修复更容易
5. 建议具体修复 - 不仅仅是"调查"
6. 使用一致的类别 - 便于筛选
7. 积极提升 - 如有疑问，添加到 CLAUDE.md 或 .github/copilot-instructions.md
8. 定期回顾 - 过时的学习内容会失去价值

Gitignore 选项

本地保留学习记录（每位开发者）：

.learnings/

在仓库中跟踪学习记录（团队共享）：
不要添加到 .gitignore - 学习记录成为共享知识。

混合模式（跟踪模板，忽略条目）：

.learnings/*.md
!.learnings/.gitkeep

钩子集成

通过代理钩子启用自动提醒。这是可选的 - 你必须显式配置钩子。

快速设置（Claude Code / Codex）

在项目中创建 .claude/settings.json：

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}

这会在每次提示后注入学习评估提醒（约 50-100 个令牌的开销）。

完整设置（带错误检测）

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}

可用的钩子脚本

详细配置和故障排除请参见 references/hooks-setup.md。

自动技能提取

当学习内容足够有价值，可成为可重用技能时，使用提供的辅助工具进行提取。

技能提取标准

当满足以下任何条件时，学习内容符合技能提取资格：

提取工作流

1. 识别候选：学习内容满足提取标准
2. 运行辅助工具（或手动创建）：
   bash ./skills/self-improvement/scripts/extract-skill.sh 技能名称 --dry-run ./skills/self-improvement/scripts/extract-skill.sh 技能名称
3. 自定义 SKILL.md：用学习内容填充模板
4. 更新学习记录：将状态设置为 已提升为技能，添加 技能路径
5. 验证：在新会话中阅读技能以确保其自包含

手动提取

如果偏好手动创建：

1. 创建 skills/<技能名称>/SKILL.md
2. 使用 assets/SKILL-TEMPLATE.md 中的模板
3. 遵循 Agent Skills 规范：
   - 带有 name 和 description 的 YAML 前言
   - 名称必须与文件夹名称匹配
   - 技能文件夹内无 README.md

提取检测触发器

注意以下信号，表明学习内容应成为技能：

在对话中：
- "将此保存为技能"
- "我经常遇到这个问题"
- "这对其他项目会有用"
- "记住这个模式"

在学习条目中：
- 多个 参见 链接（重复问题）
- 高优先级 + 已解决状态
- 类别：具有广泛适用性的 best_practice
- 用户反馈赞扬解决方案

技能质量门控

提取前验证：

• [ ] 解决方案经过测试且有效
• [ ] 描述清晰，无需原始上下文
• [ ] 代码示例自包含
• [ ] 无项目特定的硬编码值
• [ ] 遵循技能命名约定（小写，连字符）

多代理支持

此技能适用于不同的 AI 编码代理，并支持代理特定激活。

Claude Code

激活: 钩子（UserPromptSubmit, PostToolUse）
设置: 带有钩子配置的 .claude/settings.json
检测: 通过钩子脚本自动

Codex CLI

激活: 钩子（与 Claude Code 相同模式）
设置: 带有钩子配置的 .codex/settings.json
检测: 通过钩子脚本自动

GitHub Copilot

激活: 手动（无钩子支持）
设置: 添加到 .github/copilot-instructions.md：

## 自我改进

解决非显而易见的问题后，考虑记录到 `.learnings/`：
1. 使用自我改进技能中的格式
2. 使用参见链接相关条目
3. 将高价值学习内容提升为技能

在聊天中询问："我是否应将此记录为学习内容？"

检测: 会话结束时手动回顾

Clawdbot

激活: 工作区注入 + 代理间消息传递
设置: 在 ~/.clawdbot/clawdbot.json 中配置工作区路径
检测: 通过会话工具和工作区文件（AGENTS.md、SOUL.md、TOOLS.md）

Clawdbot 使用基于工作区的模型，并注入提示文件。详细设置请参见 references/clawdbot-integration.md。

代理无关指导

无论使用何种代理，在以下情况下应用自我改进：

1. 发现非显而易见的内容 - 解决方案不是立即得出的
2. 纠正自己 - 初始方法是错误的
3. 学习项目约定 - 发现未记录的模式
4. 遇到意外错误 - 特别是如果诊断困难
5. 找到更好的方法 - 改进了原始解决方案

Copilot 聊天集成

对于 Copilot 用户，在相关时将此添加到提示中：

完成此任务后，评估是否有任何学习内容应使用自我改进技能格式记录到 .learnings/。

或使用快速提示：
- "将此记录到学习记录"
- "从此解决方案创建技能"
- "检查 .learnings/ 中的相关问题"

Clawdbot 集成

Clawdbot 使用基于工作区的提示注入，