摘要：Codex能够读取项目文件并修改代码，但如果不了解目录结构、技术栈、测试命令和禁止修改范围，就容易改错文件、引入无关依赖。本文整理AGENTS.md中最应该写清楚的5类规则，并提供一份可直接参考的配置模板。

使用Codex修改简单函数时，通常不需要太多额外配置。

但当任务变成项目级修改后，问题就会逐渐出现：

• 明明使用pnpm，Codex却运行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，子目录又要求使用pnpm，Codex会按照距离当前目录更近的规则执行。

5. 文件内容已经过时

项目升级了框架或修改了测试命令，但AGENTS.md没有同步更新，Codex就会继续按照旧规则操作。

可以让Codex总结当前加载的规则，检查它是否读取了正确文件。官方文档也提供了从仓库目录验证活动指令来源的方法。

总结

Codex总是改错项目规则，不一定是模型理解能力不足，也可能是项目没有提供稳定、明确的开发约束。

AGENTS.md最应该写清楚的5项内容是：

• 项目目录和修改边界；
• 技术栈和依赖管理；
• 构建、测试与检查命令；
• 代码规范和禁止事项；
• 任务完成与验证标准。

一个好的AGENTS.md不需要特别长，但必须具体、真实并且可以执行。

与其每次都在提示词里重复“不要乱改文件、记得运行测试”，不如把这些长期规则写进项目，让Codex每次开始任务前都能获得相同的开发要求。