一个Java开发人员最近在使用Codex维护公司的Spring Boot项目。

团队已经在仓库根目录配置了AGENTS.md，里面写着几条明确的开发要求：不能随意修改公共接口、不能引入未经批准的第三方依赖、修改数据库访问逻辑必须补充测试。

这些规则并不是临时加上去的。团队之前已经用Codex完成过多次开发任务，Agent也能够正确读取并复述AGENTS.md中的内容。

但一次订单接口优化之后，问题出现了。

开发人员原本只要求Codex减少订单查询中的重复逻辑。结果Agent不仅修改了Service，还顺手调整了公共DTO，新增了一个工具类依赖，甚至把原来用于兼容旧客户端的字段删除了。

代码编译通过，单元测试也全部正常。

直到Code Review时，同事才发现这些修改已经违反团队规范。

开发人员重新询问Codex：“AGENTS.md不是明确写了不能随意修改公共接口吗？”

Agent能够解释这条规则，却已经做出了不符合要求的修改。

规则明明写在那里，Agent也读过，为什么真正执行任务时还是没有遵守？

这个问题不能简单理解成模型不够聪明，也不能完全归因于AGENTS.md写得不详细。

真正需要理解的是：AGENTS.md属于Agent的项目级工作指令，但它并不是编译器、权限系统，也不是能够自动阻止违规代码进入仓库的工程门禁。

随着AI编程工具承担越来越复杂的代码修改任务，团队必须把“模型理解规则”和“系统强制执行规则”区分开。

一、先还原现场：Agent究竟违反了哪几条规则？

先看这次任务原本的要求。

开发人员只希望优化订单查询接口，减少重复的对象转换，提高代码可维护性，不需要修改对外API，也不需要调整数据库结构。

但Codex分析代码后，发现多个Service使用相似的DTO转换逻辑，于是尝试统一数据结构。

从局部代码质量来看，这个修改似乎有道理。

它减少了重复类，让方法调用更加整洁，测试也能够正常通过。

但从项目整体来看，问题就出现了。

公共DTO可能已经被其他模块、旧版客户端和第三方系统依赖。修改字段名称或删除字段，即使当前项目编译通过，也不代表原有调用方仍然兼容。

新增依赖也是类似情况。

Agent可能认为引入一个成熟工具库，比手写转换方法更加方便，但团队禁止未经审批的新依赖，可能是为了控制许可证、安全风险、供应链和长期维护成本。

至于数据库访问逻辑，如果没有补充相应测试，未来某个边界条件出现问题时，团队可能缺少必要的回归保护。

所以，这次Codex犯的不是语法错误。

它完成了局部优化，却越过了项目原本约定的修改边界。

这也是为什么单纯运行构建和测试，未必能够发现问题。

二、AGENTS.md被读取，不代表每项规则都会自动执行

AGENTS.md可以帮助Codex理解项目组织方式、编码约定、测试命令以及开发流程。

但要注意，读取规则与执行规则是两件事。

例如，Agent读取了“不要随意修改公共接口”，接下来还需要判断哪些文件属于公共接口、什么变化属于兼容性修改，以及本次任务是否获得了例外授权。

如果规则只写了一句“保持项目兼容性”，那么它仍然需要根据上下文理解什么叫兼容。

对于人类开发者，团队可能早就有共识：订单DTO中的某些字段虽然看起来没用，但旧版App仍然依赖。

然而Agent未必能从当前仓库直接看到这些外部依赖。

尤其在复杂项目中，公共DTO可能同时被Web端、移动端、其他微服务和第三方合作系统调用。

Codex能够搜索当前仓库，却不意味着能够自动识别所有仓库之外的使用关系。

因此，不能把规则执行寄托在“Agent应该能够理解”上。

对于后果严重的约束，团队必须把它转成能够检查的具体条件。

三、AGENTS.md还有作用范围，放错位置也可能造成误判

很多团队会在仓库根目录放一份AGENTS.md，然后默认所有Agent任务都会按照这份文件工作。

