AI 协作错题本 · AI Collaboration Mistake-Log

让 AI 助手主动反思、迭代式优化协作质量的轻量机制
_{不是「列规则」，是「建反馈循环」}

_{A lightweight framework that makes your AI assistant reflect on its own mistakes — and stop repeating them.}

_{Works with Claude · Cursor · Gemini · ChatGPT · 任何能读 Markdown 规则的 AI 助手}

_{🌏 Docs are in Chinese. Fastest way to read them? Ask your AI to summarize — which is, quite literally, what this repo is about.}

🤖 AI 用户：直接读 AGENTS.md，一个文件包含完整协议 + 错题本，无需跨文件跳转。
_{AI assistants: fetch AGENTS.md directly — all content in one file.}

📖 是什么 • ⚠️ 痛点 • 🏗 架构 • 🔄 v3 更新 • 🚀 开始用 • 📜 协作协议 • 📓 错题本

这是什么

跟 AI 协作久了你会发现：AI 经常犯同一种错，纠正成本极高，规则越列越多但 AI 选择性遵守。

这是一套已经跑了几个月的协作机制，核心思想：

把 AI 协作当工程问题做反馈循环，不当玄学碰运气。

它由三份文档组成——一份 协作协议（AI 该怎么和你配合）+ 一份 错题本（AI 犯错时主动记录、复发 3 次升级为新协议）+ 一份 CLAUDE.md（自动加载层，触发上面两份的读取）。

v3 更新了什么

这个仓库的卖点是"机制自我迭代"——每个版本都是迭代真实发生的证据。v3 的主线是给机制装上"自动传感器"：

1. ⭐ 错题本巡检员（v3 旗舰）：派一个独立 agent 定期扫会话日志，主动补录"发生了但没记进错题本"的失误——正面进攻 v1/v2 都坦承的死穴"AI 经常忘记主动记"。机制从「全手动」推进到「半自动」
2. 量化账本：让"这套机制到底有没有用"变得可追踪——每次巡检记一行指标（自查拦截率↑ / 🔴占比↓ / 复发↓ = 系统在变强），配套"单周样本小不下结论"的纪律
3. 新增规则 17：「开启创意模式」= 强发散，先碰想法再出 demo——由"用问卷式收窄替用户预选安全答案"那条错题长出来
4. 新增 3 个案例（Day 22-24）——含一条所有 AI 用户都该警惕的 🔴「把 model 名/API/版本这类"会随时间漂移的事实"用训练记忆当事实，还标"已验证"」

诚实彩蛋：巡检员没有自吹"全自动了"——它把传感器的盲区（会话搜索工具掉线、空窗期不能误判归档）如实写进账本。连"度量机制有没有用"这件事都在守"事实 vs 推测"的纪律。

v1 → v2 → v3 的完整进化故事见 CHANGELOG.md。

你大概率经历过这些瞬间

这套机制不能让 AI 不犯错，但能让重复同类错的概率降下来 + 纠正成本随时间下降。

核心创新（8 个）

跟 GitHub 上常见的 awesome-cursor-rules 类项目比，那些是列规则，这个是反馈循环机制：

1. 「沉默错误」概念——专盯"用户不追问就发现不了"的错，不是泛泛防 AI 出错
2. 思维根因 vs 知识根因——不写"下次注意 X"，深挖"哪一步思维方式错了"
3. 「事不过三」升级阈值——同一根因复发 3 次才升级为硬规则，防规则膨胀（v2 里它第一次完整跑通）
4. 三层架构：观察层 ↔ 规则层 ↔ 自动加载层，闭环升级
5. 「动作 ≠ 结果」反射——AI 说"已 X"必须对应真实工具调用
6. 规则退役机制（v2 新增）——与升级对称的"减法"：根因休眠 → 规则降级。只增不减的规则体系必然膨胀
7. 核心卡 + 意图路由表（v2 新增）——高频反射常驻上下文，长文档按需深读，治"读了规则不用规则"
8. 巡检员 + 量化账本（v3 新增）——一个 agent 定期扫日志补录漏记的失误，并量化"这套机制到底有没有用"。机制从"全手动"推进到"半自动"

三层架构（v3）

