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.}

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

这是什么

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

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

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

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

v2 更新了什么

这个仓库的卖点是"机制自我迭代"——v2 就是迭代真实发生的证据：

1. "事不过三"升级机制第一次完整跑通：根因「完工验证不彻底」复发 5 次后正式升级为规则 16，不再是设计稿
2. 机制自己长胖了，被同一套方法修好：错题本 800+ 行 → 分层精炼到约 150 行 + 根因聚类视图 + 规则退役机制（升级加规则、退役减规则，加减对称）
3. 自动加载层升级为"核心卡 + 意图路由表"：开工不再全文读两个长文件，按任务类型决定深读什么
4. 新增规则 12-16 + 5 个新案例——含一条所有 AI 用户都该警惕的 🔴「编造工具输出」

完整故事见 CHANGELOG.md。

你大概率经历过这些瞬间

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

核心创新（7 个）

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

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

三层架构（v2）

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

为什么需要三层：

• 单层（只有 CLAUDE.md）：规则爆炸、AI 选择性遵守
• 双层（CLAUDE.md + 规则）：规则不变，无法吸取新教训
• 三层：错题本是观察池，规则是稳定提炼，CLAUDE.md 是触发器——形成闭环
• v2 教训：三层闭环只解决"怎么学新教训"，不解决"学多了怎么办"——所以补了分层精炼 + 退役机制 + 核心卡，给系统装上"减"的能力

冷启动指南

第一周：只做"记"

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

第一个月：开始"升级"

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

第三个月起：定期回顾

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

真实案例预览

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

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

仓库内容

适合谁

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

它的局限

❌ 不能让 AI 不犯错（即使升级硬规则后，本机制案例显示规则 7 对应根因仍累计复发 11 次——纯文字规则有上限）
❌ 不能全自动维护（需要你主动指出错误、让 AI 记录）
❌ 不能跨工具直接迁移（每个 AI 工具的"读规则"行为不一样，需要适配）

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

怎么贡献

欢迎：

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

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

它是怎么来的

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

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

License

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

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