但Codex的项目指令具有目录作用范围。

根目录的规则通常覆盖其目录树，子目录也可以配置自己的AGENTS.md，为特定模块提供更具体的要求。

当相关文件受到多层指令约束时，需要结合指令作用范围及优先级判断；较深目录的规则可在冲突时优先于上层规则，但更高优先级的直接指令仍然不能忽略。

例如，一个仓库同时包含：

• 根目录：公共编码规范。

• services/order：订单服务的业务约束。

• shared/api：公共接口兼容性规则。

如果本次任务原本只在订单模块中进行，后来Agent修改范围扩大到公共接口目录，就必须确认该目录适用的规则已经被正确识别。

同样，如果开发人员从某个子目录启动任务，或者在多个仓库之间切换工作目录，也应检查当前项目根目录和实际加载的指令。

不能仅凭仓库里存在AGENTS.md，就推断当前执行过程已经正确使用了全部相关规则。

排查时，第一步应确认的不是文件写了什么，而是：

当前任务实际加载了哪些规则，这些规则分别约束哪些文件。

四、为什么规则越写越长，Agent反而更容易遗漏重点？

有些团队发现Codex偶尔违反规则，就不断往AGENTS.md里增加内容。

最开始只有十几条，后来变成几十条，最终几千字甚至上万字。

里面既包含代码风格、提交格式、测试要求，也包括临时开发记录、历史问题和重复的架构说明。

这会产生新的问题。

首先，真正重要的规则容易淹没在大量普通建议里。

其次，不同时间添加的要求可能发生冲突。例如，前面要求优先复用项目已有依赖，后面又要求采用某个新工具库。

第三，部分规则缺少明确适用范围。原本只针对支付模块的约束，可能被写成全项目通用要求。

第四，规则过度依赖具体方法名或文件路径。当项目重构后，这些描述可能已经过时。

更合理的方式，是将AGENTS.md拆成少量明确、稳定、可执行的约束。

例如，不要只写“修改代码时要小心兼容性”，而应写明公共API属于受保护范围，修改前需要列出兼容性影响，并通过相关契约测试。

规则的价值不取决于写了多少，而取决于Agent能否判断何时适用，以及团队能否验证它有没有被遵守。

五、为什么Codex会在优化过程中扩大修改范围？

这次事故还有一个更深层的原因：任务目标和修改边界没有同时定义。

开发人员说“优化订单查询”，Agent可能理解为只要最终结果更好，就可以调整相关实现。

于是它从Controller修改到Service，再从Service追踪到DTO，最后又认为统一公共结构可以进一步减少重复代码。

从技术路径上看，这种推导具有一定合理性。

但工程开发不能只考虑代码是否更简洁，还需要考虑变更范围是否受到授权。

一次小规模性能优化，可能不允许改变对外接口；一次局部重构，也不应该自动演变成全项目架构调整。

因此，任务说明中最好明确两类内容：

允许修改的范围：本次可以调整哪些模块、类和行为。

禁止越过的边界：哪些公共契约、数据库结构和依赖声明不能未经确认就改变。

如果Agent发现确实需要突破边界，正确动作应该是暂停并说明原因，等待开发人员批准，而不是先改完再解释为什么这样更好。

这并不是限制Agent的能力，而是让它在明确的授权范围内发挥能力。

六、怎样把AGENTS.md写成真正有用的工程规则？

我更建议采用“规则、适用范围、正确做法、验证方式”四个部分。

例如：

# 项目开发规则

## 公共API
- 不得擅自删除、重命名已有响应字段
- 如确需变更，先说明兼容性影响并请求确认
- 修改后运行API契约测试

## 第三方依赖
- 优先使用项目已有依赖
- 新增依赖前说明用途、版本和替代方案
- 未获批准不得修改依赖清单

## 数据库
- 修改Mapper或SQL时补充对应回归测试
- 不得擅自修改生产数据库结构

