在AI编码任务中持续记录纠正…

适用于编码代理在工作过程中捕获学习、错误、用户纠正和功能请求，并定期提升为项目记忆或可复用技能，以实现持续改进。

适用场景

解决思路

1. 安装技能：运行 `gh skill install pskoett/pskoett-skills self-improvement`；仅 CI 执行时运行 `gh skill install pskoett/pskoett-skills self-improvement-ci`。
2. Agent Skills CLI 回退安装：运行 `npx skills add pskoett/pskoett-skills/skills/self-improvement` 或 `npx skills add pskoett/pskoett-skills/skills/self-improvement-ci`。
3. 将学习与错误记录到 markdown 文件以实现持续改进，供后续编码代理处理成修复，并把重要学习提升到项目记忆。
4. 与 self-healing 配对：self-healing 负责主动运行时恢复、诊断、修补、验证并写入 HEAL- 到 .learnings/HEALS.md；self-improvement 负责被动积累与提升，记录纠正、知识缺口、功能请求，并将重复 heal handoff 提升为永久记忆；两者共享 .learnings/ 但写入不同文件；验证纪律在 self-healing，提升逻辑在此技能。
5. 按 Quick Reference 映射执行：任务中主动失败需立即修复时改用 self-healing；过去失败但非主动修复时记录到 .learnings/ERRORS.md；用户纠正时记录到 .learnings/LEARNINGS.md 且 category 为 correction；用户想要缺失功能时记录到 .learnings/FEATURE_REQUESTS.md；API/外部工具失败时记录到 .learnings/ERRORS.md 并带集成细节；self-healing Handoff 满足提升规则时，将 Distilled Rule 提升到 CLAUDE.md、AGENTS.md 或新技能；知识过时时记录到 .learnings/LEARNINGS.md 且 category 为 knowledge_gap；找到更好方法时记录到 .learnings/LEARNINGS.md 且 category 为 best_practice；simplify/harden 重复模式时记录/更新 .learnings/LEARNINGS.md，Source: simplify-and-harden 并带稳定 Pattern-Key；类似已有条目时用 **See Also** 链接并考虑提升优先级；广泛适用学习时提升到 CLAUDE.md、AGENTS.md 和/或 .github/copilot-instructions.md；OpenClaw 工作区目标见 references/openclaw-integration.md。
6. 设置：若项目根目录没有 .learnings/，运行 `mkdir -p .learnings`。
7. 从 assets/ 复制文件模板（LEARNINGS.md、ERRORS.md、FEATURE_REQUESTS.md），或创建带标题的文件。
8. Learning Entry 格式：追加到 .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 一行描述、Details 完整上下文（发生什么、错在哪、正确是什么）、Suggested Action 具体修复或改进；Metadata 包含 Source conversation|error|user_feedback、Related Files path/to/file.ext、Tags tag1, tag2、See Also LRN-20250110-001、Pattern-Key simplify.dead_code|harden.input_validation（可选，用于重复模式跟踪）、Recurrence-Count 1（可选）、First-Seen 2025-01-15（可选）、Last-Seen 2025-01-15（可选）；以 --- 结束。
9. Error 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 失败简述、Error 实际错误消息或输出代码块、Context 尝试的命令/操作、输入或参数、相关环境细节、Suggested Fix 可识别时的解决方式；Metadata 包含 Reproducible yes|no|unknown、Related Files path/to/file.ext、See Also ERR-20250110-001；以 --- 结束。
10. Feature Request Entry 格式：追加到 .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 用户想做什么、User Context 为什么需要及解决什么问题、Complexity Estimate simple|medium|complex、Suggested Implementation 如何构建及扩展什么；Metadata 包含 Frequency first_time|recurring、Related Features existing_feature_name；以 --- 结束。
11. ID 生成：格式 `TYPE-YYYYMMDD-XXX`；TYPE 为 LRN（learning）、ERR（error）、FEAT（feature）；YYYYMMDD 为当前日期；XXX 为顺序号或随机 3 字符；例如 LRN-20250115-001、ERR-20250115-A3F、FEAT-20250115-002。
12. 解决条目：问题修复后把 `**Status**: pending` 改为 `**Status**: resolved`，并在 Metadata 后添加 Resolution 块：Resolved 时间、Commit/PR（如 abc123 或 #42）、Notes 简述做了什么。
13. 使用其他状态值：in_progress 表示正在处理；wont_fix 表示决定不处理（在 Resolution notes 加原因）；promoted 表示已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md；promoted_to_skill 表示已抽取为可复用技能（见 Automatic Skill Extraction）。
14. 提升到项目记忆：当学习广泛适用而非一次性修复时，提升为永久项目记忆；判据包括跨多个文件/功能适用、任何贡献者（人或 AI）都应知道、能防止重复错误、记录项目特定约定。
15. 提升目标分配：CLAUDE.md 放项目事实、约定、所有 Claude 交互的注意事项；AGENTS.md 放代理特定工作流、工具使用模式、自动化规则；.github/copilot-instructions.md 放 GitHub Copilot 的项目上下文和约定；OpenClaw 工作区目标（SOUL.md、TOOLS.md）见 references/openclaw-integration.md。
16. 执行提升步骤：1) 将学习提炼成简洁规则或事实；2) 添加到目标文件合适章节（必要时创建文件）；3) 更新原条目：`**Status**: pending` 改为 `**Status**: promoted`，并添加 `**Promoted**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`。
17. 提升示例：学习记录可写成详细版（如项目用 pnpm workspaces，尝试 npm install 失败，lock file 是 pnpm-lock.yaml，必须用 pnpm install），在 CLAUDE.md 中写成简洁规则（如 Build & Dependencies：Package manager: pnpm (not npm) - use `pnpm install`）；API 端点修改后必须重新生成 TypeScript client，否则运行时类型不匹配，在 AGENTS.md 中写成可执行步骤（1. 运行 `pnpm run generate:api`；2. 运行 `pnpm tsc --noEmit` 检查类型错误）。
18. 检测重复模式：先搜索 `grep -r "keyword" .learnings/`；用 `**See Also**: ERR-20250110-001` 链接条目；问题持续复现时提升优先级；考虑系统性修复：缺文档则提升到 CLAUDE.md 或 .github/copilot-instructions.md，缺自动化则添加到 AGENTS.md，架构问题则创建 tech debt ticket。
19. 接入 Simplify & Harden Feed 摄取流程：1) 从任务摘要读取 `simplify_and_harden.learning_loop.candidates`；2) 对每个候选使用 `pattern_key` 作为稳定去重键；3) 用 `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md` 搜索 .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。
20. 执行提升规则（System Prompt Feedback）：当且仅当 Recurrence-Count >= 3、至少在 2 个不同任务中出现、且发生在 30 天窗口内时，将重复模式提升到代理上下文/系统提示文件；提升目标为 CLAUDE.md、AGENTS.md、.github/copilot-instructions.md，适用时含 OpenClaw 工作区文件，见 references/openclaw-integration.md；将提升规则写成简短预防规则（编码前/编码中做什么），不要写长事件报告；该三条件规则是本技能的单一提升阈值，self-healing Handoff 的 Quick Reference 行和聚合技能（learning-aggregator、learning-aggregator-ci）都使用同一规则。
21. 周期性审查：在自然断点审查 .learnings/；时机包括开始新主要任务前、完成功能后、在有过往学习的区域工作时、活跃开发期间每周。
22. 快速状态检查：运行 `grep -h "Status\*\*: pending" .learnings/*.md | wc -l` 统计 pending 项；运行 `grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["` 列出 pending 高优先级项；运行 `grep -l "Area\*\*: backend" .learnings/*.md` 查找特定区域学习。
23. 审查动作：解决已修复项、提升适用学习、链接相关条目、升级重复问题。
24. 检测触发并记录：遇到纠正时记录为 learning 且 category 为 correction，信号如「No, that's not right...」「Actually, it should be...」「You're wrong about...」「That's outdated...」；遇到功能请求时记录为 feature request，信号如「Can you also...」「I wish you could...」「Is there a way to...」「Why can't you...」；遇到知识缺口时记录为 learning 且 category 为 knowledge_gap，信号包括用户提供你不知道的信息、引用的文档过时、API 行为与理解不符；遇到错误时记录到 error entry，信号包括命令非零退出码、异常或堆栈跟踪、意外输出或行为、超时或连接失败。
25. 分配优先级：critical 用于阻塞核心功能、数据丢失风险、安全问题；high 用于重大影响、影响常见工作流、重复问题；medium 用于中等影响、存在 workaround；low 用于轻微不便、边缘情况、nice-to-have。
26. 使用 Area 标签：frontend 用于 UI、组件、客户端代码；backend 用于 API、服务、服务端代码；infra 用于 CI/CD、部署、Docker、云；tests 用于测试文件、测试工具、覆盖率；docs 用于文档、注释、README；config 用于配置文件、环境、设置。
27. 遵循最佳实践：1) 立即记录，问题后上下文最新鲜；2) 写得具体，未来代理能快速理解；3) 包含复现步骤，尤其是错误；4) 链接相关文件，便于修复；5) 建议具体修复，不要只写「investigate」；6) 使用一致分类，便于过滤；7) 积极提升，若有疑问就加入 CLAUDE.md 或 .github/copilot-instructions.md；8) 定期审查，过时学习会失去价值。
28. 配置 Gitignore：若保持学习仅本地（每位开发者），把 `.learnings/` 加入 .gitignore；若要在仓库跟踪团队共享知识，不要加入 .gitignore；混合方式可写 `.learnings/*.md` 和 `!.learnings/.gitkeep`。
29. Hook Integration：通过代理 hooks 启用自动提醒，这是 opt-in，必须显式配置；同一对脚本可在 Claude Code 和 Codex CLI 工作（两者通过 stdin 传 JSON，并接受相同 additionalContext 输出形状）；Copilot hooks 可记录但不能注入上下文，因此 Copilot 使用 instructions-file 通道；完整各代理设置见 references/hooks-setup.md。
30. Claude Code quick setup：在项目创建 `.claude/settings.json`，命令路径必须指向技能实际安装位置：`gh skill install` / `npx skills add` 时为 `.claude/skills/self-improvement/`，若仓库 vendored 到项目则为 `skills/self-improvement/`；相对路径从项目根解析；配置 UserPromptSubmit hook 运行 `${CLAUDE_PROJECT_DIR}/.claude/skills/self-improvement/scripts/activator.sh`；这会在每个提示后注入学习评估提醒，约 50-100 tokens 开销。
31. Claude Code full setup（带错误检测）：在 UserPromptSubmit hook 之外，添加 PostToolUse，`matcher` 为 `Bash`，hook 命令运行 `${CLAUDE_PROJECT_DIR}/.claude/skills/self-improvement/scripts/error-detector.sh`；hooks 通过 stdin 接收事件 JSON；错误检测器解析该 JSON 的 `tool_response`，并把提醒作为 `additionalContext` JSON 输出返回，这是 PostToolUse 输出到达模型所必需的。
32. 可用 Hook 脚本：`scripts/activator.sh` 用于 UserPromptSubmit（Claude Code、Codex），提醒任务后评估学习（该事件在两个代理上 plain stdout 会加入上下文）；`scripts/error-detector.sh` 用于 PostToolUse（Claude Code、Codex）、postToolUse（Copilot，仅记录），解析 stdin JSON payload 中的错误模式，覆盖三种代理 payload 形状，并发出 `additionalContext` 提醒；详细配置和故障排除见 references/hooks-setup.md。
33. 自动技能提取：当学习足够有价值可成为可复用技能时，用提供的 helper 提取。
34. 技能提取标准（满足任一）：Recurring 有 `See Also` 链接到 2+ 类似问题；Verified 状态为 resolved 且有可用修复；Non-obvious 需要实际调试/调查才能发现；Broadly applicable 非项目特定且跨代码库有用；User-flagged 用户说「save this as a skill」或类似话。
35. 执行提取工作流：1) 识别候选；2) 运行 helper 或手动创建：`./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run`、`./skills/self-improvement/scripts/extract-skill.sh skill-name`；3) 自定义 SKILL.md，填入学习内容模板；4) 更新 learning：状态改为 `promoted_to_skill`，添加 `Skill-Path`；5) 验证：在新会话读取技能，确保自包含。
36. 手动提取：1) 创建 `skills/<skill-name>/SKILL.md`；2) 使用 `assets/SKILL-TEMPLATE.md` 模板；3) 遵循 Agent Skills spec：YAML frontmatter 含 `name` 和 `description`、name 必须匹配文件夹名、技能文件夹内不要有 README.md。
37. 提取检测触发：对话中出现「Save this as a skill」「I keep running into this」「This would be useful for other projects」「Remember this pattern」；learning 条目中出现多个 `See Also` 链接、高优先级 + resolved 状态、category 为 `best_practice` 且广泛适用、用户反馈称赞解决方案。
38. 技能质量门禁：提取前检查：解决方案已测试可用；描述无需原始上下文也清晰；代码示例自包含；无项目特定硬编码值；遵循技能命名约定（小写、连字符）。
39. 多代理支持：Claude Code 用 hooks（UserPromptSubmit、PostToolUse）激活，设置 `.claude/settings.json`，通过 hook 脚本自动检测；Codex CLI 用 hooks（UserPromptSubmit、PostToolUse，实验性，需在 `config.toml` 中 `codex_hooks = true`），设置 `<repo>/.codex/hooks.json` 或 `~/.codex/hooks.json`，同一脚本、同一 payload/output 形状，hook 不可用时把 self-improvement 指南加入 `AGENTS.md`；GitHub Copilot 用 instructions file 激活（`.github/hooks/*.json` 存在但 prompt/tool 事件输出被忽略，只能记录不能注入上下文），在 `.github/copilot-instructions.md` 加入 Self-Improvement 章节，步骤包括用 self-improvement 格式记录到 `.learnings/`、用 See Also 链接、把高价值学习提升为技能，并在聊天中问「Should I log this as a learning?」，检测为会话结束时人工审查；OpenClaw 可选，设置/提升目标/混合使用见 references/openclaw-integration.md。
40. 代理无关指南：发现非显而易见内容、纠正自己、学习项目约定、遇到意外错误（尤其诊断困难）、找到更好方法时，都应用 self-improvement。
41. Copilot Chat 集成：在相关提示中加入「After completing this task, evaluate if any learnings should be logged to `.learnings/` using the self-improvement skill format.」；或使用快捷提示「Log this to learnings」「Create a skill from this solution」「Check .learnings/ for related issues」。

适用边界 · 注意事项

• 任务中发生主动运行时失败、代理需要立即应用并验证修复时，改用 self-healing，而不是本技能。
• 仅 CI/headless 的学习捕获场景，改用 self-improvement-ci。
• GitHub Copilot 的 hooks 输出不会注入 prompt/tool 事件上下文，不能依赖它们做自动提醒注入，只能记录并配合 instructions-file 通道。