让CI失败：为编码代理建立持久记忆与检查机制

多会话编码代理常常重复提问，因为关键决策只存在于已关闭的聊天窗口中。一位前端工程师用一套文件协议解决了这个问题——不是让代理更聪明，而是让上下文沉淀成仓库里的文件，并用CI检查强制维持。

问题：会话重置后，决策随之消失

模式很简单：周一你告诉代理注册用手机号，因为大部分用户没有邮箱；周四新会话打开，代理看到代码里没有邮箱相关逻辑，于是合理地问——“注册用邮箱还是手机号？”没有人做错，但决策和理由都留在了不存在的聊天窗口里。更糟的是，有时代理不问，直接按已否决的方案实现。

每天使用编码代理的开发者可能都在会话开头写一段“小型简报”：这是个小店，注册用手机号，别动价格代码因为修过两次，结账流程卡在失败支付页面的设计上。但你每次都会忘掉不同片段，而忘掉的那条恰好会出问题。作者作为React和React Native工程师，日常使用Claude Code和Codex，他的诉求很直接：会话最后五分钟应该产出一个文件，而不是一段记忆。

方案：不是更聪明的代理，而是一组文件

这组文件叫Fragment，它不运行任何东西，只是仓库里的几个纯文本文件。核心是docs/AGENT-PROTOCOL.md（规则，一个文件，人和代理都读它）、CLAUDE.md和AGENTS.md（各三行，指向协议文件，绝不复制第二份）、docs/STATE.md（看板，先读后写）、scripts/docs-check.sh（检查上述文件是否仍然为真）。

STATE.md里有一个专门的段落：“已经做出的决策——不要再问”。手机号而非邮箱、原因是什么，都写在这里。下一个会话在开口之前先读它。

这与常见的“记忆文件”思路不同：很多工具把记忆存储为向量数据库或持久内存，但作者选择把决策变成仓库中可版本控制、可审查的普通文件。代理不需要理解数据库，读Markdown就够了。这也意味着人类可以随时编辑、diff和回滚，不会出现黑箱记忆。

CLAUDE.md 和 AGENTS.md 是编码代理领域逐渐形成的约定文件名：前者被 Claude Code 等工具自动读取作为项目说明，后者常被 Codex 等代理识别。它们本质上是放在仓库根目录的提示文件，代理在会话开始时会自动加载。Fragment 把它们压缩成三行指针，只负责把代理引向 docs/AGENT-PROTOCOL.md，从而避免同一份规则被复制多份后彼此漂移。这种「单一事实来源」的写法是文件协议能维持一致性的前提。

检查机制：文件本身一周就会腐烂

作者试过“只维护一个笔记文件”的做法，大约五天后失效：一个会话忘了更新，下一个会话信任过期的看板，于是又回到开头的简报循环。真正重要的是检查脚本。docs-check.sh在以下情况让CI失败：会话改了文档却没有留下日志痕迹；链接失效或文档未被索引；看板一周没有变动；工作标记为done但复选框未勾选且没有记录命令。

它不关心你的代码或语言，只检查“故事”是否仍然为真。仓库特定的规则放在本地文件里，由共享的检查脚本source进来——更新检查逻辑不会碰这些本地规则。这种设计把检查层和业务规则分离，便于升级和复用。

CI（持续集成）是代码托管平台在每次推送或合并请求时自动运行的流水线，通常用于跑测试和构建。把 docs-check.sh 接入 CI 意味着：任何提交都会触发对文档一致性的检查，失败会阻止合并。这与本地手动运行不同——本地检查依赖人记得执行，而 CI 检查由平台强制执行，无法被跳过。作者强调的「不可跳过的工程约束」正是指这一点：把维护记忆从个人纪律变成合并门槛。

实际效果：74分钟抓到一次真实事件，第二个人自然习得流程

Fragment是从私有仓库提取的，不是先设计再实现。两个人、两个操作系统、两个不同的代理，18小时内25次提交。两件事出乎作者意料。

检查脚本在接入CI后74分钟抓到一个真实事件：一个文件通过GitHub网页界面被重命名。这是非常合理的整理动作，但重命名同时打破了三条规则——索引链接悬空、文件未被列出、跳过会话日志。CI在几分钟内变红。没有人疏忽，只是网页界面看不到它不知道的索引。

第二个人没有经过教学就采纳了仪式：他的七次提交全部呈现相同的三文件形态——索引、看板、实际工作。没有共享会话，没有提醒，只是读了同一个协议文件，就收敛到同样的动作。这暗示文件协议本身具备一定的自解释性，不过样本量极小，不足以证明可推广性。

它不能证明什么

作者自己列出了局限：n=2，两个生产仓库都由他本人运行；超过两人的并发未测试，那两人是轮流操作；Fragment不证明能防止bug，它防止的是上下文丢失和重复争论已决策的事项。测试和代码审查仍然决定代码是否正确。完整的工作记录（含commit SHA）在CASE-STUDY.md里。

n=2 是统计学中对样本量的表述，指这项观察只基于两个人、两个仓库。样本量如此小，任何「第二个人自然习得流程」的结论都只能视为个案信号，而非可推广的证据。作者主动标注这一点，是在区分「我观察到了什么」和「我能证明什么」。在工程写作中，明确样本边界比夸大普适性更有价值，也为后续更大规模的验证留出空间。

如何尝试

在Claude Code中运行npx skills add hematenergi/fragment --skill fragment，或者把网站上的安装提示粘贴到你使用的任何代理中。第一次运行检查脚本会失败——这正是特性所在，它是一个采用清单。逐项处理直到变绿。作者是印度尼西亚的独立工程师Dany，使用GMT+7时区，接受远程合同工作。

Fragment的价值不在于发明了新概念，而在于把“代理记忆”从聊天窗口迁移到仓库中，并用CI把维护记忆变成不可跳过的工程约束。这比任何单次提示技巧都更持久，也比让代理变聪明更可控。代价是：你需要维护一个看板和一个检查脚本，并且在团队中形成会话开始读协议、结束写状态的纪律。对于每天与编码代理协作的开发者，这可能是目前最低成本的上下文持久化方案之一。