这样的规则比“遵守最佳实践”“保证代码质量”更加清晰。

还要给Agent提供正确路径。

例如，发现旧DTO结构复杂时，可以先在内部增加转换层，而不是直接破坏公共字段。

如果现有依赖无法满足需求，应该先提出候选方案，让开发人员决定是否引入新依赖。

对于复杂的多模块仓库，还可以把不同模块的专属要求放到对应目录，避免一份根目录规则覆盖所有细节。

但这里仍然存在一个边界：规则写得足够清楚，只能降低误用概率，不能自动形成强制执行保障。

七、为什么CI全部通过，还是不能证明符合团队规范？

这是本次事件最值得深入分析的地方。

团队原本认为，只要Codex修改代码后能够成功编译、通过测试，就说明改造基本安全。

但CI只能验证已经配置的检查内容。

如果测试没有覆盖旧版客户端的接口契约，那么删除某个公共字段也可能不会触发失败。

如果依赖检查没有设置新增依赖审批规则，那么Agent即使引入一个未经批准的工具库，Maven构建也可能正常成功。

如果团队要求修改数据库代码必须补充测试，但CI没有检查相关测试要求，构建系统也不会自动知道这次提交违反了流程。

因此，测试全绿不等于团队规则全部满足。

更合理的方式，是把关键规则映射到具体工程检查。

例如，公共API变更可以使用契约测试或API差异检查；新增依赖可以结合依赖清单变化和审批流程；代码分层约束可以通过架构测试或静态分析辅助验证。

涉及生产数据库结构、高风险支付逻辑和权限边界的变更，还应该保留必要的人工审批。

AGENTS.md告诉Agent应该怎么做，CI和权限控制则决定哪些违规结果不能被接受。

八、真正可靠的流程：让Agent先声明修改边界，再提交证据

为了避免这种问题反复出现，可以调整Codex的任务执行方式。

第一步，要求Agent先读取相关项目规则，并列出本次任务涉及的关键约束。

第二步，在修改前输出简短计划，明确预计修改哪些模块，以及哪些行为必须保持不变。

第三步，实施代码修改，但对新增依赖、公共契约和数据库结构变更设置确认门槛。

第四步，修改完成后检查Git Diff，不只看代码是否更简洁，还要检查有没有超出计划的文件变化。

第五步，运行对应的单元测试、契约测试和静态检查。

第六步，生成变更说明，列出实际修改范围、测试结果以及尚未验证的风险。

例如，一个订单查询优化任务，Agent最终提交的变更说明应该能够回答：

为什么修改这些文件？有没有改变对外响应？是否新增依赖？数据库查询行为是否变化？执行了哪些测试？

如果发现改动范围明显超出原计划，就应当重新评审，而不是因为测试通过就直接合并。

这样可以把原本隐藏在Agent执行过程中的判断，变成开发人员能够检查的证据。

九、多Agent并行开发，为什么更需要工程门禁？

如果项目已经使用多个Codex任务并行开发，还会出现额外风险。

例如，Agent A负责订单查询，Agent B负责报表接口。两个任务分别在不同Git worktree中执行。

它们可能都正确读取了各自启动时适用的AGENTS.md，但任务执行期间，团队又调整了公共接口规范。

如果两个工作区没有及时同步规则，Agent可能继续按照旧要求生成代码。

还有一种情况：两个Agent分别修改不同模块，各自的测试都通过，但合并后出现公共契约冲突。

这说明单个任务符合规则，不代表多个任务的最终组合一定符合规则。

并行场景下，更需要在合并阶段统一检查依赖、API契约和架构约束。

如果关键规则发生变化，还应明确是否要求进行中的任务重新加载规则，并在最终提交前再次验证。

多Agent可以提高代码产出速度，但不能让每个Agent自行决定最终的工程合规结果。

十、怎样快速排查一次真实的AGENTS.md违规修改？

如果已经发现Codex违反团队规范，不建议只要求它“重新认真阅读AGENTS.md”。