┌──────────────────────────────────────────────┐
│  CLAUDE.md (自动加载层)                       │
│  内嵌「核心卡」：30 秒自检 + 17 条规则速查      │
│  + 意图路由表（按任务类型决定深读什么）         │
├──────────────────────────────────────────────┤
│  PROTOCOL.md (规则层)                        │
│  17 条协作规则——按路由表对应规则按需深读        │
├──────────────────────────────────────────────┤
│  MISTAKE-LOG.md (观察层，v2 起内部分两档)      │
│  活跃层：根因索引 + 聚类视图（开工扫这个）       │
│  归档层：完整推理路径（复盘才读）               │
│  ↑ AI 每次犯错主动追加                         │
│  ↑ 同根因 ≥ 3 次 → 升级到规则层                │
│  ↓ 根因休眠 2 次回顾 → 规则退役降级             │
└──────────────────────────────────────────────┘
        ▲
        │  v3 新增：巡检员 agent（半自动传感器）
        └─ 定期扫会话日志 → 补录漏记的失误 → 记量化账本

为什么需要三层：

• 单层（只有 CLAUDE.md）：规则爆炸、AI 选择性遵守
• 双层（CLAUDE.md + 规则）：规则不变，无法吸取新教训
• 三层：错题本是观察池，规则是稳定提炼，CLAUDE.md 是触发器——形成闭环
• v2 教训：三层闭环只解决"怎么学新教训"，不解决"学多了怎么办"——所以补了分层精炼 + 退役机制 + 核心卡，给系统装上"减"的能力
• v3 教训：闭环还有个洞——"AI 忘了记，错误就没进观察池"。所以加了巡检员当"自动传感器"定期补录，并用量化账本盯住机制本身有没有在变强

冷启动指南

第一周：只做"记"

不要一上来就写一堆规则。AI 每犯一个错你主动指出 + 让 AI 自己分析根因写进 MISTAKE-LOG.md。目标：攒 5-8 条错题，看 AI 经常犯哪几类错。

第一个月：开始"升级"

翻一遍错题本，找复发的根因。同一根因 ≥ 3 次 → 升级为 PROTOCOL.md 硬规则。目标：建立你自己的协作协议（5-10 条）。

第三个月起：定期回顾

每 2 周一次"错题本健康检查"：同根因复发间隔是不是在拉长？🔴 占比有没有下降？过时规则要删掉。目标：把机制本身也当作可优化对象。

真实案例预览

错题本里 14 个高代表性案例（脱敏后开源版）：

每条都包含：现象 → 真相 → 错误推理路径 → 思维根因 → 预防规则。

仓库内容

适合谁

• 跟 AI 协作做正经活的人：PM、研发、设计师、写作者、研究者……
• 觉得 AI 经常"犯傻"但又必须用它的人
• 看不上"列 100 条规则"那种 .cursorrules 模板的人
• 想沉淀自己跟 AI 协作方法论的人

它的局限

❌ 不能让 AI 不犯错（即使升级硬规则后，本机制案例显示规则 7 对应根因仍累计复发 15 次——纯文字规则有上限） ⚠️ 半自动维护（v3 的巡检员把它从"全手动"推到"半自动"，但传感器有盲区，仍需你主动指出错误） ❌ 不能跨工具直接迁移（每个 AI 工具的"读规则"行为不一样，需要适配）

✅ 能显著降低同类错误反复出现的频率 ✅ 能让你的纠正成本随时间下降 ✅ 能让协作方法论变得可见、可分享、可迭代

怎么贡献

欢迎：

• Issue：你跟 AI 协作时遇到的"沉默错误"案例
• PR：补充新的错题本案例（脱敏后）、修订规则、增加冷启动指南细节
• 讨论：你自己的协作机制对比

唯一要求：新增的错题条目必须包含「思维根因」和「预防规则」两节——不要只发"AI 又错了"的吐槽。

它是怎么来的

作者是 AI 产品经理（独立做事），编程小白，每天用 Claude Code / Cursor 协作 8+ 小时。跑了几个月发现 AI 同一类错反复出现——于是开始记错题本。攒到 30+ 条后发现"事不过三"是个好阈值。

机制本身也在持续迭代——v1 发布两周后机制自己就长出了 5 条新规则和 3 个新机制，见 CHANGELOG。

License

MIT —— 随便用、随便改、欢迎在你的项目里挂出处。

_{这个仓库本身就在用错题本机制持续迭代。
如果你看到 README 里有让你疑惑的地方，那可能就是下一条错题。}