🪽 给编码 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 跑多快,而是保证它跑在路上。