更有效的排查应按实际执行路径展开。

先确认当前仓库和工作目录，找出相关AGENTS.md的作用范围，检查是否存在子目录规则或相互冲突的要求。

再查看本次任务的原始指令，判断开发人员是否给出了与项目规则冲突的要求，以及Agent有没有明确指出冲突。

随后检查Git Diff，记录哪些文件被修改、哪些变化超出了任务范围。

接着核查Agent的实际执行过程：是否读取了相关规则，是否识别了公共DTO属于受保护范围，是否在修改前请求批准。

最后再检查CI和Code Review：为什么这次违规没有在合并前被自动发现？

这里要区分两种情况。

如果规则根本没有正确加载，应修复规则发现和作用范围问题。

如果规则已加载、Agent也能够解释，但仍然生成违规变更，那么重点应放在任务边界、可执行检查和审批机制上。

不能把所有问题都归结为“提示词还不够强”。

十一、用一个指标判断工程规则是否真正生效

这篇只突出一个核心指标：关键工程规则违规率。

可以定义为：

关键规则违规率 = 违反关键规则的变更数 ÷ 涉及关键规则的变更总数。

例如，一个月内有100个涉及公共API、依赖或数据库访问的变更，其中8个在提交审查时违反了团队明确规定的规则，那么违规率为8%。

这组数字只是说明统计方法，并非实际项目数据。

这里需要把“提交阶段出现违规”和“违规代码最终进入主分支”区分开。

前者反映Agent和开发流程生成违规变更的频率；后者反映CI与审核能否有效拦截。

如果增加严格的检查之后，违规提交仍然存在，但没有违规代码能够合并，说明门禁有所改善，却不能证明Agent本身已经完全遵守规则。

反过来，如果通过缩小任务范围减少违规，也要检查代码交付速度和任务完成质量是否受到不合理影响。

真正有意义的验证，是让关键规则在真实开发任务中能够被识别、被检查，并在违反时及时阻止不安全的变更。

十二、Plus和Pro怎么判断？

如果日常主要使用ChatGPT、Codex维护单个项目，编写AGENTS.md、检查代码规范、执行单元测试和修改少量模块，Plus通常够用。

如果需要长期维护大型代码仓库，开展多个Agent并行开发，分析跨模块变更、API契约、架构约束和复杂CI流程，并持续进行多轮代码审查与回归验证，Pro更适合高频、长任务的工程工作流。

但需要明确，Pro并不意味着Agent一定不会违反AGENTS.md。

套餐主要影响可用能力和使用资源，不能代替项目规则设计、代码访问权限、CI门禁和人工审核。

团队最终需要判断的，不只是Agent能一次完成多少代码，而是它生成的变更能否稳定满足工程要求。

最后

Agent明明读了AGENTS.md，为什么改完代码还是违反团队规范？

因为项目规则被读取，不代表所有规则都已经被正确理解、持续应用并强制验证。

规则可能缺少明确范围，也可能与任务目标产生冲突；Agent为了完成局部优化，还可能扩大修改范围，影响公共契约和其他业务模块。

真正可靠的工程路径是：

明确规则作用范围 → 定义修改边界 → 给出正确实现路径 → 设置高风险审批 → 将关键约束转成CI检查 → 审查变更证据 → 验证违规率。

随着ChatGPT、Codex越来越擅长理解代码和执行复杂任务，工程团队需要关注的重点，也会从“Agent能不能写代码”，转向“Agent生成的代码能不能被可靠约束”。

AGENTS.md仍然很有价值，但它应该是工程治理的起点，而不是最后一道防线。

真正成熟的AI编程工作流，不是要求Agent永远不犯错，而是让关键错误能够被发现、被阻止，并且不会在无人确认的情况下进入生产系统。

持续分享 Codex、大模型开发与 AI 编程实战内容

也整理了稳定的 Plus/Pro 会员订阅渠道，有需要可自取。