Codex 总是修改无关文件？用 AGENTS.md 建立项目规则

摘要使用 Codex 修改真实项目时不少开发者都会遇到类似问题只想修复一个页面结果它同时调整了公共组件只想修复一个 Bug却顺手重构了整个模块明明项目使用 pnpm它却生成了 npm 命令。这些问题不一定是 Codex 不会写代码更多时候是项目没有提供足够明确的工程规则。本文介绍如何使用AGENTS.md为 Codex 持久化项目结构、验证命令、修改边界和交付标准减少无关修改让 AI 编程任务更加稳定。使用 Codex 处理简单代码片段时我们通常不需要提供太多背景。例如解释这个 TypeScript 类型错误并给出修改建议。但当 Codex 进入真实项目后情况会变得完全不同。真实项目一般包含固定的目录结构统一的接口封装特定的状态管理方式已经存在的公共组件团队约定的代码风格测试、构建和代码检查命令不允许随意修改的核心模块。如果没有把这些规则告诉 Codex它只能根据当前文件和通用经验自行判断。结果可能是代码本身没有明显语法错误却不符合项目的实际约定。解决这类问题的一种有效方式就是在项目中建立AGENTS.md。一、AGENTS.md 是什么可以把AGENTS.md理解为一份专门写给编程智能体看的项目说明。OpenAI 官方将它描述为面向智能体的开放格式说明文件。Codex 会自动把其中的内容加载进上下文适合记录项目布局、运行命令、工程规范、禁止事项以及任务完成后的验证要求。普通的README.md更多是写给开发者看的通常介绍项目是什么如何安装如何启动如何部署。而AGENTS.md更适合告诉 Codex修改代码前应该先做什么哪些目录可以修改哪些文件禁止改动应该运行哪些检查什么结果才算任务完成。例如# AGENTS.md ## 项目技术栈 - Vue 3 - TypeScript - Vite - Pinia ## 目录约定 - src/api接口请求 - src/types类型定义 - src/views业务页面 - src/components公共组件 - tests测试文件 ## 修改规则 - 不新增第三方依赖 - 不修改无关业务模块 - 不改变后端接口字段 - 不全局格式化代码 - 不删除历史兼容逻辑 ## 验证命令 - npm run type-check - npm run test - npm run build有了这份文件开发者就不需要在每个任务中反复解释相同规则。二、为什么 Codex 会修改无关文件1. 任务目标过于宽泛例如帮我优化订单模块。“优化”可能包括很多事情优化性能调整目录重构组件修改接口合并重复逻辑增加缓存补充测试。如果没有进一步限制Codex 很可能扩大任务范围。更合适的写法是只修复订单列表切换筛选条件时重复请求的问题。 不要调整目录结构不要修改订单详情页也不要新增依赖。2. 项目规范没有明确记录如果项目规定所有请求必须放在src/api但这一规则没有写进文档Codex 可能直接在页面组件里调用请求。如果项目统一使用 pnpm但没有明确说明它也可能生成 npm 或 yarn 命令。3. “完成”的定义不清楚开发者说“修复完成”可能意味着Bug 已经消失类型检查通过测试通过构建通过没有无关修改。Codex 如果只理解为“代码已经改完”就可能在没有运行验证的情况下结束任务。因此项目规则中要写清楚代码生成不是任务完成验证通过并检查 Diff 后才算完成。三、AGENTS.md 应该写哪些内容一份实用的AGENTS.md不需要非常长重点是准确、明确、可执行。OpenAI 官方最佳实践建议把它用于记录仓库布局、运行方式、构建测试命令、工程约定、PR 要求、禁止规则和验收标准同时保持内容精简。1. 项目技术栈告诉 Codex 当前项目使用什么技术。## 技术栈 - React 19 - TypeScript - Vite - Zustand - Vitest这样可以减少它生成与当前框架不匹配的代码。2. 目录职责## 目录职责 - src/pages页面组件 - src/api接口封装 - src/types公共类型 - src/hooks可复用 Hooks - src/stores全局状态 - tests自动化测试目录职责越清楚Codex 越不容易把业务代码放错位置。3. 修改边界## 修改边界 - 优先修改与当前任务直接相关的文件 - 不修改未在任务中提及的业务模块 - 不主动调整路由配置 - 不修改 package.json - 不新增生产依赖 - 如需扩大范围先说明原因这里尤其建议加入如果必须扩大修改范围先说明原因不要直接修改。它可以阻止任务在不知不觉中变大。4. 代码规范## 代码规范 - 新代码必须使用 TypeScript - 优先复用现有工具函数 - 不重复实现已有公共组件 - 保持现有命名和文件组织方式 - 不进行与任务无关的格式化 - 公共函数需要补充类型说明5. 验证命令## 验证要求 修改完成后依次运行 1. npm run type-check 2. npm run lint 3. npm run test 4. npm run build 如果命令失败 - 先分析失败原因 - 判断是否由本次修改引起 - 不得通过跳过测试或关闭规则解决问题6. 交付标准## 完成标准 任务完成前必须 - 说明修改了哪些文件 - 说明每个文件的修改目的 - 报告测试和构建结果 - 检查 git diff - 确认没有无关修改 - 列出仍未解决的风险四、如何创建 AGENTS.md如果使用 Codex CLI可以通过/init命令生成一份初始AGENTS.md再根据项目真实情况修改。官方文档也强调自动生成的内容只是起点最终规则应该反映团队真实的构建、测试、审查和交付方式。也可以直接在仓库根目录手动创建touch AGENTS.md一个可以直接参考的完整版本如下# AGENTS.md ## 项目说明 这是一个基于 Vue 3、TypeScript、Vite 和 Pinia 的后台管理项目。 ## 主要目录 - src/api接口请求 - src/types类型定义 - src/views业务页面 - src/components公共组件 - src/stores状态管理 - tests测试文件 ## 工作方式 1. 修改前先分析相关调用链 2. 先给出涉及文件和修改方案 3. 优先采用最小修改原则 4. 不要主动重构无关代码 5. 修改完成后运行验证命令 6. 最后检查 Git Diff 并输出总结 ## 禁止事项 - 不新增第三方依赖 - 不修改 package.json - 不改变接口字段 - 不调整路由结构 - 不删除权限判断 - 不全局格式化代码 - 不修改当前任务以外的模块 ## 验证命令 - npm run type-check - npm run lint - npm run test - npm run build ## 完成标准 - 所有验证命令通过 - 没有无关文件变化 - 没有新增依赖 - 没有改变公开接口 - 输出修改文件、验证结果和风险说明五、大型项目可以分目录建立规则大型仓库里不同目录可能使用不同的开发规范。例如project/ ├── AGENTS.md ├── apps/ │ ├── web/ │ │ └── AGENTS.md │ └── admin/ │ └── AGENTS.md └── services/ └── payment/ └── AGENTS.override.md根目录的文件可以记录所有模块共同遵守的规则。子目录中的文件则记录当前模块的特殊要求例如# services/payment/AGENTS.override.md ## 支付模块规则 - 修改前必须先阅读支付状态机 - 不允许改变金额计算精度 - 不允许修改回调验签逻辑 - 必须运行支付模块集成测试 - 任何数据库结构变化都要先停止并说明Codex 会从项目根目录向当前工作目录查找规则并按层级合并距离当前目录更近的规则会出现在后面因此可以覆盖上层的通用指导。AGENTS.override.md可用于在某一层提供更明确的覆盖规则。这种设计很适合Monorepo前后端共用仓库多服务项目支付、权限等高风险模块不同团队共同维护的代码库。六、有了 AGENTS.md任务仍然要写清楚AGENTS.md不能替代具体任务。它负责记录长期规则当前提示词负责说明本次要做什么。推荐使用下面的任务模板任务目标 修复订单列表切换状态后重复请求的问题。 允许修改 - src/views/order/List.vue - src/api/order.ts - tests/order/List.test.ts 禁止修改 - 用户模块 - 支付模块 - 路由配置 - package.json 执行步骤 1. 先阅读 AGENTS.md 2. 分析重复请求的触发链路 3. 输出可能原因和最小修改方案 4. 修改相关文件 5. 运行项目规定的验证命令 6. 检查 Git Diff 7. 输出交付总结 验收标准 - 首次加载只请求一次 - 切换筛选条件正常重新请求 - 不改变接口字段 - 不新增依赖 - 测试和构建通过 - 没有无关修改可以简单理解为AGENTS.md管长期规则当前提示词管本次任务Git Diff 管最终结果。三者配合Codex 的任务稳定性会明显提高。七、如何检查 Codex 是否遵守规则1. 任务开始前让它总结规则开始任务前请先读取 AGENTS.md并总结本次需要遵守的规则。 暂时不要修改代码。如果总结与项目规则不一致可以在任务开始前纠正。2. 修改完成后检查 Git Diffgit status git diff --stat git diff重点检查是否修改了允许范围以外的文件是否改变了接口或公共类型是否新增了依赖是否出现大面积格式化是否删除了历史兼容逻辑是否真正运行了验证命令。3. 让 Codex 做一次规则审查请根据 AGENTS.md 审查本次 Git Diff。 输出 1. 是否违反修改边界 2. 是否存在无关修改 3. 是否改变公开接口 4. 是否新增未经允许的依赖 5. 是否完成全部验证 6. 是否达到项目定义的完成标准 先输出审查结果不要继续修改。八、AGENTS.md 也需要持续维护项目规则不是创建一次就永远不变。当 Codex 多次出现同一种问题时可以把解决经验写回AGENTS.md。例如它经常修改package.json可以补充- 未经明确允许不得修改 package.json 或 Lock 文件。如果它经常跳过完整测试可以补充- 局部测试通过后仍需运行完整类型检查和构建。官方也建议把反复出现的审查反馈写进AGENTS.md形成持续改进的反馈循环同时把规则放在最接近适用代码的目录中。不过不要把所有临时需求都塞进去。适合写入的内容是长期有效的项目规范多次重复出现的问题所有任务都应该遵守的规则高风险模块的固定限制。一次性需求仍然应该写在当前任务提示词中。九、常见误区误区一AGENTS.md 写得越长越好规则太多、太模糊反而会降低重点。应该优先保留必须遵守的限制真实可运行的命令清楚的目录职责明确的完成标准。误区二只写技术栈不写验证方式告诉 Codex 项目使用 Vue并不能保证任务完成。还要告诉它如何测试如何构建如何检查修改什么才算完成。误区三规则写了但任务范围仍然模糊AGENTS.md不能把“帮我优化项目”自动变成一个边界明确的任务。每次仍然要写清楚目标、范围和验收标准。误区四完全相信 Codex 已经遵守规则规则可以提高稳定性但不能代替测试和人工审查。最终仍然要检查 Git Diff。总结Codex 总是修改无关文件很多时候不是代码能力问题而是项目规则和任务边界没有表达清楚。AGENTS.md可以帮助开发者把长期有效的工程要求写进仓库包括项目结构目录职责修改边界禁止事项测试命令代码审查要求任务完成标准。更稳定的使用方式是用 AGENTS.md 固定长期规则用任务提示词限定当前范围用测试和 Git Diff 验证最终结果。AI 编程不是让 Codex 获得无限自由而是让它在清晰的工程规范内完成可验证的任务。当规则、任务和验证形成闭环后Codex 才更适合进入真实项目而不仅仅是生成几段代码。CSDN 文章描述Codex 总是修改无关文件怎么办本文介绍如何使用 AGENTS.md 为 Codex 建立项目规则包括目录规范、修改边界、验证命令、分层规则和 Git Diff 审查方法。参考资料OpenAI DevelopersCustom instructions with AGENTS.md。OpenAI DevelopersCodex Best Practices。OpenAI DevelopersCodex Customization。OpenAI DevelopersCodex CLI。