# agentsmd 发布后，我的四个设计假设全被证伪 **Published:** November 9, 2026 *发布一个开源 agent skill 七周后，agentsmd 的四个设计假设被真实使用逐一证伪：教训不是会话里唯一值得留下的东西，AI 生成的命令未必跑得通，用它的不全是程序员，发出去也不自然有人用。本文记录每个假设被打脸的现场，以及规则因此长成的样子。* --- 9 月 4 日发布 [agentsmd-skill](https://github.com/kelegele/agentsmd-skill) v1.0.0 那天，我有一种「完成了」的错觉。CHANGELOG 写好了，README 排干净了，三条核心机制——准入门槛、合并闸、120 行上限——在文档里自洽得挑不出毛病。我当时确信，接下来要做的只是等用户上门。 两个月后版本号走到 v1.5.2，[CHANGELOG](https://github.com/kelegele/agentsmd-skill/blob/main/CHANGELOG.md) 里躺了七个版本。回头逐条对，每个版本都不是「新功能」，而是**一次被打脸的记录**：我在发布那天相信的四个假设，被真实使用逐个证伪。把这几记耳光复盘出来，比讲设计本身诚实得多——设计哲学在[上一篇](/blog/agents-md-lessons-without-bloat)里说过了。 ## 假设一：教训是会话里唯一值得留下的东西 v1.0.0 的世界观很简单：会话里产生教训，教训固化成规则，规则写进 [AGENTS.md](https://agents.md/)，一条单行道。头两周用下来，单行道开始堵车——我在会话里想「留下来」的东西，远不止教训。 一份随手生成的对比报告躺在目录顶层，下周还要用；个人 agent 的记忆条目和项目脱节了，该跟着项目走；TODO 和 CHANGELOG 停在上个版本，没人更新。这些东西和「教训」一样，都在问同一个问题：**我该去哪，我该活多久？** 而它们各自的寿命完全不同——规则要活到项目死掉，报告活到下次对比，记忆条目活到被更正。 v1.1.0 于是加了两个条件步骤：agent 有记忆机制，就按宿主格式沉淀项目记忆，先查重再写入；项目有进度文件，就同步更新。散落的产出文档则给了归集流程——先查引用再提方案，批准后才移动，移动后修断链。 这一记耳光教会我的事，比加几个步骤重要：**固化知识的本质不是「写进文件」，是给每条信息找到正确的寿命和位置。** AGENTS.md 只是众多容器里寿命最长的那一个。 ## 假设二：AI 生成的命令可以信任 v1.0.0 还有一个没写进文档的假设：为新项目生成 AGENTS.md 时，从 README 和配置文件摘出来的构建命令是可信的。毕竟它们「有出处」。 直到某个新项目上，生成文件里的第一条命令就是一个死命令。README 里的测试脚本早在两个版本前就改名了，skill 不知道，照抄，写进 AGENTS.md，还加了个体面的对勾。下个会话的 agent 读到它，不会怀疑——**这个文件的定位就是「可信上下文」**——照着执行，第一脚踩空，然后花十分钟排查一个本不该存在的错误。 这件事的恶劣程度超过一般的功能缺陷：十条缺规则，agent 会自己摸索；一条假规则，agent 会信以为真地执行。对一份专门写给 AI 看的文件来说，假命令是毒药而不是空缺。 v1.2.0 的回应是**命令可执行验证**：写入的每条命令逐条实跑；部署、迁移这类不便实跑的，与 `package.json` scripts、Makefile、CI 配置逐一核对，对不上不写入。同版本还引入 [agents.md 官方示例](https://agents.md/)作成稿锚点，让生成的文件有颗粒度参照。 现在回头看，「生成」和「可执行」之间隔着一整个运行时——任何没被运行过的命令，都只是看起来像命令。 ## 假设三：来用它的都是程序员 这个假设藏得最深，因为它从来没被我当成假设——「项目规范」这个词在我的脑子里自动等同于「代码项目规范」。120 行上限、命令验证、章节语义，全部默认读者手里有一个 `package.json`。 然后有人把它装进了一个纯文档协作目录。没有源码，没有构建配置，首版扫描无从下手；「Build & Test Commands」章节对报告库毫无意义，它真正要管的是数据口径、命名归档、交付复核。整套流程在那个目录上静默失灵——最糟的一种失败，不报错，只是没用。 v1.5.0 的**场景适配**由此而来：流程开始前先判定 coding 还是 work 场景，骨架不变，适配三处——coding 核命令，work 核文中引用路径真实存在；归集也分家，文档归 `docs/`，CSV、JSON 这类机器可读数据归 `data/`，数据表不再被当文档塞错地方。 这一记耳光最疼，因为它戳破的不是功能缺失，是我对「用户」的想象。工具一旦发布，就会立刻离开你为它设计的语境——**抽象层级必须跟着使用者走，而不是跟着设计者走。** ## 假设四：发出去，自然有人用 功能稳定后我默认剩下的事是等。事实上 [skills.sh](https://skills.sh/kelegele/agentsmd-skill) 确实早早自动收录了仓库，第一批安装就是这么来的——但「被收录」和「被找到」之间隔着渠道自己的语法。 v1.5.1 主动完成了 [ClawHub](https://clawhub.ai) 与 [LobeHub](https://lobehub.com) Skills Marketplace 的上架，同时把收到的最高频提问写回 README：「Hermes、OpenClaw 这类有记忆的个人 agent 能不能用？」——能，纯 Markdown 无依赖，有记忆机制就按宿主格式沉淀。答案一直成立，只是没人问就没写。 v1.5.2 处理语言问题：Skills Hub 的索引与审核以英文为主，正文和 README 全部切英文默认，中文译文退到 `docs/zh-CN/`。但有个东西不能跟着一刀切——frontmatter 的 `description` 做成双语：英文主句供索引，中文触发短语保留，中文会话里说「总结经验写进 AGENTS.md」照样触发。 分发不是上传动作，是逐个渠道学习它的语法，然后在不丢核心的前提下迁就。 ## 发布之后的事，是换掉自己的假设 四个假设，四个版本，一条规律：**每一次有价值的迭代，都不是「想到了」，而是「被证明了想错了」。** 命令跑不通才有了实跑验证，文档目录失灵才有了场景适配——没有一版来自闭门推演。 所以现在我对「发布」的理解变了。发布那天交付的不是成品，是一组待检验的假设清单；之后的每个 issue、每个反直觉的使用场景，都是清单在逐项兑现。CHANGELOG 里的七个版本，与其说是功能史，不如说是七次认错记录。 给同样在维护小工具的人一个可操作的建议：发布时把自己确信的东西写成一张假设清单——「用户都会写代码」「生成的命令可信」「发出去自然有人用」——然后等着它们挨个被打脸。被打脸的速度，就是你迭代的速度。 agentsmd 的仓库在 [GitHub](https://github.com/kelegele/agentsmd-skill)，`npx skills add kelegele/agentsmd-skill` 一句话安装；0 依赖 skill 的写法心得在[这篇](/blog/skill-craft-lessons)。