---
name: self-improving-agent
description: >
  记录经验、错误与纠正信息，用于持续改进。适用场景包括命令或操作意外失败、
  用户纠正 agent、用户提出当前不存在的能力需求、外部 API 或工具失败、agent
  发现自己的知识已过期或有误、以及为重复性任务发现更好的做法。执行重大任务前
  也应先回顾 learnings。触发短语：记录经验、沉淀经验、复盘经验、self improvement、
  learning log、capture learnings。
metadata:
---

# 自我改进 Skill

将经验与错误记录到 markdown 文件中，以支持持续改进。后续编码 agent 可以基于这些记录做修复，而高价值经验则可以提升为项目记忆或规则。

## 快速参考


| 场景           | 动作                                                                                     |
| ------------ | -------------------------------------------------------------------------------------- |
| 命令或操作失败      | 新建独立文件 `.learnings/ERRORS/<ERR-id>.md`（不要追加到 ERRORS.md，会冲突；详见 issue #189）             |
| 用户纠正你        | 记录到 `.learnings/LEARNINGS.md`，分类为 `correction`                                         |
| 用户想要缺失功能     | 记录到 `.learnings/FEATURE_REQUESTS.md`                                                   |
| API / 外部工具失败 | 新建独立文件 `.learnings/ERRORS/<ERR-id>.md`，写明集成细节                                          |
| 知识已过期        | 记录到 `.learnings/LEARNINGS.md`，分类为 `knowledge_gap`                                      |
| 发现更好的方法      | 记录到 `.learnings/LEARNINGS.md`，分类为 `best_practice`                                      |
| 需要简化/加固重复模式  | 在 `.learnings/LEARNINGS.md` 中记录或更新，带上 `Source: simplify-and-harden` 和稳定的 `Pattern-Key` |
| 与已有条目相似      | 使用 `**See Also**` 关联，必要时提升优先级                                                          |
| 适用范围广的经验     | 提升到 `CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`                            |
| 工作流改进        | 提升到 `AGENTS.md`                                                                        |
| 工具使用坑点       | 记录到 `AGENTS.md` 的工具注意事项或项目文档中                                                           |
| 行为模式         | 记录到 `AGENTS.md` 的协作约定中                                                                  |


---

### 在 `AGENTS.md`、`CLAUDE.md`中加入提醒，提示自己记录 learnings（这是 hook 之外的替代方案）

#### 自我改进工作流

当出现错误或被纠正时：

1. 记录到 `.learnings/ERRORS/<ERR-id>.md`、`LEARNINGS.md` 或 `FEATURE_REQUESTS.md`
2. 回顾并将具有广泛适用性的经验提升到：
  - `CLAUDE.md`：项目事实与约定
  - `AGENTS.md`：工作流与自动化规则
  - `.github/copilot-instructions.md`：Copilot 上下文

## 日志格式

### Learning 条目

追加到 `.learnings/LEARNINGS.md`：

```markdown
## [LRN-YYYYMMDD-XXX] 分类

**Logged**: ISO-8601 时间戳
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
一句话描述学到了什么

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

### Suggested Action
给出具体修复或改进建议

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001（如与现有条目相关）
- Pattern-Key: simplify.dead_code | harden.input_validation（可选，用于跟踪重复模式）
- Recurrence-Count: 1（可选）
- First-Seen: 2025-01-15（可选）
- Last-Seen: 2025-01-15（可选）

---
```

### Error 条目

新建独立文件 `.learnings/ERRORS/<ERR-id>.md`（**不要**追加到 `ERRORS.md` 或 `INDEX.md` —— 任何多 PR 并行写的共享文件必冲突，已拆成纯每条独立文件；详见 issue #189 + issue #456 / PR #446）。

文件名本身就是索引——`ls .learnings/ERRORS/ | sort -r` 就是按日期倒序的目录。查找方法见 `.learnings/ERRORS/README.md`。

文件内容（标题就是条目正文）：

```markdown
## [ERR-YYYYMMDD-XXX] skill_or_command_name

**Logged**: ISO-8601 时间戳
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
简要描述失败了什么

### Error
```

实际错误信息或输出

