---
title: "04 · 为什么 AGENTS.md 能改变 Codex 行为"
description: "面向新手解释 AGENTS.md 为什么能让 Codex 更稳定：它是项目和 Agent 的协作接口。"
canonical: "https://xiangyugongzuoliu.com/openai-codex-agents-md-guide"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

`AGENTS.md` 能改变 Codex 行为，是因为它把“每次都要重复交代的话”变成了任务开始前就会进入上下文的项目规则。

> [!TIP]
> 下个月仍然有效的规则写进 `AGENTS.md`；只对这次任务有效的细节写进 prompt。

<Cards>
  <Card title="AGENTS.md" href="https://developers.openai.com/codex/guides/agents-md">
    官方说明如何发现、合并和使用 `AGENTS.md`。
  </Card>
  <Card title="Rules" href="/docs/codex/official/02-config-security/05-project-rules">
    项目规则页讲全局、项目、嵌套和排障。
  </Card>
  <Card title="Context engineering" href="/docs/codex/understanding/context-engineering">
    `AGENTS.md` 是长期上下文，不是一次性任务说明。
  </Card>
</Cards>

## 它本质上是接口

```mermaid
flowchart LR
    Repo["项目事实"] --> Agents["AGENTS.md"]
    Team["团队约束"] --> Agents
    Agents --> Codex["Codex 行为"]
    Codex --> Work["读文件 / 改代码 / 跑验证"]
```

README 主要解释项目给人看。`AGENTS.md` 主要约束 Agent 怎么干活。两者互补，不互相替代。

没有项目规则时，Codex 只能猜包管理器、目录职责、测试命令和禁止事项。有了 `AGENTS.md`，它能先知道项目真实约定，再开始做事。

## 发现顺序

Codex 启动时会构建 instruction chain。官方规则可以理解成三层：

1. Global scope：Codex home 下的 `AGENTS.override.md` 或 `AGENTS.md`。
2. Project scope：从项目根一路到当前目录，逐层读取 `AGENTS.override.md`、`AGENTS.md` 或配置里的 fallback 文件名。
3. Merge order：越靠近当前工作目录的规则越晚进入上下文，因此更能覆盖上层规则。

这意味着：

- 全局文件适合个人稳定习惯。
- 根目录文件适合全仓共同规则。
- 子目录文件适合模块规则。
- override 文件适合临时强覆盖，但不能滥用。

## 什么该写进去

适合写：

- 项目用途。
- 技术栈。
- 包管理器。
- 目录职责。
- 启动、测试、构建、lint 命令。
- 禁止事项。
- 受保护路径。
- 验收要求。

不适合写：

- 本次任务细节。
- 临时想法。
- 长篇背景。
- 密钥、账号、私有 token。
- 没稳定下来的个人偏好。
- 与现有规则冲突的模板。

如果你第二次对 Codex 纠正同一个问题，这就是写进规则的信号。

## 三层内容

第一层是事实：项目用什么技术栈、哪个包管理器、哪些目录做什么、哪些命令能验证。

第二层是约束：哪些文件不要碰，哪些操作不能默认做，哪些高风险逻辑必须先确认。

第三层是验收：改完要跑什么检查，无法验证时要怎么说明，最终交付应该包含哪些证据。

只有事实，没有约束，就是说明书。只有约束，没有事实，就是口号。没有验收，就无法判断完成。

## 新手第一次怎么写

不要追求完整。先写六块：

- 项目概况：一句话说明项目做什么。
- 目录职责：列关键目录，不要逐文件注释。
- 开发命令：只列启动、测试、构建、lint。
- 编码规则：写具体可执行的约定。
- 禁止事项：写不能碰的路径、命令和依赖。
- 验收要求：写不同改动类型怎么检查。

写法要具体。“代码要优雅”没有用，因为 Codex 无法验证。“修改 API handler 后运行某个测试命令”有用，因为它能执行。

## 怎么维护

`AGENTS.md` 不是一次写完的文档。它应该随着项目和团队实践迭代。

每次 Codex 犯错后，先判断是任务没写清，还是项目规则缺失。只有会反复出现的问题，才沉淀到 `AGENTS.md`。

团队项目里，`AGENTS.md` 应该像代码一样走 review。它改变的是所有 Agent 进入项目后的行为，不能随手改。

如果文件越来越长，先删除低价值说明，再把局部规则拆到更靠近对应目录的位置。

## 新手常见坑

- 把 README 复制进去：人类介绍太长，Agent 规则不够清楚。
- 写一堆抽象要求：无法验证，无法稳定执行。
- 把任务模板塞进去：每次任务不同，应该写 prompt。
- 把密钥、账号、私有 URL 写进去。
- 规则互相冲突：根目录说用 pnpm，子目录又让用 npm。
- 没有验收要求：Codex 只会说“完成了”。

## 怎么验收

让 Codex 只读总结当前加载到的规则。它应该能复述项目用途、命令、禁止事项和验收要求。

给一个小任务，看它是否先读相关文件、是否只改允许范围、是否按规则跑验证。

检查最终回复是否包含改动文件、验证结果、未验证项和剩余风险。

如果这些没有发生，优先改 `AGENTS.md` 的具体性，而不是继续堆更多提示词。

## 官方资料

- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Rules](https://developers.openai.com/codex/rules)
- [Project instructions discovery](https://developers.openai.com/codex/config-advanced#project-instructions-discovery)
