Codex总是改错项目规则？AGENTS.md这5项必须写清楚

摘要Codex能够读取项目文件并修改代码但如果不了解目录结构、技术栈、测试命令和禁止修改范围就容易改错文件、引入无关依赖。本文整理AGENTS.md中最应该写清楚的5类规则并提供一份可直接参考的配置模板。使用Codex修改简单函数时通常不需要太多额外配置。但当任务变成项目级修改后问题就会逐渐出现明明使用pnpmCodex却运行npm安装依赖只要求修改后端却顺手调整了前端目录项目已经有公共组件它又重新写了一套修改代码后没有运行测试为了解决一个小问题引入了新的第三方库原有接口不能变它却调整了返回结构。这些问题不一定是Codex不会写代码而是它没有提前知道项目规则。对于需要反复使用Codex的项目可以在仓库中添加一个AGENTS.md文件把目录结构、测试命令、代码规范和修改边界固定下来。OpenAI官方文档将AGENTS.md描述为面向编程智能体的项目说明文件。Codex会在开始任务前读取其中的内容并把这些规则作为后续操作的长期指导。一、先写清楚项目目录和文件边界Codex能够搜索项目文件但它并不知道每个目录在业务中的真实作用。例如一个常见项目可能包含src/ api/ components/ pages/ services/ utils/ server/ tests/ scripts/开发者看到这些目录通常能根据经验判断pages存放页面services处理业务逻辑api负责接口请求tests存放测试scripts属于维护工具。但Codex未必知道项目内部的具体约定。如果不写清楚它可能把业务逻辑放进页面组件也可能在工具目录中创建正式功能代码。AGENTS.md中可以这样写## 项目目录 - src/pages页面组件只处理页面展示和交互。 - src/services核心业务逻辑。 - src/api接口请求封装。 - src/components公共组件新增组件前先检查是否已有可复用实现。 - tests测试文件不要为了让测试通过而修改原有断言。 - scripts维护脚本不允许放入正式业务逻辑。如果某些目录不能修改也要明确说明- 不要修改dist、vendor和generated目录。 - 未经要求不要修改数据库迁移文件。 - 不要调整生产环境配置。规则越具体Codex越不容易把一个小任务扩大成全项目修改。二、写清楚技术栈和依赖管理方式很多项目问题并不是代码逻辑错误而是Codex按照错误版本生成了代码。例如项目使用Vue 2它却按照Vue 3编写项目使用Java 8它生成了高版本语法项目使用Python 3.10它调用了新版本接口项目使用pnpm它却生成npm命令项目已经固定依赖版本它又安装最新版。所以AGENTS.md应该明确项目技术栈## 技术栈 - Node.js 20 - TypeScript 5 - React 18 - Vite - pnpm - Jest还要说明依赖规则## 依赖规则 - 统一使用pnpm不要使用npm或yarn。 - 未经确认不要新增生产依赖。 - 优先使用项目现有工具库。 - 不要随意升级依赖版本。 - 新增依赖前先说明用途和替代方案。这样做能够减少Codex为了快速完成任务随意引入新框架或工具库的情况。三、写清楚构建、测试和检查命令Codex修改完代码后是否会执行正确的测试很大程度上取决于你有没有提供明确命令。OpenAI官方建议在AGENTS.md中加入项目运行方式、构建命令、测试命令、代码检查和完成标准让Codex知道怎样验证修改结果。例如## 常用命令 安装依赖 pnpm install 启动开发环境 pnpm dev 运行单元测试 pnpm test 运行代码检查 pnpm lint 运行类型检查 pnpm typecheck 生产环境构建 pnpm build还可以根据修改类型规定必须执行的命令## 修改后检查 - 修改TypeScript文件后运行pnpm typecheck。 - 修改业务逻辑后运行相关单元测试。 - 修改公共组件后运行pnpm lint。 - 修改构建配置后运行pnpm build。 - 如果测试无法运行必须说明原因不要直接声称任务完成。最后这一条非常重要。有时Codex会完成代码修改但因为环境或依赖问题没有真正运行测试。如果没有明确要求它可能只根据代码推断结果。四、写清楚代码规范和禁止事项“保持代码整洁”这种规则过于模糊对Codex帮助有限。更有效的方式是把团队真实使用的规范写出来。例如## 代码规范 - 使用TypeScript严格模式。 - 优先使用函数组件和Hooks。 - 一个函数只处理一个主要职责。 - 保持现有命名风格。 - 公共接口返回结构不得随意修改。 - 错误信息需要保留必要上下文。 - 不要删除已有日志和权限校验。禁止事项也要单独写## 禁止事项 - 不要为了减少代码行数删除异常处理。 - 不要大范围格式化无关文件。 - 不要顺便重构与当前任务无关的模块。 - 不要把密码、Token或API Key写进代码。 - 不要使用any绕过TypeScript错误。 - 不要通过修改测试预期掩盖业务错误。很多人只告诉Codex“应该做什么”却没有告诉它“哪些事情绝对不能做”。在项目级任务中禁止事项往往比普通建议更重要。五、写清楚什么情况下才算完成如果只要求“完成用户登录功能”Codex对“完成”的理解可能只是代码已经写出来。但开发者真正需要的完成标准可能包括页面可以提交后端能够校验参数登录成功后返回Token登录失败时返回正确错误信息权限中间件正常工作单元测试通过原有功能没有受到影响。OpenAI官方建议在提示词或AGENTS.md中明确“Done when”也就是任务结束时必须满足的条件。可以这样写## 完成标准 任务只有满足以下条件才能标记为完成 - 代码已经完成修改。 - 相关测试已经运行并通过。 - lint和类型检查没有新增错误。 - 没有修改任务范围之外的文件。 - 没有新增未经允许的依赖。 - 最终回复需要列出修改文件和验证结果。还可以要求Codex在任务结束时给出固定格式完成后请说明 1. 修改了哪些文件 2. 每个文件修改了什么 3. 执行了哪些测试 4. 是否存在未解决问题 5. 哪些位置需要人工检查。这样能减少“代码已经生成但不知道到底改了什么”的情况。一份可直接参考的AGENTS.md模板下面是一份比较精简的版本# AGENTS.md ## 项目说明 这是一个React、TypeScript和Node.js项目。 前端代码位于src目录后端代码位于server目录。 ## 目录规则 - src/pages页面组件。 - src/components公共组件。 - src/services业务逻辑。 - src/api接口请求。 - server后端接口。 - tests测试文件。 不要修改dist、vendor和生产环境配置文件。 ## 开发规范 - 使用pnpm。 - 保持现有代码风格。 - 优先复用已有组件和工具函数。 - 不要随意修改公共接口返回结构。 - 不要新增未经确认的生产依赖。 - 不要进行与当前任务无关的重构。 ## 安全要求 - 不要在代码中写入密码、Token和API Key。 - 不要删除权限校验、参数校验和异常处理。 - 涉及用户数据的接口必须检查权限。 ## 验证命令 - pnpm lint - pnpm typecheck - pnpm test - pnpm build 如果无法运行某项命令必须说明具体原因。 ## 完成标准 - 只修改任务相关文件。 - 相关测试通过。 - 没有新增类型错误和lint错误。 - 最终列出修改文件、测试结果和潜在风险。这份模板不需要原样复制。真正有效的AGENTS.md应该根据自己的项目调整而不是堆积大量通用规则。AGENTS.md是不是写得越长越好不是。OpenAI官方建议保持AGENTS.md简短、准确优先记录每次任务都需要遵守的规则如果内容过多可以把不同目录的规则拆开放置距离当前工作目录更近的文件拥有更高优先级。AGENTS.md写得太长容易出现三个问题重要规则被大量说明淹没不同规则互相冲突项目变化后内容没有及时更新。更合理的方法是先写最重要的10到20条规则。当Codex重复犯同一个错误时再把这条规则补充进去。为什么写了AGENTS.md还是不生效常见原因包括1. 文件放错位置项目级AGENTS.md通常放在仓库根目录。针对特定子目录的规则可以放在对应目录下。2. 存在覆盖文件如果目录中存在AGENTS.override.md它可能会覆盖同级普通规则。3. 规则描述过于模糊例如写高质量代码。这类要求没有可执行标准。应该改成具体的测试、命名、依赖和修改边界。4. 规则互相冲突根目录要求使用npm子目录又要求使用pnpmCodex会按照距离当前目录更近的规则执行。5. 文件内容已经过时项目升级了框架或修改了测试命令但AGENTS.md没有同步更新Codex就会继续按照旧规则操作。可以让Codex总结当前加载的规则检查它是否读取了正确文件。官方文档也提供了从仓库目录验证活动指令来源的方法。总结Codex总是改错项目规则不一定是模型理解能力不足也可能是项目没有提供稳定、明确的开发约束。AGENTS.md最应该写清楚的5项内容是项目目录和修改边界技术栈和依赖管理构建、测试与检查命令代码规范和禁止事项任务完成与验证标准。一个好的AGENTS.md不需要特别长但必须具体、真实并且可以执行。与其每次都在提示词里重复“不要乱改文件、记得运行测试”不如把这些长期规则写进项目让Codex每次开始任务前都能获得相同的开发要求。