让 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.
📖 是什么 •
跟 AI 协作久了你会发现：AI 经常犯同一种错，纠正成本极高，规则越列越多但 AI 选择性遵守。
这是一套已经跑了几个月的协作机制，核心思想：
把 AI 协作当工程问题做反馈循环，不当玄学碰运气。
它由三份文档组成——一份 协作协议（AI 该怎么和你配合）+ 一份 错题本（AI 犯错时主动记录、复发 3 次升级为新协议）+ 一份 CLAUDE.md（自动加载层，触发上面两份的读取）。
这个仓库的卖点是"机制自我迭代"——每个版本都是迭代真实发生的证据。v3 的主线是给机制装上"自动传感器"：
- ⭐ 错题本巡检员（v3 旗舰）：派一个独立 agent 定期扫会话日志，主动补录"发生了但没记进错题本"的失误——正面进攻 v1/v2 都坦承的死穴"AI 经常忘记主动记"。机制从「全手动」推进到「半自动」
- 量化账本：让"这套机制到底有没有用"变得可追踪——每次巡检记一行指标（自查拦截率↑ / 🔴占比↓ / 复发↓ = 系统在变强），配套"单周样本小不下结论"的纪律
- 新增规则 17：「开启创意模式」= 强发散，先碰想法再出 demo——由"用问卷式收窄替用户预选安全答案"那条错题长出来
- 新增 3 个案例（Day 22-24）——含一条所有 AI 用户都该警惕的 🔴「把 model 名/API/版本这类"会随时间漂移的事实"用训练记忆当事实，还标"已验证"」
诚实彩蛋：巡检员没有自吹"全自动了"——它把传感器的盲区（会话搜索工具掉线、空窗期不能误判归档）如实写进账本。连"度量机制有没有用"这件事都在守"事实 vs 推测"的纪律。
v1 → v2 → v3 的完整进化故事见 CHANGELOG.md。
| 场景 | 你心里的 OS |
|---|---|
| AI 说"已修复 X"——你跑代码发现没修 | 它怎么又这样 |
| AI 信誓旦旦说"这个做不到"——你换个问法发现能做到 | 它在编造限制 |
| 同一个错改了 3 次还在犯 | 我是不是该换个工具 |
| 写了 5000 字 CLAUDE.md / .cursorrules，AI 第三轮就忘了 | 规则太多没用 |
| AI 不被你追问，就发现不了它说错了 | 这才是最可怕的 |
这套机制不能让 AI 不犯错，但能让重复同类错的概率降下来 + 纠正成本随时间下降。
跟 GitHub 上常见的 awesome-cursor-rules 类项目比，那些是列规则，这个是反馈循环机制：
- 「沉默错误」概念——专盯"用户不追问就发现不了"的错，不是泛泛防 AI 出错
- 思维根因 vs 知识根因——不写"下次注意 X"，深挖"哪一步思维方式错了"
- 「事不过三」升级阈值——同一根因复发 3 次才升级为硬规则，防规则膨胀（v2 里它第一次完整跑通）
- 三层架构：观察层 ↔ 规则层 ↔ 自动加载层，闭环升级
- 「动作 ≠ 结果」反射——AI 说"已 X"必须对应真实工具调用
- 规则退役机制（v2 新增）——与升级对称的"减法"：根因休眠 → 规则降级。只增不减的规则体系必然膨胀
- 核心卡 + 意图路由表（v2 新增）——高频反射常驻上下文，长文档按需深读，治"读了规则不用规则"
- 巡检员 + 量化账本（v3 新增）——一个 agent 定期扫日志补录漏记的失误，并量化"这套机制到底有没有用"。机制从"全手动"推进到"半自动"
┌──────────────────────────────────────────────┐
│ 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 个高代表性案例（脱敏后开源版）：
| # | 标题 | 根因 |
|---|---|---|
| 1 | 把 OAuth 403 误判为"地区限制" | 推测当事实、证据缺口用猜测填空 |
| 2 | merge 提交信息夸大"人工核验通过" | 动作 ≠ 结果、能渲染 ≠ 已核验 |
| 3 | 把别的 AI 判定的"性格弱点"当事实写进档案 | 没追溯来源、推测当事实 |
| 4 | HTML 整合堆砌行业黑话，未配生活化比喻 | 读了规则没在每一步用 |
| 5 | 共享日志里别人做的事被当成自己功劳 | 跨实例协作的责任归属 |
| 6 | 过度防御"内容纪律"，忽视"视觉品质" | 上次教训过度泛化 |
| 7 | 编造工具输出：把"我以为会发生"当成"已经发生" | 完成欲压过真实性——推测当事实的极端形态 |
| 8 | 听到持久偏好只口头答应，没落盘 | 口头确认 ≠ 持久化 |
| 9 | 验证只查"正面"漏查"反面"——留下鬼影 | 虚假确信：贴了证据没证到点子上 |
| 10 | 用肉眼数网格坐标，反复偏错 | 把不可靠输入当客观工具 |
| 11 | 3D 模型只验"出现"没验"完整"——规则 16 诞生 | 完工验证不彻底（第 5 次复发，触发升级） |
| 12 🆕 | 把 model 名/API/版本这类"会漂移的事实"用训练记忆当事实 | 训练记忆当事实 + 把推测标"已验证"（所有 AI 用户都该看） |
| 13 🆕 | 手边有真理文档不读，拿通用模板下定论 | 推测当事实的签名变体（累计 3 次） |
| 14 🆕 | 用户目的并列多个点，没问"哪个是主"就自己挑一个 | 默认解读代替追问 |
每条都包含：现象 → 真相 → 错误推理路径 → 思维根因 → 预防规则。
| 文件 | 用途 |
|---|---|
| README.md | 本文件 |
| PROTOCOL.md | AI 该怎么跟你配合——17 条协作规则 + 自动加载层核心卡 + HITL 工作流 |
| MISTAKE-LOG.md | AI 协作误判记录 + 思维根因分析 + 升级/退役机制 + 巡检员半自动维护 |
| CHANGELOG.md | v1 → v2 → v3 的进化记录——机制自我迭代的证据 |
| AGENTS.md | 单文件合并版，给 AI 直接读 |
- 跟 AI 协作做正经活的人：PM、研发、设计师、写作者、研究者……
- 觉得 AI 经常"犯傻"但又必须用它的人
- 看不上"列 100 条规则"那种 .cursorrules 模板的人
- 想沉淀自己跟 AI 协作方法论的人
❌ 不能让 AI 不犯错（即使升级硬规则后，本机制案例显示规则 7 对应根因仍累计复发 15 次——纯文字规则有上限）
✅ 能显著降低同类错误反复出现的频率 ✅ 能让你的纠正成本随时间下降 ✅ 能让协作方法论变得可见、可分享、可迭代
欢迎：
- Issue：你跟 AI 协作时遇到的"沉默错误"案例
- PR：补充新的错题本案例（脱敏后）、修订规则、增加冷启动指南细节
- 讨论：你自己的协作机制对比
唯一要求：新增的错题条目必须包含「思维根因」和「预防规则」两节——不要只发"AI 又错了"的吐槽。
作者是 AI 产品经理（独立做事），编程小白，每天用 Claude Code / Cursor 协作 8+ 小时。跑了几个月发现 AI 同一类错反复出现——于是开始记错题本。攒到 30+ 条后发现"事不过三"是个好阈值。
机制本身也在持续迭代——v1 发布两周后机制自己就长出了 5 条新规则和 3 个新机制，见 CHANGELOG。
MIT —— 随便用、随便改、欢迎在你的项目里挂出处。
这个仓库本身就在用错题本机制持续迭代。
如果你看到 README 里有让你疑惑的地方，那可能就是下一条错题。