Self-Improving Agent（自我改进）
把“踩坑”变成“资产”。 每次失败、纠正或新发现，都写入结构化记录，后续可检索、可复盘、可沉淀到长期规则。
1. 什么时候必须记录
出现以下任一情况时，立即记录：
- 命令/操作失败（非 0 退出、超时、异常输出）
- 用户纠正你（“不对”“应该是…”）
- 用户提出你当前不具备的能力
- 外部服务失败（API 报错、限流、鉴权失败）
- 你意识到知识已过时或理解错误
- 你发现了可复用的更优流程
2. 记录到哪里
在工作区使用 .learnings/：
.learnings/LEARNINGS.md：纠正、认知缺口、最佳实践.learnings/ERRORS.md：失败与异常.learnings/FEATURE_REQUESTS.md：能力请求
若目录不存在，先创建：
mkdir -p .learnings3. 快速分流规则
- 失败/报错 →
ERRORS.md - 被纠正/学到新规则 →
LEARNINGS.md - 想要但暂不支持的能力 →
FEATURE_REQUESTS.md
4. ID 规范
格式：TYPE-YYYYMMDD-XXX
- TYPE:
LRN/ERR/FEAT - 日期：当天日期
- XXX：三位序号（如
001）
示例：
LRN-20260308-001ERR-20260308-002FEAT-20260308-001
5. 模板（请严格使用）
5.1 Learning 模板（LEARNINGS.md）
## [LRN-YYYYMMDD-XXX] correction | knowledge_gap | best_practice
**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 | simplify-and-harden
- Related Files: path/to/file
- Tags: tag1, tag2
- See Also: LRN-...（可选）
- Pattern-Key: ...（可选）
- Recurrence-Count: 1（可选）
- First-Seen: YYYY-MM-DD（可选）
- Last-Seen: YYYY-MM-DD（可选）
---5.2 Error 模板（ERRORS.md）
## [ERR-YYYYMMDD-XXX] command_or_integration
**Logged**: ISO-8601 时间
**Priority**: medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config
### Summary
一句话说明失败点
### Error完整报错文本
### Context
- 执行了什么命令/操作
- 使用了哪些参数
- 关键环境信息
### Suggested Fix
可执行的修复建议
### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file
- See Also: ERR-...（可选）
---5.3 Feature Request 模板（FEATURE_REQUESTS.md）
## [FEAT-YYYYMMDD-XXX] capability_name
**Logged**: ISO-8601 时间
**Priority**: low | medium | high
**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: ...（可选）
---6. 状态流转
允许状态：
pending：待处理in_progress：处理中resolved：已解决promoted：已提升到长期规则文件wont_fix：不处理（需写原因）
当问题已解决时，补充：
### Resolution
- **Resolved**: ISO-8601 时间
- **Commit/PR**: commit hash 或 PR 链接
- **Notes**: 做了什么7. 何时“晋升”到长期记忆文件
满足以下任一条件，建议晋升：
- 同类问题重复出现
- 对多人/多任务都适用
- 不写下来就会反复踩坑
晋升目标：
- 工作流规则 →
AGENTS.md - 行为/表达规则 →
SOUL.md - 工具使用细节 →
TOOLS.md - 长期偏好/事实 →
MEMORY.md
晋升后把原条目状态改为 promoted，并注明目标文件。
8. 复盘频率
建议在以下时机快速复盘 .learnings/：
- 开始新任务前
- 完成复杂任务后
- 每周至少一次
可用命令：
# 统计 pending
grep -h "Status\*\*: pending" .learnings/*.md | wc -l
# 查看高优先级
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["9. 执行原则（简版）
- 立即记录：别等会儿，信息会丢。
- 写可执行建议：不是“再看看”，而是“下次先做 X”。
- 优先去重与关联：能关联就加
See Also。 - 重复三次就系统化：提升到
AGENTS.md/SOUL.md/TOOLS.md。 - 短而准：结论可复用，描述可追溯。
10. OpenClaw 场景建议
- 在主会话中把高价值学习同步到
MEMORY.md。 - 在需要跨会话协作时，使用
sessions_send分享关键学习。 - 对高频重复问题，优先将规则写入工作区文档，减少未来上下文成本。
目标不是“记日志”，而是持续降低错误率、提高可复用性。