把智能体踩过的坑写进仓库规则

AI 编程代理能改代码、发部署，却未必知道上周为什么做了某个决定。作者用一个 GitHub 仓库维护多个芬兰语指南站点，日常更新主要交给两个 AI 代理。用了两个月后，他们认为，仓库里最重要的是根目录那份共享指令文件。

它的价值是把踩过的坑、业务约定和交付边界留给下一次会话。对经常让 AI 接手仓库的团队，这篇经验值得参考，但其中的部署授权不能直接照搬。

为什么团队经验要写进仓库

按作者这套工作方式，代理每次接任务都从零开始，不会自动记住昨天的错误。同一个仓库还有两个代理协作，临时对其中一个说过的话，也不会自然传给另一个。

因此，需要持续生效的约定被写进根目录文件，纳入版本控制，像代码一样通过 pull request 审查。作者说，文件里几乎每一行都来自一次真实问题。

反复出现的错误，应该推动共享规则更新。

不过，共享上下文不等于把所有历史塞进去。早期代理会先读几周的任务记录，普通修改也迟迟无法开始。后来他们要求先读简短的状态页，再看各站点的交接说明；历史仍然保留，但日常改动不必翻阅。

这里区分了两类信息：状态页回答「现在是什么情况」，历史记录回答「过去怎么走到这里」。多数任务先需要前者。

哪些边界要提前讲清楚

作者把「完成任务」定义为一条完整交付路径：收到更新指令后，代理自行构建、检查、合并和部署，不在每一步重复询问授权；如果用户明确说「先给我看」，就停在预览阶段。重复请求同一项许可，在他们的规则中被视为错误。

这能减少打断，但前提是团队已经约定了交付权限。

执行范围也必须明确。代理只能在长期维护的源文件里做最小修改，不能顺手重建站点、新增导入或重新设计页面。作者遇到的问题是，代理很愿意改进用户没有要求改进的东西。

还有两条规则来自业务，而非代码风格：

• 页面保留经过核实的首次发布日期，只有内容确实变化，才能更新修改日期。禁止用构建时间或全站统一时间戳，让旧内容看起来像新内容。
• 合作方展示顺序和优惠内容以月度登记表为准。重新设计页面不能改动顺序，上个月的协议也不能默认延续。

代理可能把它们理解成日期字段和页面布局，团队却需要把它们当作事实与协议维护。指令文件要补上的，正是代码里看不出来的约束。

检查要跟着改动走，规则也要能删除

以前，一行文字修改可能触发所有页面的浏览器测试，再做一次备份。作者后来要求：验证范围跟随改动大小，同一版本已经得到的结果，不再手工重复验证。

部署失败也不能直接重跑。代理必须先找出实际原因，只有托管服务商 API 的一种已知临时错误，允许按文档例外处理。原文没有说明是哪家服务商，也没有给出具体错误。

交付记录则尽量收敛：一次变更以部署运行及其摘要为记录，不另开文档 pull request，不给普通编辑补状态行，也不把报告复制进三个文件。两个代理各自完成接到的任务，不碰对方尚未完成的分支。

但规则不是越多越好。他们曾用校验和锁定某些文件，以便验证导入，其中误把经常变化的状态页也锁住了。校验值过期后，不相关的 pull request 开始失败。

解决办法是把状态页移出校验清单，而不是继续修补校验值。

保护机制如果阻碍了文件的正常变化，它自己就成了缺陷。

因此，作者要求文件短到每次都能完整读完，原因不明显的规则要写明理由；代理同样的错误犯两次，就修改文件，并通过 pull request 审查。

我的判断

我认同把反复成立的约定放进仓库。相比每次复制提示词，它更便于共享、审查和追溯；相比让代理翻完整历史，状态页与交接说明也更直接。

但这仍是两个月使用后的经验之谈。作者没有给出修改前后的耗时、故障率或对照实验，不能据此断言一份指令文件能带来多少效率提升。

有几处尤其需要带着前提读。自动合并和部署适合已经明确授权的工作流，涉及生产权限、人工审批或回滚要求的团队，需要写自己的边界。「检查改了什么」也不能只按行数理解，一行公共配置或依赖变更，影响可能覆盖全站。

此外，原文没有给出文件名、完整内容或两个代理的加载方式。它提供的是维护思路，不能据此认定任何代理都会自动读取并严格执行根目录规则。

能拿来做什么

• 给日常 AI 编程整理一份简短的仓库约定，优先写清永久源文件的位置、任务完成标准，以及哪些操作需要停下来等待。
• 给前端内容站明确日期和合作位规则，避免页面构建、组件重构顺手改动业务事实。
• 在前端或 Node 项目中，按影响范围安排检查；部署失败先定位原因，只为已经确认的临时故障设置重试例外。
• 定期清理指令文件，把重复犯错补成规则，也把过时约束删掉；状态信息频繁变化时，检查它是否被不合适的校验机制锁住。