```

### Context
- 执行了什么命令/操作
- 使用了哪些输入或参数
- 如果相关，补充环境细节

### Suggested Fix
如果能判断，写明可能的解决方式

### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file.ext
- See Also: ERR-20250110-001（如为重复问题）

---
```

### Feature Request 条目

追加到 `.learnings/FEATURE_REQUESTS.md`：

```markdown
## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 时间戳
**Priority**: medium
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Requested Capability
用户想要完成什么

### User Context
为什么需要这个能力、正在解决什么问题

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
可以如何实现、可能扩展哪些现有能力

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_feature_name

---
```

## ID 生成规则

格式：`TYPE-YYYYMMDD-XXX`

- TYPE：`LRN`（learning）、`ERR`（error）、`FEAT`（feature）
- YYYYMMDD：当前日期
- XXX：顺序编号或随机 3 位字符（例如 `001`、`A7B`）

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

## 条目关闭与状态更新

当某个问题被修复后，更新对应条目：

1. 将 `**Status**: pending` 改为 `**Status**: resolved`
2. 在 `Metadata` 之后补充解决块：

```markdown
### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 或 #42
- **Notes**: 简要说明做了什么
```

其他可用状态值：

- `in_progress`：正在处理中
- `wont_fix`：决定不处理（需在 `Resolution` 里写原因）
- `promoted`：已提升到 `CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`

## 提升到项目记忆

当某条 learning 具有广泛适用性，而不是一次性修复时，应将其提升到长期项目记忆。

### 何时提升

- 该经验适用于多个文件或多个功能
- 这是任何贡献者（人类或 AI）都应该知道的知识
- 能防止重复犯错
- 记录了项目特有的约定

### 提升目标


| 目标          | 适合放什么                   |
| ----------- | ----------------------- |
| `CLAUDE.md` | 面向 Claude 交互的项目事实、约定和坑点 |
| `AGENTS.md` | agent 工作流、工具使用模式、自动化规则 |
| `.github/copilot-instructions.md` | 提供给 GitHub Copilot 的项目上下文和约定 |


### 如何提升

1. **提炼** 这条经验，把它压缩成简洁规则或事实
2. **加入** 对应目标文件的合适章节（如果没有就新建）
3. **更新** 原始条目：
  - 将 `**Status**: pending` 改为 `**Status**: promoted`
  - 增加 `**Promoted**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`

### 提升示例

**Learning**（详细版）：

> 项目使用 pnpm workspaces。尝试执行 `npm install` 会失败。
> 锁文件是 `pnpm-lock.yaml`，必须使用 `pnpm install`。

**在 `CLAUDE.md` 中**（简洁版）：

```markdown
## 构建与依赖
- 包管理器：pnpm（不是 npm）- 使用 `pnpm install`
```

**Learning**（详细版）：

> 修改 API 接口后，必须重新生成 TypeScript client。
> 忘记执行会在运行时导致类型不匹配。

**在 `AGENTS.md` 中**（可执行版）：

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

## 重复模式检测

如果准备记录的内容与已有条目相似：

1. **先搜索**：`grep -r "keyword" .learnings/`
2. **关联条目**：在 `Metadata` 中加入 `**See Also**: ERR-20250110-001`
3. **提升优先级**：如果问题持续重复出现
4. **考虑系统性修复**：重复问题通常意味着：
  - 文档缺失（→ 提升到 `AGENTS.md`）
  - 自动化缺失（→ 加到 `AGENTS.md`）
  - 架构问题（→ 创建技术债任务）

## Simplify & Harden 经验输入通道

使用这个工作流，把 `simplify-and-harden` skill 中反复出现的模式转成更稳定的提示规则。

### 收录流程

1. 从任务总结中读取 `simplify_and_harden.learning_loop.candidates`
2. 对每个 candidate，使用 `pattern_key` 作为稳定去重键
3. 在 `.learnings/LEARNINGS.md` 中查找是否已有该键对应的条目：
  - `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md`
4. 如果已存在：
  - 增加 `Recurrence-Count`
  - 更新 `Last-Seen`
  - 为相关条目/任务补充 `See Also`
5. 如果不存在：
  - 创建新的 `LRN-...` 条目
  - 设置 `Source: simplify-and-harden`
  - 设置 `Pattern-Key`、`Recurrence-Count: 1` 和 `First-Seen` / `Last-Seen`

