self-improvement

自我改进技能

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

快速参考

情况	操作
命令／操作失败	记录到 .learnings/ERRORS.md
用户纠正了你	使用类别 correction 记录到 .learnings/LEARNINGS.md
用户想要缺失的功能	记录到 .learnings/FEATURE_REQUESTS.md
API／外部工具失败	将集成详情记录到 .learnings/ERRORS.md
知识已过时	使用类别 knowledge_gap 记录到 .learnings/LEARNINGS.md
找到更好的方法	使用类别 best_practice 记录到 .learnings/LEARNINGS.md
与现有条目相似	使用 **See Also** 添加链接，并考虑提高优先级
普遍适用的经验	提升到 CLAUDE.md、AGENTS.md 和／或 .github/copilot-instructions.md
工作流改进	提升到 AGENTS.md（机器人工作区）
工具注意事项	提升到 TOOLS.md（机器人工作区）
行为模式	提升到 SOUL.md（机器人工作区）

设置

如果项目根目录中不存在 .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

• 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 - 决定不予处理（在解决方案说明中添加原因）
• promoted - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升到项目记忆

当某条经验具有普遍适用性（并非一次性修复）时，将其提升到永久项目记忆中。

何时提升

• 经验适用于多个文件／功能
• 任何贡献者（人类或 AI）都应该了解的知识
• 可避免反复出现的错误
• 记录项目专属约定

提升目标

目标	适用内容
CLAUDE.md	项目信息、约定，以及适用于所有 Claude 交互的注意事项
AGENTS.md	Agent 专属工作流、工具使用模式、自动化规则
.github/copilot-instructions.md	GitHub Copilot 的项目背景和约定
SOUL.md	行为准则、沟通风格、原则（机器人）
TOOLS.md	工具功能、使用模式、集成注意事项（机器人）

如何提升

1. 提炼：将经验整理成简洁的规则或事实
2. 添加：添加到目标文件中的相应部分（如有需要则创建文件）
3. 更新原始条目：
   • 将 **Status**: pending 改为 **Status**: promoted
   • 添加 **Promoted**: 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 "keyword" .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

审查操作

• 解决已修复的事项
• 推广适用的经验
• 关联相关条目
• 升级反复出现的问题

检测触发条件

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

更正（→ 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. 积极推广 - 不确定时，将内容添加到 CLAUDE.md 或 .github/copilot-instructions.md
8. 定期审查 - 过时的经验会失去价值

Gitignore 选项

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

.learnings/

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

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

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

Hook 集成

通过 Agent Hook 启用自动提醒。此功能为选择加入 - 必须显式配置 Hook。

快速设置（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"
      }]
    }]
  }
}

可用的 Hook 脚本

脚本	Hook 类型	用途
scripts/activator.sh	UserPromptSubmit	提醒在任务完成后评估经验
scripts/error-detector.sh	PostToolUse (Bash)	在命令出错时触发

详细配置和故障排除请参阅 references/hooks-setup.md。

自动提取 Skill

当一条经验足以成为可复用的 Skill 时，使用提供的辅助工具将其提取出来。

技能提取标准

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

标准	说明
重复出现	包含指向 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 规范：
   • YAML frontmatter 中包含 name 和 description
   • 名称必须与文件夹名称一致
   • 技能文件夹中不得包含 README.md

提取检测触发条件

留意以下信号，判断某项经验是否应成为技能：

在对话中：

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

在经验记录中：

• 多个 See Also 链接（重复出现的问题）
• 高优先级且状态为 resolved
• 类别为 best_practice，且适用范围广
• 用户对解决方案给予好评

技能质量检查

提取前，请确认：

• 解决方案经过测试且有效
• 无需原始上下文也能清楚理解描述
• 代码示例自包含
• 不包含项目专属的硬编码值
• 遵循技能命名约定（小写字母、连字符）

多 Agent 支持

此技能支持不同的 AI 编码 Agent，并可通过针对 Agent 的方式激活。

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?"

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

Bot

激活方式：工作区注入 + Agent 间消息传递 设置：在 ~/.bot/bot.json 中配置工作区路径 检测：通过会话工具和工作区文件（AGENTS.md、SOUL.md、TOOLS.md）检测

Bot 使用基于工作区的模式，并注入提示词文件。详细设置请参见 references/bot-integration.md。

不依赖特定 Agent 的指导

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

1. 发现不明显的内容——无法立即想到解决方案
2. 纠正自己的错误——最初采用的方法有误
3. 了解项目约定——发现了未记录的模式
4. 遇到意外错误——尤其是难以诊断的错误
5. 找到更好的方法——改进了原有解决方案

Copilot Chat 集成

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

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

或者使用快捷提示词：

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

Bot 集成

Bot 使用基于工作区的提示词注入，并通过专用文件处理不同方面的内容。

工作区结构

~/bot/                    # Default workspace (configurable)
├── AGENTS.md              # Multi-agent workflows, delegation patterns
├── SOUL.md                # Behavioral guidelines, communication style
├── TOOLS.md               # Tool capabilities, MCP integrations
└── sessions/              # Session transcripts (auto-managed)

Bot 推广目标

学习类型	推广至	示例
Agent 协作	AGENTS.md	“将文件搜索委派给探索 Agent”
沟通风格	SOUL.md	“表达简洁，避免免责声明”
工具注意事项	TOOLS.md	“MCP 服务 X 需要刷新身份验证”
项目事实	CLAUDE.md	标准项目约定

Agent 间学习

Bot 支持基于会话的通信：

• sessions_list - 查看活跃/最近的会话
• sessions_history - 阅读其他会话的对话记录
• sessions_send - 向其他会话发送消息

混合配置（Claude Code + Bot）

同时使用两者时：

1. 保留 .learnings/，用于项目特定的学习内容
2. 使用 Bot 工作区文件存放跨项目模式
3. 将高价值的学习内容同步到两个系统

请参阅 references/bot-integration.md，了解完整的配置、推广格式和故障排查方法。