self-improvement

自我改进技能

将经验和错误记录到 Markdown 文件中，以实现持续改进。编码 Agent 之后可以处理这些记录并修复问题，重要经验则会提升为项目记忆。

安装命令请参阅 references/installation.md。有关可选的 Agent 激活和钩子，请参阅 references/hooks-setup.md。仅在安装或配置此技能时阅读这些内容。

与 self-healing 配合使用： self-healing 是主动的运行时恢复原语——当任务执行期间出现问题时，它会诊断、修补、验证，并将 HEAL- 条目写入 .learnings/HEALS.md。自我改进（本技能）是被动的积累与提升层——它会记录纠正信息、知识缺口和功能请求，并将反复出现的修复交接内容提升为永久记忆。两者共用 .learnings/，但写入不同的文件；验证规范由 self-healing 负责，提升逻辑由本技能负责。

快速参考

情况	操作
任务执行期间出现故障——Agent 需要立即修复	改用 self-healing（将已验证的 HEAL- 条目写入 .learnings/HEALS.md）
过去的命令／操作失败（当前并非正在修复）	记录到 .learnings/ERRORS.md
用户纠正了你	将类别设为 correction，记录到 .learnings/LEARNINGS.md
用户需要缺失的功能	记录到 .learnings/FEATURE_REQUESTS.md
API／外部工具失败	将集成详情记录到 .learnings/ERRORS.md
self-healing 交接区块符合提升规则（见下文“提升规则”）	将提炼后的规则提升到 CLAUDE.md／AGENTS.md／新技能
知识已过时	将类别设为 knowledge_gap，记录到 .learnings/LEARNINGS.md
找到更好的方法	将类别设为 best_practice，记录到 .learnings/LEARNINGS.md
简化／强化反复出现的模式	在 .learnings/LEARNINGS.md 中记录／更新，并添加 Source: simplify-and-harden 和稳定的 Pattern-Key
与现有条目相似	使用 **See Also** 添加链接，并考虑提高优先级
适用范围广的经验	提升到 CLAUDE.md、AGENTS.md 和／或 .github/copilot-instructions.md

设置

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

mkdir -p .learnings

从 assets/ 复制文件模板（LEARNINGS.md、ERRORS.md、FEATURE_REQUESTS.md），或创建带有标题的文件。

记录格式

经验条目

追加到 .learnings/LEARNINGS.md：

每条保存的经验在记录时都要包含维护字段，即使它从未被提升。 使用 references/context-maintenance.md；明确标注未知信息。

## [LRN-YYYYMMDD-XXX] category

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

### Summary
One-line description of what was learned

### Details
Full context: what happened, what was wrong, what's correct

### Suggested Action
Specific fix or improvement to make

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

### Context Maintenance
- Decay-Type: reality | decision | dependency | relevance | unknown
- Decay-Rate: fast | medium | slow | durable | unknown (brief basis)
- Authority: source or unknown; Owner: known role or unknown
- Revalidation: method; invalidating triggers; when to check; unavailable-source behavior
- Validation: pending | verified | unresolved; Last-Validated: date or none; Evidence: checked source or none
- Disposition: unassessed | retain | revise | externalize | retire; Application: proposed | applied

---

错误条目

追加到 .learnings/ERRORS.md：

## [ERR-YYYYMMDD-XXX] skill_or_command_name

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

### Summary
Brief description of what failed

### Error

实际错误消息或输出

### Context
- Command/operation attempted
- Input or parameters used
- Environment details if relevant

### Suggested Fix
If identifiable, what might resolve this

### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file.ext
- See Also: ERR-20250110-001 (if recurring)

---

功能请求条目

追加到 .learnings/FEATURE_REQUESTS.md：

## [FEAT-YYYYMMDD-XXX] capability_name

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

### Requested Capability
What the user wanted to do

### User Context
Why they needed it, what problem they're solving

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built, what it might extend

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

---

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**: Brief description of what was done

其他状态值：

• in_progress - 正在处理
• wont_fix - 决定不处理（在 Resolution notes 中添加原因）
• promoted - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md
• promoted_to_skill - 已提取为可复用技能（参见“自动技能提取”）

提升为项目记忆