### 提升规则（系统提示反馈）

当满足以下全部条件时，将重复模式提升到 agent 上下文或系统提示文件：

- `Recurrence-Count >= 3`
- 至少出现在 2 个不同任务中
- 出现时间落在 30 天窗口内

提升目标：

- `CLAUDE.md`
- `AGENTS.md`
- `.github/copilot-instructions.md`

写入时应使用简短的预防性规则，说明编码前/编码中该做什么，而不是写成长篇事故复盘。

## 定期回顾

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

### 何时回顾

- 开始新的重大任务前
- 完成一个功能后
- 在曾经出过问题的区域工作时
- 活跃开发期间每周一次

### 快速状态检查

```bash
# 统计待处理条目数量
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

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

# 查找某个区域的相关经验
grep -l "Area\*\*: backend" .learnings/*.md
```

### 回顾动作

- 关闭已修复条目
- 提升适用范围广的经验
- 关联相关条目
- 升级重复问题

## 触发条件识别

当你观察到以下情况时，应自动记录：

**纠正**（→ 记录为 `correction` 类 learning）：

- “不是，这里不对……”
- “实际上，应该是……”
- “你这里说错了……”
- “这个信息过期了……”

**功能请求**（→ 记录为 feature request）：

- “你还能不能顺便……”
- “我希望你可以……”
- “有没有办法……”
- “为什么你不能……”

**知识缺口**（→ 记录为 `knowledge_gap` 类 learning）：

- 用户提供了你原本不知道的信息
- 你引用的文档已经过期
- API 实际行为与你原本理解不一致

**错误**（→ 记录为 error entry）：

- 命令返回非零退出码
- 出现异常或堆栈
- 输出或行为不符合预期
- 超时或连接失败

## 优先级指引


| 优先级        | 适用时机                 |
| ---------- | -------------------- |
| `critical` | 阻塞核心功能、存在数据丢失风险或安全问题 |
| `high`     | 影响显著、影响常见工作流、或属于重复问题 |
| `medium`   | 影响中等，但存在可接受的绕行方案     |
| `low`      | 轻微不便、边界情况、或锦上添花      |


## Area 标签

用于按代码库区域筛选 learnings：


| Area       | 范围                  |
| ---------- | ------------------- |
| `frontend` | UI、组件、客户端代码         |
| `backend`  | API、服务、服务端代码        |
| `infra`    | CI/CD、部署、Docker、云环境 |
| `tests`    | 测试文件、测试工具、覆盖率       |
| `docs`     | 文档、注释、README        |
| `config`   | 配置文件、环境变量、设置        |


## 最佳实践

1. **立即记录**：问题刚发生时上下文最完整
2. **写具体**：未来的 agent 需要快速理解
3. **写清复现步骤**：尤其是错误类条目
4. **关联相关文件**：方便后续修复
5. **给出具体修复建议**：不要只写“需要调查”
6. **保持分类一致**：便于过滤和统计
7. **积极提升**：如果拿不准，就考虑加入 `CLAUDE.md` 或 `.github/copilot-instructions.md`
8. **定期回顾**：过期的 learnings 会迅速贬值

## Gitignore 方案

**将 learnings 保持为本地内容**（每位开发者各自维护）：

```gitignore
.learnings/
```

**将 learnings 纳入仓库版本控制**（团队共享）：
不要加入 `.gitignore`，让 learnings 成为共享知识。

**混合方案**（保留模板，忽略具体条目）：

```gitignore
.learnings/*.md
!.learnings/.gitkeep
```

## Hook 集成

通过 agent hooks 启用自动提醒。这是 **opt-in** 的，必须显式配置。

### 快速配置（Claude Code / Codex）

在项目里创建 `.claude/settings.json`：

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

这会在每次 prompt 后注入一条 learning 评估提醒，额外开销约 50-100 tokens。

### 完整配置（包含错误检测）

