self-improvement

自改进

把一次性对话中的高价值经验，转成项目内可复用资产。

Quick Reference

情况	动作
命令/工具失败	记录到 .learnings/ERRORS.md
用户纠正你	记录到 .learnings/LEARNINGS.md，类别 correction
用户要求缺失能力	记录到 .learnings/FEATURE_REQUESTS.md
外部 API 失败	记录到 .learnings/ERRORS.md，含集成细节
知识已过时	记录到 .learnings/LEARNINGS.md，类别 knowledge_gap
发现更好做法	记录到 .learnings/LEARNINGS.md，类别 best_practice
与已有条目相似	用 See Also 关联，考虑提升优先级
广泛适用的经验	提升到 CLAUDE.md / AGENTS.md

文件结构

.learnings/
├── LEARNINGS.md
├── ERRORS.md
└── FEATURE_REQUESTS.md

何时记录

优先记录这些情况：

1. 用户纠正了你的判断、假设或实现方式
2. 工具、命令、运行环境出现了非显然失败
3. 用户要求当前系统不直接支持的能力
4. 你发现了值得复用的项目约束、工作流或最佳实践
5. 你的知识已过时或与实际行为不符

不要记录这些情况：

1. 明显且一次性的错误
2. 无需复盘即可解决的小问题
3. 与当前项目无关的泛泛常识

记录原则

1. 只保留高信号信息，避免把 .learnings/ 变成噪音堆积区
2. 先写"为什么以后还会有用"，再写"这次发生了什么"
3. 如果是错误，明确复现线索和建议修复方向
4. 如果是用户纠正，明确原假设哪里错了
5. 记录前先搜索已有条目，重复的用 See Also 关联
6. 如果模式已经稳定，考虑提升到 AGENTS.md 或抽出新 skill

记录格式

Learning

## [LRN-YYYYMMDD-XXXXXX] correction | knowledge_gap | best_practice

**Logged**: 2026-03-23T10:00:00+00:00
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config | runtime

### Summary
一句话说明学到了什么

### Details
说明当时的错误假设、触发条件和正确做法

### Suggested Action
以后应如何避免再次犯错

### Metadata
- Source: user_feedback | error | conversation
- Related Files: path/to/file.py
- Tags: tag1, tag2
- See Also: LRN-20260320-001 (如果与已有条目相关)
- Pattern-Key: correction.api_format (可选，用于重复模式追踪)
- Recurrence-Count: 1 (可选)

---

Error

## [ERR-YYYYMMDD-XXXXXX] auto_logged_error

**Logged**: 2026-03-23T10:00:00+00:00
**Priority**: medium | high
**Status**: pending
**Area**: runtime

### Summary
一句话说明哪里失败了

### Error
```text
具体错误内容
```

### Context
- Step: 3
- Tool: `bash`
- Task: 当前任务摘要

### Suggested Fix
说明后续应怎么复盘或修正

### Metadata
- Reproducible: yes | no | unknown
- Related Files: N/A
- Pattern-Key: tool_error.bash (可选)
- Recurrence-Count: 2 (可选)

---

Feature Request

## [FEAT-YYYYMMDD-XXXXXX] capability_name

**Logged**: 2026-03-23T10:00:00+00:00
**Priority**: medium
**Status**: pending
**Area**: runtime

### Requested Capability
用户需要什么能力

### User Context
为什么需要它

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
可行的最小实现思路

### Metadata
- Frequency: first_time | recurring
- Related Features: N/A

---

条目生命周期

Status	含义
pending	新记录，待处理
in_progress	正在处理中
resolved	已修复/已解决
promoted	已提升到 CLAUDE.md / AGENTS.md / 新 skill
wont_fix	决定不处理（在 Resolution 中说明原因）

解决条目时，追加 Resolution 块：

### Resolution
- **Resolved**: 2026-03-24T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: 简述做了什么

重复模式检测

记录前先搜索已有条目：

grep -r "keyword" .learnings/

如果找到相似条目：

1. 用 See Also 关联
2. 考虑提升优先级
3. 如果 Recurrence-Count >= 3，强烈建议提升到项目规则

Priority 指引

Priority	适用场景
critical	阻塞核心功能、数据丢失风险、安全问题
high	显著影响、常见工作流受阻、反复出现
medium	中等影响、有 workaround
low	轻微不便、边缘场景

Area 标签

Area	范围
frontend	UI、组件、客户端代码
backend	API、服务、服务端代码
infra	CI/CD、部署、Docker、云
tests	测试文件、测试工具
docs	文档、注释
config	配置文件、环境变量
runtime	Agent 运行时、工具执行

提升路径

当某条 learning 被多次验证、具有跨任务价值时：

Learning 类型	提升目标	示例
项目约定	CLAUDE.md	"包管理器用 uv，不要用 pip"
工作流规则	AGENTS.md	"API 变更后必须重新生成客户端"
可复用模式	新 skill	复杂到需要专门指导的模式

提升后更新原条目 Status 为 promoted，并注明 **Promoted**: CLAUDE.md。

Skill 提取标准

当 learning 满足以下任一条件时，可以提取为独立 skill：

• 有 2+ 条 See Also 关联（反复出现）
• Status 为 resolved 且修复方案经过验证
• 非显而易见，需要实际调试才能发现
• 不限于特定项目，跨代码库可用
• 用户明确要求 "把这个存为 skill"

与原生 Hook 的关系

项目内的 SelfImprovementHook 自动做这些事：

1. 运行前提醒你在必要时使用本 skill
2. 工具失败时自动往 ERRORS.md 记一条基础记录
3. 同一工具反复失败时自动提升优先级并追踪 Pattern-Key
4. 用户 reject/edit 反馈时自动往 LEARNINGS.md 记录
5. feature_request 反馈时自动往 FEATURE_REQUESTS.md 记录

自动记录只是保底。真正高质量的 learning 仍然需要你在任务结束前主动整理。

定期回顾

在以下时机回顾 .learnings/：

• 开始新的大型任务前
• 完成一个功能后
• 在有历史 learning 的区域工作时

grep -h "Status\*\*: pending" .learnings/*.md | wc -l
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["