Skip to content

🪽 给编码 Agent 留缰绳:从约定文件开始 ​

Agent 最可怕的时刻不是它不会写,而是它「自信地写错」:猜一个目录、删一段配置、改一个不该动的路径。解法是把约定写进仓库。

为什么约定文件有用 ​

Agent 不共享你的记忆。你觉得理所当然的「导航名不等于目录名」「这段配置不能删」,对它来说全是未知。不写下来,它只能猜;写下来,猜就变成了查。

本博客的 AGENTS.md(在仓库根目录)里写了几类东西:

  • 目录映射表:顶栏「视野与拾遗」对应 digest/ 和 shootingSkills/ 两个目录。没有这张表,Agent 按导航名找目录会扑空。
  • 命令与验收:npm run build 是验证改动的标准;没有 lint 和测试,就别编造验证流程。
  • 约束与原因:vite.ssr.noExternal 不能移除,因为插件直接引用 .vue;base 必须保持 /,因为部署在根路径。

写约束,也写原因 ​

只写「不许改 X」是不够的,Agent 会绕开 X 但踩中等价的 Y。写了原因,它才能把约束泛化到类似情况。人读文档也一样。

约定要跟着改动维护 ​

导航重构之后,我把映射表同步进了 AGENTS.md。约定文件和代码脱节,Agent 就会按旧约定制造新事故——比没有约定更隐蔽。

约定文件是缰绳:不是限制 Agent 跑多快,而是保证它跑在路上。