当某条经验适用范围广（而非一次性修复）时，将其提升为永久项目记忆。

何时提升

• 经验适用于多个文件／功能
• 所有贡献者（人类或 AI）都应了解的知识
• 能够防止反复出现的错误
• 记录项目特定约定

推广目标

目标	适用内容
CLAUDE.md	适用于所有 Claude 交互的项目事实、约定和注意事项
AGENTS.md	Agent 专属工作流、工具使用模式和自动化规则
.github/copilot-instructions.md	GitHub Copilot 的项目背景和约定

如何推广

主 Agent 使用学习条目或 learning-aggregator 差距报告执行此步骤。无需专用的 Agent 预设。

1. 检查资格和相关性。 应用下方的推广规则，阅读支持条目和相关文件，并检查现有指令。如果规则已经涵盖，记录现有目标，而不要重复添加。将过时证据或冲突规则标记出来，供人工审核；不要悄然忽略条目或覆盖现有指导。
2. 提炼出一到三句可操作且符合上下文的表述。选择适当的目标文件和章节，保留其组织结构以及任何需要在指令文件间同步的内容。推广修改的是指令，而不是应用代码。
3. 写入指令前，先展示拟议差异供人工批准。 仅应用获批的更改。在 Copilot 中，展示差异并在聊天中征求确认。技能编辑需要明确的范围审批，详见下文。
4. 推广后更新源条目： 设置 **Status**: promoted，记录 **Promoted**: <target files> 和 Promoted-Date: YYYY-MM-DD，并保留源 ID 和 Pattern-Key。不得将尚未应用的提案标记为已推广。推广审批不代表获准提交或发布。
5. 如果规则有明确的通过／失败条件，将评估候选项标记给 eval-creator。包括 Pattern-Key、规则、目标、源 ID、重复出现的证据、断言和验证方法。

如果差距报告提供了 tracker，则在交接中将其保留为 Pattern-Key。使用内联来源信息的项目也可以将 `` 放在规则上方；省略未知字段。Tracker 注释为可选项。

推广时维护上下文

在推广时完善捕获阶段的约定；如可用，使用 context-decay。将元数据保留在学习条目中，指令中只保留规则或检索指针。 审核不会改变重复出现情况或资格；参见 references/context-maintenance.md。 对于过时的技能指导，即使是首次学习，也要提出具体方案。 技能编辑／退役需要明确的范围审批，即使没有 context-decay 也不例外；参见同一参考文档。

推广示例

学习条目（冗长）：

项目使用 pnpm workspaces。尝试了 npm install，但失败了。 锁文件是 pnpm-lock.yaml。必须使用 pnpm install。

在 CLAUDE.md 中（精简）：

## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`

学习条目（冗长）：

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

在 AGENTS.md 中（可操作）：

## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`

检测重复模式

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

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

精简并加固信息流

使用此工作流，从 simplify-and-harden 技能中摄取重复模式，并将其转化为持久的提示词指导。

记录工作流

1. 从任务摘要中读取 simplify_and_harden.learning_loop.candidates。
2. 对于每个候选项，使用 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

这三项条件是此技能唯一的晋升门槛。Quick Reference 中关于自修复 Handoff 块的条目，以及聚合器技能（learning-aggregator、learning-aggregator-ci）都使用相同规则。

将晋升的规则写成简短的预防规则（说明编码前/编码时应做什么）， 而不是冗长的事件记录。

定期审查

在合适的阶段节点审查 .learnings/：

何时审查

• 开始新的重大任务之前
• 完成一项功能之后
• 在曾有相关经验记录的区域开展工作时
• 活跃开发期间每周审查

快速状态检查

# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority items
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: backend" .learnings/*.md

审查操作

• 解决已修复的事项
• 晋升适用的经验记录
• 链接相关条目
• 上报重复出现的问题
• 审查已保存的经验记录，包括一次性和未晋升的条目；当其 来源、决策、依赖或审查节点发生变化时进行审查。使用 references/context-maintenance.md 更新现有约定；如有 context-decay，则使用它。审查不算作重复出现的记录，也不构成 按时间移除条目的依据。

检测触发条件

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

