把编程 Agent 的项目决策写进文件与 CI

事情的经过，说简单点是这样的。周一，你告诉 Agent：不要做邮箱注册，大多数用户没有邮箱，所以要用手机号。

周四，一个新会话一上来就问：“开始之前确认一下：注册应该用邮箱，还是手机号？”

谁都没做错。决定已经做了，理由也很充分。只是这些内容留在了一个已经不存在的聊天窗口里。新会话读了代码，没看到任何关于邮箱的说明，于是做了件合理的事：开口问。有时它连问都不问，直接把我已经否决的方案做了出来。

如果你每天都用 coding Agent，大概已经习惯在每次会话开头敲上一段固定的交代：这是家小店。注册用手机号。别动价格计算代码，那个 bug 我们已经修过两遍了。结账流程卡着，是因为我还没决定支付失败时该显示什么。每次你都会漏掉不同的一条，而出问题的，偏偏就是漏掉的那条。

解决办法不是换个更聪明的 Agent，而是一个文件。

我是一名前端和移动端工程师。一周里大部分时间，我都在开发和维护线上运行的 React 和 React Native 应用；最近也用 Claude Code 和 Codex 做了不少业余项目。我想要的很简单：每次会话的最后五分钟，应该产出一个文件，而不是留下一段记忆。

这就成了 Fragment。它不是什么会执行任务的工具，只是放在 repo 里的几个普通文件：

docs/AGENT-PROTOCOL.md   the rules. one file. every agent and human reads this one
CLAUDE.md / AGENTS.md    three lines each, pointing there. never a second copy
docs/STATE.md            the board. read first, written last
scripts/docs-check.sh    red when any of the above stops being true

STATE.md 里有个小节，叫“已经做出的决定——不要再问”。“用手机号，不用邮箱，因为大多数用户没有邮箱”就写在这里。下一个会话会先读它，再开口。

光靠文件，一周就会失效

“维护一个笔记文件就好”这种办法，我试过。大概能管用五天。然后某次会话忘了更新，下一个会话又信了过期的状态看板，你就又得从头交代一遍。

所以，真正重要的不是目录怎么组织，而是检查脚本。遇到下面这些情况，docs-check.sh 会让 CI 失败：

• 某次会话修改了文档，却没有在日志里留下记录。
• 某个链接失效，或者某份文档没有被收录到索引中。
• 状态看板已经一周没有更新。
• 某项工作声称已经完成，却还有未勾选的复选框，也没有记录执行过的命令。

它不了解你的代码，也不了解你用的语言。它只检查记录是否仍与实际情况一致。repo 专属的规则放在一个本地文件里，由共享检查脚本通过 source 加载，所以更新检查脚本不会改动这些规则。

别人用起来后，实际发生了什么

Fragment 是从一个私有 repo 里提炼出来的，并不是先设计出来再投入使用。两个人、两种操作系统、两个不同的 Agent，18 小时内提交了 25 个 commit。有两件事让我意外：

第一，检查脚本接入 CI 后仅 74 分钟，就抓到了一次真实问题。有人通过 GitHub 网页界面重命名了一个文件。这完全是合理的日常整理，但这次重命名同时违反了三条规则：索引里留下了失效链接、文件没有列入索引、会话日志没有记录。几分钟内，CI 就变红了。没有人粗心，只是网页界面无法检查一个它根本不知道存在的索引。

第二，另一位使用者没人教，就采用了这套工作习惯。他的全部 7 个 commit 都呈现出相同的三文件结构：索引、状态看板，以及实际工作涉及的文件。没有一起进行过会话，也没有人提醒。他们读了同一份协议文件，自然就采取了同样的做法。

这些结果不能证明什么

我宁愿把这些话说在前面，因为一份只会夸自己的案例研究，本质上就是营销：

• n=2。两个生产 repo 都由我负责。
• 超过两个人的并发协作还没有测试过。这两个人是轮流工作的。
• 这里没有任何证据表明 Fragment 能防止 bug。它防止的是上下文丢失，以及对已经做出的决定反复争论。代码是否正确，仍然要靠测试和 review 来判断。

完整过程及对应的 commit SHA，都记录在 CASE-STUDY.md 里。

npx skills add hematenergi/fragment --skill fragment

你也可以把网站上的安装 prompt 粘贴给你正在使用的任意 Agent。第一次运行检查脚本时，它会失败。这正是设计目的：失败项就是你的接入清单。沿着清单逐项处理，直到检查变绿。

如果你试用了，遇到问题，我想知道具体是哪里出了问题。

我是 Dany，一名身处印度尼西亚（GMT+7）的前端和移动端工程师，技术方向包括 React、Next.js、React Native，以及 web3 前端（Solana、EVM）。我也为 AI coding Agent 开发工具。目前接受远程合同工作，个人网站是 hematenergi.github.io。

如需采取进一步操作，你可以考虑屏蔽此人，和／或举报滥用行为。