摘要

使用 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 Diff

git 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 审查方法。

参考资料

1. OpenAI Developers：Custom instructions with AGENTS.md。

2. OpenAI Developers：Codex Best Practices。

3. OpenAI Developers：Codex Customization。

4. OpenAI Developers：Codex CLI。