更正（→ correction 类别的经验记录）：

• “不，这不对……”
• “实际上，应该是……”
• “你说错了……”
• “这已经过时了……”

功能请求（→ 功能请求）：

• “你还可以……吗？”
• “我希望你能……”
• “有没有办法……”
• “为什么不能……？”

知识缺口（→ knowledge_gap 类别的经验记录）：

• 用户提供了你不知道的信息
• 你引用的文档已过时
• API 的行为与你的理解不同

错误（→ 错误条目）：

• 命令返回非零退出码
• 出现异常或堆栈跟踪
• 输出或行为异常
• 超时或连接失败

优先级指南

优先级	使用时机
critical	阻断核心功能、存在数据丢失风险或安全问题
high	影响重大、影响常见工作流或问题重复出现
medium	影响中等，且存在变通方法
low	轻微不便、边缘情况或锦上添花的改进

区域标签

用于按代码库区域筛选经验记录：

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

最佳实践

1. 立即记录 - 问题刚发生后，相关背景信息最清晰
2. 描述具体 - 让后续 Agent 能快速理解
3. 包含复现步骤 - 错误尤其需要
4. 链接相关文件 - 便于修复
5. 提出具体修复方案 - 不要只写“调查”
6. 使用一致的类别 - 便于筛选
7. 谨慎晋升 - 应用晋升规则；如果复制的事实很快会过时，优先提供来源检索指引
8. 定期审查 - 过时的经验记录会失去价值

Gitignore 选项

将经验保留在本地（每位开发者各自保存）：

.learnings/

在仓库中跟踪经验（整个团队共享）： 不要添加到 .gitignore 中——经验将成为共享知识。

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

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

钩子集成

自动提醒是可选启用的。Claude Code、Codex CLI 和 Copilot 的事件与输出约定各不相同；请参阅 references/hooks-setup.md。Amp 按需加载技能，并使用单独的原生插件提供每轮提醒；请参阅 references/amp-setup.md。提醒不会写入经验，也不保证捕获经验。

自动提取技能

当一条经验足够有价值，值得转化为可复用技能时，请使用提供的辅助工具进行提取。

技能提取标准

符合以下任意条件的经验均可提取为技能：

标准	说明
反复出现	包含指向 2 个或更多类似问题的 See Also 链接
已验证	状态为 resolved，且修复有效
不明显	需要实际调试或调查才能发现
适用范围广	并非特定于某个项目；对不同代码库都有用
用户指定	用户说“将此保存为技能”或类似的话

提取工作流

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-name>/SKILL.md
2. 使用 assets/SKILL-TEMPLATE.md 中的模板
3. 遵循 Agent Skills 规范：
   • 使用包含 name 和 description 的 YAML frontmatter
   • 名称必须与文件夹名称一致
   • 技能文件夹内不得包含 README.md

提取检测触发条件

留意以下信号，判断某条经验是否应转化为技能：

在对话中：

• “将此保存为技能”
• “我总是遇到这个问题”
• “这对其他项目也会有用”
• “记住这个模式”

在经验条目中：

• 多个 See Also 链接（反复出现的问题）
• 高优先级且状态已解决
• 类别为 best_practice，且适用范围广
• 用户反馈称赞该解决方案

技能质量检查

提取前，请确认：

• 解决方案经过测试且有效
• 不依赖原始上下文也能清楚理解描述
• 代码示例完整自足
• 没有针对特定项目硬编码的值
• 符合技能命名约定（小写、使用连字符）

多 Agent 支持

无论使用哪种 Agent，在以下情况下都应进行自我改进：

1. 发现不明显的问题——解决方案并非一目了然
2. 纠正自己——最初的方法有误
3. 了解项目约定——发现未记录的模式
4. 遇到意外错误——尤其是诊断过程困难时
5. 找到更好的方法——改进最初的解决方案

Copilot Chat 集成

对于 Copilot 用户，可在相关提示词中添加以下内容：

完成此任务后，请评估是否应使用自我改进技能的格式，将经验记录到 .learnings/。

也可以使用快捷提示词：

• “将此记录到经验中”
• “根据此解决方案创建技能”
• “检查 .learnings/ 中是否有相关问题”