learning-from-failures

Learning From Failures

目标

把“我又犯了同类错”、用户给出的有效纠偏，以及任务中暴露出的更优实践，转成可触发、可验证、可复用的机制改进。 这个 skill 不负责泛泛道歉，也不把一次性坏例子堆进规则；它负责找出失败、纠偏或高质量反馈背后的通用模式，并把必要改进落到会自动触发的位置。

触发与节奏

用户指出重复错误、严重漂移、没有从教训中学习时，先暂停继续实现。 除非用户明确要求继续改代码，否则先完成失败复盘和机制落点判断。

用户用反讽、夸张表扬、连续点名多个相似坏味道，或明显是在表达“这个问题已经说过很多次”时，也必须按重复失败处理。不要只修当前行；先判断已有规则为什么没有自动挡住，是否需要补强 skill description、执行步骤、治理脚本或常驻索引。

用户给出更优设计、删减路径、职责收敛方式、验证策略或命名/抽象纠偏时，也要判断是否值得学习。 这类学习不一定要立即中断实现；如果用户要求继续交付，可以在当前最小修复完成后，把可复用原则补进合适的 skill、规则或治理入口。

必须避免：

• 继续沿着刚才的错误方向补丁式修改；
• 只说“我记住了”但不落盘；
• 把具体坏例子原样塞进 skill，制造噪音；
• 把一次用户建议机械复制成规则，而没有提炼出跨场景原则；
• 用新 wrapper、getter、alias、proxy 掩盖同一个问题；
• 为了显得有行动，创建无法自动触发的普通文档。

什么值得学习

出现下面任一情况，就要做一次机制落点判断：

• 用户给出比当前实现更少、更直接、更内聚的方案；
• 用户指出某个抽象、参数、wrapper、alias、fallback 或兼容层没有必要；
• 用户把问题上升到通用原则，例如 owner、生命周期、单一路径、删除重复暴露、验证入口；
• 某次验证、review 或治理检查暴露出流程没有自动挡住问题；
• 任务推进中发现已有 skill/规则描述太窄，导致本该触发的学习没有触发。

不值得落盘的内容：

• 只适用于某个文件、某个变量名、某次情绪表达的细节；
• 已经被现有 skill 明确覆盖，且这次没有暴露触发失败；
• 没有可执行判断标准的口号。

五步复盘 / 沉淀

1. 定位重复模式 用一句话说清这不是哪个单点错，而是哪类模式反复发生，或用户纠偏揭示了哪类更优通用模式。 例：把“删除重复暴露”误做成 getter alias，公共入口没有真正减少。

   用户指出一个具体坏味道时，必须先把它翻译成结构性模式，再扫描同一文件、同一 owner、同一责任链里的同类问题。 不要只改用户点名的那一行；除非扫描后确认没有同类问题，否则当前修复不算完成。

2. 抽象层级校准 对同一个失败至少看三层：

   • 具体层：这次错在什么文件、判断、方案或动作。
   • 方法层：这反映出哪类分析方法缺口，例如停止追问、没有递归审计、没有校准 owner、把证据误当结论。
   • 原则层：它对应哪条稳定工程原则，例如 deletion-first、single-domain-owner、cqs-pure-read、no-compatibility-by-default。

   落盘时优先选择“方法层”或“方法层 + 原则层”的表达。不要只记录本次具体坏例子，也不要抽象到无法执行的哲学口号。合适的规则应能指导下一次相似但不完全相同的问题。

3. 找失效的现有规则 搜索 AGENTS.md 和相关 .agents/skills/*/SKILL.md。 判断是：

   • 已有规则没触发；
   • 已有规则太抽象；
   • 规则存在但缺少可执行检查；
   • 根本没有对应 skill。

   如果同类错误在已有记录后再次发生，不能只重复原规则或补一句口号；必须升级触发层级或执行检查，例如从普通 skill 补到 AGENTS.md 常驻约束、从原则描述补成可执行链路检查，或从人工提醒补成治理脚本。

4. 提炼通用原则 只写能跨场景复用的原则。 不写情绪化措辞、不写项目一次性细节、不写“下次小心”，也不把用户原话原样变成规则。 提炼后做一次“迁移测试”：把当前具体名词替换成另一个模块、owner、兼容层或验证场景时，规则是否仍然成立；如果不成立，说明太具体；如果成立但不知道下一步怎么做，说明太抽象。

5. 选择落点

   • 每轮都必须知道：写 AGENTS.md，保持短句。
   • 某类场景需要：写已有 skill 或新 skill，并确保 description 能触发。
   • 能自动检查：更新治理脚本或说明为什么暂不适合脚本。
   • 只是人类背景：才写普通文档。

6. 学习闭环自检 落盘后必须反查这条教训能否在下次自动生效，而不是只确认文字已写入：

   • 常驻层：如果每轮都必须知道，是否在 AGENTS.md；如果没有，原因是否成立。
   • 触发层：如果是按需规则，相关 skill 的 description 是否覆盖用户真实说法、代码触达面和任务类型。
   • 执行层：skill body 是否给出可操作检查，而不是抽象口号。
   • 验证层：能否用治理脚本、测试、review checklist 或明确的不适用说明兜底。

   如果用户在一次机制改进后继续指出“你还是没学到”“这仍然是特判/双路径/补丁”，必须先复审上一次学习落点是否缺少触发、执行或验证层，再继续改代码。

7. 回到当前任务 机制改进落地后，再修正当前工作中的具体错误。 不能把“新增规则”当成替代当前修复。

落盘规则

• 修改 AGENTS.md、skill、命令或治理系统时，必须联动 nextclaw-agent-instructions-governance。
• 如果失败来自代码实现、owner、fallback、验证或目录治理，仍要联动对应专项 skill；本 skill 只负责“教训如何进入机制”。
• 如果学习来自用户提供的更优设计，优先更新最能在下次相似场景自动触发的设计/实现/验证 skill；不要只写到当前任务文档。
• 如果失败来自缺少验证，优先更新验证 workflow 或治理脚本，而不是只写一句流程建议。
• 如果失败来自目标漂移，优先更新目标锚点、计划文档或相关 campaign skill。

输出要求

使用本 skill 后，回复或工作笔记里至少说明：

• 学习来源是什么：失败、用户纠偏、更优设计，还是验证/治理暴露的缺口；
• 背后的通用模式是什么；
• 本次选择了哪个抽象层级落盘，为什么不是更具体或更抽象；
• 现有规则为什么没挡住，或为什么原 description 不足以触发；
• 本次把教训落到了哪里；
• 为什么这个落点会自动触发；
• 学习闭环自检结论是什么：常驻层、触发层、执行层、验证层分别是否覆盖；
• 是否还需要修正当前代码/文档里的具体错误。

不适用

以下情况不要使用本 skill：

• 单纯解释一个普通 bug，且没有暴露重复失败或机制缺口；
• 用户只要快速修一个明确小问题；
• 用户建议只影响当前一次实现，无法提炼出通用原则；
• 已有专项 skill 已经完整覆盖，且不需要新增机制。