---

name: self-improvement description: "记录学习心得、错误及修正，实现持续改进。使用场景：(1) 命令或操作意外失败时 (2) 用户纠正 Claude（'不对，应该是...'、'实际上...'）(3) 用户请求不存在的能力 (4) 外部 API 或工具失败 (5) Claude 发现知识过时或错误 (6) 针对重复性任务发现更优方案。重要任务前需回顾学习记录"

自我提升技能

将学习心得和错误记录为 markdown 文件以实现持续改进。后续编程代理可将其转化为修复方案，重要学习内容将升级至项目记忆库。

快速参考

设置

若项目根目录不存在 .learnings/ 文件夹则创建：

mkdir -p .learnings

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

记录格式

学习条目

追加到 .learnings/LEARNINGS.md：

[LRN-YYYYMMDD-XXX] 分类

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

概要

学习内容的单行描述

详情

完整背景：发生了什么问题，错误点在哪里，正确做法是什么

建议措施

具体的修复或改进方案

元数据

• 来源: 对话记录 | 系统报错 | 用户反馈
• 相关文件: 路径/文件名.扩展名
• 标签: 标签1, 标签2
• 另见: LRN-20250110-001（若与现有条目相关）

---

错误记录

添加到.learnings/ERRORS.md:

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

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

### 概要  
失败场景的简要说明  

### 错误详情  

实际报错信息或输出

### 上下文  
- 尝试执行的命令/操作  
- 使用的输入参数  
- 相关环境信息（如适用）  

### 建议修复  
已知的可行解决方案  

### 元数据  
- 可复现性: 是 | 否 | 不确定  
- 相关文件: 路径/文件名.扩展名  
- 另见: 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. 将 **Status**: pending 更改为 **Status**: resolved
2. 在 Metadata 后添加解决块：

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: 简要描述所做的工作

其他状态值：

• in_progress - 正在积极处理中
• wont_fix - 决定不解决（在 Resolution notes 中添加原因）
• promoted - 已提升至 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升为项目记忆

当学习成果具有广泛适用性（非一次性修复）时，将其提升为永久性项目记忆。

何时提升

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

提升目标

如何提升

1. 提炼学习成果为简洁的规则或事实
2. 添加到目标文件的适当部分（如有必要创建文件）
3. 更新原始条目：
   • 将 **Status**: pending 改为 **Status**: promoted
   • 添加 **Promoted**: 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. 考虑系统性修复：重复出现的问题通常表明：
   • 文档缺失（→ 提升到 CLUDE.md 或 .github/copilot-instructions.md）
   • 自动化缺失（→ 添加到 AGENTS.md）
   • 架构问题（→ 创建技术债务任务）

定期回顾

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

何时回顾

• 开始新的大型任务之前
• 完成一个功能后
• 在有过去学习记录的领域中工作时
• 在积极开发期间每周

快速状态检查

# 统计待处理项目
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

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

# 查找特定领域的学习记录
grep -l "Area\*\*: backend" .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

Hook 集成

通过 agent hooks 启用自动提醒功能。这是一个可选功能 —— 你必须明确地配置 hooks。

快速设置 (Claude Code / Codex)

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

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

这将在每次提示后注入一个学习评估提醒（大约 50-100 个 tokens 的开销）。

完整设置 (带有错误检测)

{
  "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"
      }]
    }]
  }
}

可用的 Hook 脚本

有关详细配置和故障排除，请参阅 references/hooks-setup.md。

自动技能提取

当某个学习经验足够有价值成为可复用技能时，使用提供的辅助工具进行提取。

技能提取标准

满足以下任意条件即可进行技能提取：

提取流程

1. 识别候选：学习经验符合提取标准
2. 运行辅助工具（或手动创建）：

   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
   

3. 定制 SKILL.md：用学习内容填充模板
4. 更新学习记录：将状态设为 promoted_to_skill，添加 Skill-Path
5. 验证：在新会话中阅读技能文档确保自包含性

手动提取

若倾向手动创建：

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

提取触发信号

注意以下表明应转为技能的信号：

对话中：

• "保存为技能"
• "这个问题反复出现"
• "对其他项目也有用"
• "记住这个模式"

学习记录中：

• 多个 See Also 链接（重复问题）
• 高优先级 + 已解决状态
• 分类为 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 使用基于工作区的提示注入，针对不同关注点使用专门的文件。

### 工作区结构

~/clawd/ # 默认工作区（可配置） ├── AGENTS.md # 多代理工作流、委派模式 ├── SOUL.md # 行为准则、沟通风格 ├── TOOLS.md # 工具能力、MCP 集成 └── sessions/ # 会话记录（自动管理）

### Clawdbot 提升目标

| 学习类型 | 提升至 | 示例 |
|--------------|------------|---------|
| 代理协调 | `AGENTS.md` | "将文件搜索委派给探索代理" |
| 沟通风格 | `SOUL.md` | "简明扼要，避免免责声明" |
| 工具陷阱 | `TOOLS.md` | "MCP 服务器 X 需要身份验证刷新" |
| 项目事实 | `CLAUDE.md` | 标准项目惯例 |

### 代理间学习

Clawdbot 支持基于会话的通信：
- **sessions_list** - 查看活动/最近的会话
- **sessions_history** - 读取另一个会话的记录
- **sessions_send** - 向另一个会话发送消息

### 混合设置（Claude Code + Clawdbot）

同时使用时：
1. 保留 `.learnings/` 以存储项目特定的学习内容
2. 使用 clawdbot 工作区文件存储跨项目模式
3. 将高价值学习内容同步到两个系统

请参阅 `references/clawdbot-integration.md` 获取完整的设置、提升格式和故障排除信息。