跟 AI 一起做项目，有一句话很容易脱口而出：“把这次的教训写进 AGENTS.md，下次别再犯了。”

这句话背后的期待很合理。既然已经花时间纠正过一次，就希望下一次任务能继承这份经验。但经验写进文件之后，还有另一件事要处理：新规则跟旧规则是什么关系？如果每次都只往后加，这份给 Agent 看的项目说明，迟早会变得难以维护。

所以我做了 agentsmd-skill。它的任务是把项目经验提炼成少量、可执行的规则，并在写入之前完成去重、合并和清理。2026 年 9 月 4 日，我把它放到了公开仓库。这篇聊聊它的设计，以及我为什么给它加了一条看起来有些生硬的限制：不含空行，最多 120 行。

写下来之后，还需要有人维护

AGENTS.md 是面向编码 Agent 的项目说明文件，可以放构建命令、代码约定和工作流程。它提供了一个相对明确的位置，让接手任务的 Agent 找到项目上下文。

但文件存在，不代表里面的信息一直有效。

项目可能换过包管理器，测试命令可能已经调整，某个临时解决方案可能早就被正式实现取代。如果旧规则没有同步处理，Agent 读到的就是不同阶段的要求。遇到矛盾时，它还得重新判断哪一条适用于当前项目。

重复也是一个问题。同一件事可能先写成“提交前检查”，下次改成“发布前验证”，再下次加上一段更具体的补充。单独看，每句话都有道理；放在一起，却不容易看出它们各自负责什么。

我希望这个 Skill 接住的，就是从“记录经验”到“维护规则”之间的这一步。

什么教训值得成为长期规则

最容易实现的方式，是让 Agent 总结本次对话，再追加到文件末尾。但一段对话里有很多只属于当下的信息：临时文件名、某次运行的参数、还没有验证的推测，都不适合长期留下来。

我在 Skill 里设了三个准入条件：

  • 未来大概率还会遇到。
  • 违反会带来实际损失，例如返工、缺陷或时间浪费。
  • 能用一行说清楚要做什么。

三条要同时成立。用户的明确纠正、实际发生的错误和验证有效的做法，是优先考虑的来源；一次性任务细节和通用常识，则直接排除。

下面是一个说明规则加工方式的假设示例，并非项目事故记录。

原始教训可能是：

这次改了文章图片目录，预览时有张图打不开，后来发现正文路径没有一起修改。

这段话适合放在复盘里。如果项目确实反复遇到这类问题，提炼后的规则可以是：

- 移动文章图片后，同步更新正文引用，并在预览中检查图片能否加载。

它保留了触发条件、具体动作和验证方式，去掉了某次任务的经过。

“一行说清楚”也有边界。需要多步操作的故障排查，不应该强行挤成一条越来越长的句子。详细流程可以留在项目文档里，规则只说明何时查阅它。精简的目的是让指令更明确，不能为了缩短文件而丢失必要条件。

真正关键的是合并旧规则

这个 Skill 的核心放在合并阶段：读取现有文件，建立规则清单，再逐条比较新增内容。

如果已经有等价要求，就丢弃新条目。如果部分重叠，就合并成更精确的表述。如果新经验只是已有规则的一个特例，就检查能否用一条覆盖范围合适的规则表达。明确过时的内容，则应当删除。

继续用一个假设示例说明。文件里原来写着：

- 修改文章后检查图片。

后来又得到一条更具体的经验：

- 移动文章图片后，同步更新正文引用。

直接追加当然可以，但两条之间的关系需要读者自己拼接。更清楚的写法是保留一般检查，再把路径变更的处理条件合进去：

- 修改文章后检查图片加载；若移动图片文件，同步更新正文引用。

这里有个细节：不能为了合并，把原本适用于所有文章修改的检查，缩窄成只有移动图片时才检查。删掉重复文字的同时，要保住原来的有效约束。

当前 Skill 对矛盾规则采用“保留更新的实践”的处理方式。我的理解是，它需要建立在新实践确实适用的前提上。时间更新，本身不足以证明旧规则可以废弃；如果只是两个场景的要求不同，应该把适用条件说明白。

合并因此是一项判断工作。最后留下几行，只是结果的一部分；有没有改变规则原本的含义，同样需要检查。

为什么给它设 120 行上限

120 行不是 AGENTS.md 的官方限制，也不是经过实验得到的最佳长度。官方格式没有强制字段或固定章节；这个数字是我给当前 Skill 设定的维护约束。

我想用它制造一个明确的取舍时刻：文件接近上限时，加入新内容之前，先看看有什么应该退出。

当前削减顺序是：先清理过时规则，再处理重复项，然后检查通用性较弱的特例，最后审视较少触发的章节条目。Skill 还限制章节数量，并建议每个章节不要堆太多规则，避免文件靠增加标题继续膨胀。

不过，行数只能作为粗略指标。一行可以写十个字，也可以写两百个字；同样的行数不意味着同样的阅读负担。低频规则也不一定不重要，例如很少执行但影响很大的发布操作，仍然值得保留清晰的约束。

对更大的项目，官方也提供了在子目录放置 AGENTS.md 的组织方式。当前这个 Skill 的流程主要围绕项目根文件展开，不能把它的 120 行限制当成所有仓库都该照搬的标准。

我更看重的是限制带来的维护动作：加一条之前，重新审视已有内容。

没有文件时，先认识项目

另一个容易走偏的环节，是第一次生成 AGENTS.md。

如果只给 Agent 一个模板，它很容易填出一份看起来完整、却到处适用的文档：保持代码清晰、遵守最佳实践、提交前充分测试。读起来没什么问题，却没有告诉它这个项目到底怎么运行。

所以初始化流程要求先扫描目录、项目说明、依赖和构建配置，以及已有的自动化检查配置，再决定要写哪些内容。

实际使用什么命令，就写什么命令。没有对应流程，就省略相关章节。模板提供组织参考，不要求凑齐所有标题。

这也延续了我之前在写一个零依赖 Skill 的感悟里讨论的方向：让 Agent 学会从项目里获取依据。具体答案会随项目变化，找到答案的方法应该进入工作流程。

交付时，要把删改也说清楚

如果 Skill 最后只回复“已更新 AGENTS.md”，用户很难判断它到底做了什么。

因此我要求它报告三件事：新增了哪些规则；合并、替换或删除了什么，以及理由；更新后的非空行数和剩余容量。

其中，删除和替换尤其值得展示。新增一句话容易理解，删掉一句旧要求却可能影响后续任务。用户需要看到这次修改的依据，才能判断是否准确保留了项目约束。

想试用，可以按仓库安装说明安装，然后在一次任务结束后说：

用 agentsmd 把这次的教训固化进 AGENTS.md。

第一次试用时，我建议选一个刚刚验证过的小问题，检查它如何提炼和合并。先看规则是否准确，再看文件是否更短。

目前公开仓库呈现的是这套工作流设计。我还没有可以据此宣称“错误减少多少”或“效率提升多少”的对照数据，120 行上限的实际效果也需要继续观察。

留下值得下次继续使用的经验

做这个 Skill，让我把注意力从“还有什么没写进去”，转向了“已经写进去的东西，还值得保留吗”。

一次纠正，可以先成为候选经验；经过验证、提炼和比对，才成为长期规则。之后项目发生变化，它仍然需要被修改，甚至删除。

我希望 AGENTS.md 最终留下的是少量清楚的指引：遇到什么情况，应该采取什么行动，如何确认做对了。让下一次任务继承这些判断，才是把教训写下来的意义。