自我提升技能

将学习和错误记录到 Markdown 文件中，以便持续改进。编码代理稍后可以将其处理成修复方案，重要的学习内容会被提升到项目记忆中。

快速参考

设置

创建.learnings/目录于项目根目录（如果不存在）：

mkdir -p .learnings

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

日志格式

学习条目

追加至.learnings/LEARNINGS.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)

---

错误条目

追加至.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

• 类型：LRN（学习），ERR（错误），FEAT（功能）
• YYYYMMDD：当前日期
• XXX：顺序号或随机3个字符（例如，001,A7B)

示例：LRN-20250115-001,ERR-20250115-A3F,FEAT-20250115-002

解决条目

当问题被修复时，更新条目：

1. 将**状态**：待处理改为**状态**：已解决
2. 在元数据后添加解决区块：

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done

其他状态值：

• 进行中- 正在积极处理中
• 不予修复- 决定不处理（在解决说明中添加原因）
• 已提升- 已提升至 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升至项目记忆

当一项学习成果具有广泛适用性（而非一次性解决方案）时，将其提升为永久性的项目记忆。

何时提升

• 学习成果适用于多个文件/功能
• 任何贡献者（人类或AI）都应了解的知识
• 能防止错误重复发生
• 记录项目特有的约定规范

提升目标

如何提升

1. 提炼将学习成果提炼为简洁的规则或事实
2. 添加移至目标文件的相应部分（如需要则创建文件）
3. 更新原始条目：
   • 更改**状态**：待定→**状态**：已提升
   • 添加**已提升至**：CLAUDE.md、AGENTS.md、或.github/copilot-instructions.md

提升示例

学习（详细版）：

项目使用 pnpm 工作区。尝试了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 "关键词" .learnings/
2. 链接条目：添加**另请参见**：ERR-20250110-001在元数据中
3. 提升优先级如果问题持续出现
4. 考虑系统性修复：重复出现的问题通常表明：
   • 缺少文档（→ 提升至 CLAUDE.md 或 .github/copilot-instructions.md）
   • 缺少自动化（→ 添加到 AGENTS.md）
   • 架构问题（→ 创建技术债务工单）

定期审查

复习.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

复习行动项

• 解决已修复的事项
• 推广适用的学习成果
• 关联相关条目
• 上报反复出现的问题

检测触发点

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

更正(→ 归类为更正类学习项)：

• "不，这样不对……"
• "实际上，应该是……"
• "关于……你搞错了"
• “这已经过时了...”

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

• “你还能不能...”
• “我希望你能...”
• “有没有办法...”
• “为什么你不能...”

知识缺口（→ 学习时遇到知识缺口类别）：

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

错误（→ 错误条目）：

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

优先级指南

区域标签

用于按代码库区域筛选学习内容：

最佳实践

1. 立即记录- 问题刚发生时的上下文最清晰
2. 具体明确- 便于后续人员快速理解
3. 包含重现步骤- 特别是对于错误
4. 关联相关文件- 便于修复
5. 建议具体修复方案- 不仅仅是"调查"
6. 使用一致的分类- 便于筛选
7. 积极推广- 如有疑问，添加到 CLAUDE.md 或 .github/copilot-instructions.md
8. 定期回顾- 过时的经验会失去价值

Gitignore 选项

保持经验本地化（按开发者）：

.learnings/

在仓库中跟踪经验（团队范围内）： 不要添加到 .gitignore 文件中 - 学习成果应成为共享知识。

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

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

钩子集成

通过代理钩子启用自动提醒。此为选择性加入- 您必须明确配置钩子。

快速设置（Claude Code / Codex）

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

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

这会在每次提示后注入学习评估提醒（约50-100个令牌的开销）。

完整设置（含错误检测）

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

可用钩子脚本

请参阅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. 更新学习记录：将状态设置为已晋升为技能，添加技能路径
5. 验证：在新会话中阅读技能以确保其自包含性

手动提取

若偏好手动创建：

1. 创建skills/<技能名称>/SKILL.md
2. 使用模板assets/SKILL-TEMPLATE.md
3. 遵循Agent Skills 规范：
   • YAML 前置元数据，包含名称和描述
   • 名称必须与文件夹名称匹配
   • 技能文件夹内无 README.md 文件

提取检测触发器

留意以下信号，表明某个学习内容应转化为技能：

在对话中：

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

在学习条目中：

• 多个“另请参阅”链接（反复出现的问题）
• 高优先级 + 已解决状态
• 类别：best_practice具有广泛适用性
• 用户反馈赞扬该解决方案

技能质量门控

提取前需验证：

• 解决方案经过测试且可运行
• 描述清晰且不依赖原始上下文
• 代码示例自包含
• 无项目特定的硬编码值
• 遵循技能命名规范（小写字母，连字符）

多智能体支持

此技能适用于不同AI编码智能体，并支持智能体特定的激活方式。

Claude Code

激活：挂钩（UserPromptSubmit, PostToolUse）设置：.claude/settings.json包含挂钩配置检测：通过挂钩脚本自动执行

Codex CLI

激活：挂钩（与Claude Code模式相同）设置：.codex/settings.json包含钩子配置检测：通过钩子脚本自动进行

GitHub Copilot

激活：手动（不支持钩子）设置：添加到.github/copilot-instructions.md：

## Self-Improvement

After solving non-obvious issues, consider logging to `.learnings/`:
1. Use format from self-improvement skill
2. Link related entries with See Also
3. Promote high-value learnings to skills

Ask in chat: "Should I log this as a learning?"

检测：会话结束时手动审查

与代理无关的指导

无论使用何种代理，请在以下情况应用自我改进：

1. 发现不显而易见的事物- 解决方案并非立即得出
2. 自我纠正- 初始方法是错误的
3. 学习项目惯例- 发现了未记录的规律
4. 遇到意外错误- 尤其是在诊断困难的情况下
5. 寻找更好的方法- 在你原有解决方案的基础上进行改进

Copilot 聊天集成

对于 Copilot 用户，在相关时请将此内容添加到你的提示中：

完成此任务后，评估是否有任何学习内容应记录到.learnings/使用自我提升技能格式。

或使用快速提示：

• "将此记录到学习内容中"
• "基于此解决方案创建技能"
• "检查 .learnings/ 中的相关问题"