在一个由好几个 AI（Agent）轮流接力干活的代码仓库里，常常会出现一个让人细思极恐的问题：
上一个 AI 在某个地方吃过亏，但这个教训只写在它自己的对话记录里，等下一个 AI 接手时，手里根本没有这份避坑指南，结果又一头掉进同一个坑里。
在 Polter 这个项目（一个基于高性能终端 Ghostty 改造的项目）的开发中，就真实发生过这样一幕：
连着六个提交，系统测试显示的都是清一色的全绿，一切正常。但运行一次不带任何过滤条件的全局测试（zig build test），就会发现早就红了，因为那条出错的穷举 switch 分支，在前面那六次测试里一次都没有被编译过。
六个提交，谁都没发现，因为大家每次看到的都是绿灯。
为了解决前人踩坑、后人接着踩的问题，这个仓现在的做法是分两层放。
第一层：仓库外面的教训记忆库（记细节）
第一层记忆放在电脑里代码仓库的外面，路径是 ~/.claude/projects/.../memory/。规则很简单，一条教训一个 Markdown 文件，另外配一个索引文件 MEMORY.md。
截至 2026 年 9 月，这里已经攒了 240 条记忆，分三类：feedback（教训）170 条，project（项目相关）39 条，reference（参考、事实）31 条。
1. 记忆文件长什么样？
拿其中一条真实记录 terminal-send-ok-is-not-delivered.md 举例：
- 现场还原：给另一个终端里的 AI 发指令时，工具返回了
ok:true。但实际上那条指令只是安安静静地停在了对方的输入框里，对方足足 32 分钟没收到。 - 为什么被骗（Why）：
ok的意思仅仅是字打进去了，不代表提交发出了。更麻烦的是，输入框里没发出去的草稿，和一条被打断退回来的指令，在屏幕上长得一模一样，被打断的那条在历史记录里不留任何痕迹。 - 以后怎么做（How to apply）：发完关键指令后，去终端历史里找那条以
❯开头的原话，找不到就是没送到，别想当然地以为对方正在思考。
这样的文件每个都不长，下一个 AI 只要扫一眼第一行的摘要，就知道跟自己手上的活有没有关系，有关系再去读具体做法。
2. 教训被推翻了，千万别删
记忆库里有一个很酷的原则：结论被推翻了，文件也绝对不删。
比如有一个文件叫 zig-test-filter-is-additive.md。最早的结论说：测试过滤参数 -Dtest-filter 不是在做过滤，而是在基线之外做叠加。因为当时测试发现，写一个什么都匹配不到的名字会报 85 个通过，写一个真名会报 86 个通过。
直到后来有人发现，如果在测试里放一个必然失败的 expect(false)，当过滤条件匹配不到时，这条测试根本就没跑，只有匹配到时它才会真正去跑并报错。旧结论就这么被推翻了。
但旧文件没删，而是在文件开头加上一行 ⛔️ 2026-09-18 推翻，把新读数写在最前面，旧读数留在后面。
为什么要留着？ 因为旧结论的实用部分依然成立，当你用一个匹配不到的过滤条件时，屏幕上照样显示 87 pass，数字看着很正常，但你要测的东西其实一条也没跑。如果不留着这份错误档案，下一个 AI 哪天又量出 85 和 86，就会以为自己发现了新大陆，把那个老错误再犯一遍。
3. 第一层的缺点
它只存在当前这台电脑的用户目录下，别人把代码 clone 过去，这 240 条一条都读不到。
另外也没人整理，时间久了出现了重复，比如 两边都有 ≠ 两边一样 这条出现了两次，不要动 git 暂存区 和 agent 不能碰暂存区 说的其实是一件事。
第二层：跟着代码走的 CLAUDE.md（守红线）
第二层直接放在代码仓库的根目录下，是个软链到 AGENTS.md 的文件，必须跟着 git 进仓库，谁 clone 代码，谁就能第一时间读到。
但这里的核心策略是：字数一定要少，只留最核心的红线。
这一节开头就写明了：这里列出的每一条，都必须对应在这个分支上付过代价的真实返工，不写空洞的大道理。
为什么要有这一层？
以前，文档里写着一条很正常的建议：全量测试太慢，平时优先用局部过滤（-Dtest-filter）。
AI 们很听话，两天里每一次跑测试都带着过滤。结果呢？仓里专门用来防错的三道一致性检查，因为没被过滤选中，两天里连一次都没编译过。
吃过这次亏之后，这条建议没删（写代码时用过滤是对的），但紧接着补上了一条生死线：
最终交付前，必须完整跑一次不带 filter 的全局测试，带 filter 的全绿，连这棵树能不能编译通过都证明不了。
再看另一个经典的地板坑
仓里流传着一句话：绿不算证据，地板才算。
什么叫地板？就是你想知道一个检查机制灵不灵的时候，必须先故意把被测对象弄坏、亲眼看到检查报错红了，你才敢相信这个检查是管用的。
结果这个仓在这上面出过三次错：大家在拆除防卫代码时，直接把那一行代码给删了，编译器报错 unused function parameter（未使用的函数参数）。系统一红，大家以为是检查机制起效了，其实代码连断言（Assertion）那一行都没跑到，红的只是编译错误。
为了填这个坑，现在的规范改成了：拆守卫时让代码照样编得过，用 if (...) {} 把它空架起来，不准直接删行。
类似这样的核心铁律，在 AGENTS.md 里一共只有七条。
总结：两层记忆怎么配合？
- 第一层（仓外的记忆库）：负责装细节和过程。记录当时怎么出的错、为什么信错了、现场数据是多少。它可以很庞大，也可以随时推翻重写。
- 第二层（仓内的 CLAUDE.md）：负责装底线和红线。只留那些必须刻在骨头里、每次开工前必须知道的硬核教训。
细账记在外、红线带在身，用这种分层的办法，多个 AI 在同一棵树上轮流接力时，才能真正做到前人栽树、后人乘凉，不至于陷进重复踩同一个坑的死循环。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/lugia123/article/details/166647745