```json
{
  "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 脚本


| 脚本                          | Hook 类型            | 作用                        |
| --------------------------- | ------------------ | ------------------------- |
| `scripts/activator.sh`      | UserPromptSubmit   | 提醒在任务结束后评估是否有新的 learnings |
| `scripts/error-detector.sh` | PostToolUse (Bash) | 在命令报错时触发提醒                |


详细配置与故障排查见 `references/hooks-setup.md`。

## 自动提炼 Skill

当某条 learning 有足够价值，值得变成可复用 skill 时，可以用仓库自带的辅助脚本提炼。

### Skill 提炼条件

当满足以下任意条件时，可考虑提炼为 skill：


| 条件         | 说明                           |
| ---------- | ---------------------------- |
| **重复出现**   | 已通过 `See Also` 关联了 2 条以上类似问题 |
| **已验证**    | 状态为 `resolved`，且修复方案已证明有效    |
| **不直观**    | 需要实际调试或调查后才发现解法              |
| **适用范围广**  | 不是项目专属问题，对其他代码库也有价值          |
| **用户明确要求** | 用户说了“把这个保存成 skill”之类的话       |


### 提炼流程

1. **识别候选项**：该 learning 符合提炼条件
2. **运行辅助脚本**（或手工创建）：
  ```bash
   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
  ```
3. **完善 `SKILL.md`**：把模板中的占位内容替换成真正的经验内容
4. **更新 learning**：将状态改为 `promoted_to_skill`，并添加 `Skill-Path`
5. **验证**：在一个新的 session 中读取 skill，确认它已足够自洽

### 手工提炼

如果你更倾向手工创建：

1. 创建 `skills/<skill-name>/SKILL.md`
2. 使用 `assets/SKILL-TEMPLATE.md` 作为模板
3. 遵循 [Agent Skills 规范](https://agentskills.io/specification)：
  - 使用包含 `name` 与 `description` 的 YAML frontmatter
  - `name` 必须与文件夹名称一致
  - skill 目录内不要放 `README.md`

### 提炼触发信号

关注这些信号，它们往往意味着某条 learning 应该升级为 skill：

**在对话中：**

- “把这个保存成 skill”
- “我总是遇到这个问题”
- “这个在别的项目也会有用”
- “记住这个模式”

**在 learning 条目中：**

- 存在多个 `See Also` 链接（说明它在重复出现）
- 优先级高，且状态已 `resolved`
- 分类为 `best_practice`，且适用范围广
- 用户明确认可这个方案

### Skill 质量门槛

在提炼前，确认：

- 方案已经过测试并可用
- 描述不依赖原始上下文也能理解
- 代码示例是自包含的
- 没有硬编码项目专属值
- 命名符合 skill 规范（小写、连字符）

## 多 Agent 支持

这个 skill 可以在不同 AI 编码 agent 中使用，但激活方式因平台而异。

### Claude Code

**Activation**：Hooks（`UserPromptSubmit`、`PostToolUse`）
**Setup**：在 `.claude/settings.json` 中配置 hooks
**Detection**：通过 hook 脚本自动检测

### Codex CLI

**Activation**：Hooks（与 Claude Code 相同模式）
**Setup**：在 `.codex/settings.json` 中配置 hooks
**Detection**：通过 hook 脚本自动检测

### GitHub Copilot

**Activation**：手动（不支持 hooks）
**Setup**：加入 `.github/copilot-instructions.md`：

```markdown
## Self-Improvement

解决了不直观的问题后，考虑将经验记录到 `.learnings/`：
1. 使用 self-improvement skill 中定义的格式
2. 通过 See Also 关联相关条目
3. 将高价值经验提升为 skill

可以在聊天中提醒：
"我是否应该把这个记录为一条 learning？"
```

**Detection**：在 session 结束时手动回顾

### 平台无关指引

无论使用哪个 agent，遇到以下情况都应启用自我改进流程：

1. **发现不直观的信息**：解法不是立刻就能想到的
2. **纠正了自己**：最初方案是错的
3. **学到了项目约定**：发现了未文档化的模式
4. **遇到意外错误**：尤其是诊断困难的错误
5. **找到了更好的方法**：在原方案基础上做出了明显改进

### Copilot Chat 集成

对于 Copilot 用户，可以在相关 prompt 中加入：

> 完成任务后，请评估是否有经验需要按 self-improvement skill 格式记录到 `.learnings/`。

也可以使用这些简短指令：

- “把这个记录到 learnings”
- “从这个解法提炼一个 skill”
- “检查 `.learnings/` 里有没有相关问题”