让编程Agent先识别生成文件再修复

AI Agent 修好了接口字段，本地测试也过了，CI 一跑，修复却消失了。原文讨论的是一个容易被忽略的原因：Agent 改了生成文件，下一次构建又把它覆盖了。提交记录里有补丁，不代表构建后还保得住。

作者给出的原则很直接：动手前先区分源文件和生成产物，把修复放进模板、Schema 或 OpenAPI 文档，再重新生成。对使用自动生成客户端、类型文件和编译样式的团队，这比继续补提示词更值得先检查。

为什么本地通过，到了 CI 就失效

问题通常沿着同一条路径发生：Agent 打开生成的客户端或类型文件，看到字段错误、请求头缺失，直接修改输出文件。本地测试读取的正是这份文件，因此可以通过。

但 CI 执行干净安装，重新运行生成器，文件又恢复成输入所描述的样子。刚才的修改被覆盖，错误随之回来。团队看到的是「明明提交过修复」，实际运行的却是重新生成的代码。

本地测试通过，只能证明当前磁盘上的文件可用，不能证明这份修改能够被构建流程重现。

作者认为，这类问题的关键不是 Agent 不会修代码，而是它没先判断代码由谁维护。生成文件只是结果；决定结果的模板、契约或其他输入，才是应该追溯的地方。

怎样把修复留在下一次构建里

编辑前，作者建议检查三类线索：文件头是否声明由工具生成，文件是否位于构建输出目录，以及 package scripts 中是否存在代码生成步骤。原文的小节没有继续展开检查方法，也没有给出具体命令，不能据此假定所有项目都有统一入口。

以 OpenAPI 生成的客户端为例，如果字段名或类型来自接口描述，就应该修改 OpenAPI 文档，再重新生成客户端。直接改输出的 TypeScript，只修到了这一份文件，还会让它与接口契约产生偏差。

如果现有生成器无法表达需要的变化，作者建议扩展模板或生成器。临时手改看似更快，但下次生成后还要重新处理。

要让这条规则真正执行，还需要两道约束：

• 让生成文件主动表明身份：使用清晰的目录名，并添加生成标记。
• 在 CI 中重新生成产物，检查它与仓库提交的版本是否一致。

后一项是漂移检查（drift check）。大白话解释，就是确认「仓库里保存的结果，确实能由当前输入重新做出来」。对于已经提交的生成文件，它能把悄悄丢失的修改变成构建阶段的显式失败。

是否提交生成文件，则取决于使用方式。下游需要直接使用、不能要求它先运行构建时，可以提交，同时增加漂移检查；如果每个环境都会重新生成，作者建议用 gitignore 排除产物，只保留输入。

我的判断

我认同作者把检查时机放在「编辑之前」。单纯要求 Agent 小心，执行效果取决于它有没有读到规则；目录、文件头、明确的生成命令和 CI 检查，可以让规则更容易遵守，也更容易验证。

不过，「文件由工具生成」还不足以单独决定它今后应该怎样修改。 原文把工具生成的迁移文件也列入适用范围，却没有交代这些文件生成后是否仍由工具持续管理。具体项目仍要确认维护约定，不能看到生成来源就机械套用。

类似地，OpenAPI 字段错误适合回到接口描述修复，但原文没有说明请求头缺失究竟来自契约、模板还是其他配置。可靠的操作是先追溯生成来源，再决定改哪里。

作者也没有提供实测案例、耗时数据或与其他方案的对照。因此，「漂移检查成本低」「能消除整类问题」应视为工程经验判断。相较于只在 Agent 指令里禁止修改生成目录，CI 检查的优势是能够验证结果；但原文没有证明任何一套检查配置可以直接适用于所有团队。

能拿来做什么

• 给前端或 Node 项目的 Agent 指令补上生成目录、输入文件位置和实际 codegen 命令，让它在修复客户端或类型前先找到维护入口。
• 遇到生成客户端的字段或类型错误时，先检查 OpenAPI 文档，修改后重新生成，并检查产物差异，避免只补当前文件。
• 对已经提交到仓库的生成产物，在 CI 中增加重新生成和差异检查，让无法重现的手工修改及时失败。
• 处理 lockfiles 和测试 snapshots 时，使用拥有这些产物的工具更新：前者走包管理器，后者走测试运行器的更新参数。原文未给出具体参数，应按项目实际配置执行。