Codex 项目级上下文治理：用 AGENTS.md 规范 AI 编程项目规则

在使用 AI 编码工具时，你是否遇到过这些问题：

• 改了不该改的代码——让它加个按钮，它顺手把 API 封装层"重构"了
• 执行了错误的命令——它用 npm install 但项目用的是 pnpm，用 mvn 构建但项目用的是 gradle
• 文件放错位置——不按照现有项目结构，随意创建文件
• 引入外部依赖替代已有封装——项目有统一的 request.ts、time.ts，AI 每次都用新方式
• 无视项目约定的模式——代码风格与项目不一致

这些问题的共同根因是：AI 不知道你的项目有什么约定、工具链和结构。AGENTS.md 就是用来填补这个空白的——一份给 AI 读的项目说明书。

为什么需要 AGENTS.md？

已有超过 60,000 个开源仓库在使用 AGENTS.md，被 20 多种 AI 编码工具原生支持。

2026 年初的一项研究（arXiv 2601.20404）在 124 个真实 PR 上测试发现，使用 AGENTS.md 后：

• 中位运行时间减少 28.6%
• 输出 token 减少 16.6%

需要注意的是，AI 自动生成的 AGENTS.md 容易包含过多冗余约束，效果反而不如手写的精简版本。内容质量是关键——根据项目实际情况，明确写出技术栈、目录结构、命名规范等，能让 AI 的行为更加清晰、可预测。

实用做法：先让 AI 生成基础框架，再由人工针对核心业务规范进行微调。

AGENTS.md 实战模板

以下模板替换成项目实际信息后可直接使用：

# AGENTS.md

{1 ~ 2 句话介绍项目的基本情况}

## 基础规则

### 编码前先思考
实现之前，先明确说出你的假设。如果不确定，就问。如果有更简单的方案，说出来。

### 简单优先
能解决问题的最少代码。不要加没被要求的功能，不要投机的灵活性。

### 外科手术式修改
只改必须改的。不要"改进"相邻代码，不要重构没坏的东西，匹配现有风格。

### 目标驱动
把任务转化为可验证的目标：写测试→通过测试→提交。

## 常用命令
- 安装依赖：{如 pnpm install}
- 本地开发：{如 pnpm dev}
- 运行测试：{如 pnpm vitest run}
- 构建：{如 pnpm build}
- 代码格式化：{如 pnpm format}
- 代码检查：{如 pnpm lint}

## 技术栈
- 后端：{语言/框架/版本，如 Go 1.26.0、Java 21 + Spring Boot 3}
- 前端：{框架/版本，如 Next.js 16 + React 19}
- 数据库：{如 PostgreSQL 16、MySQL 8}
- 包管理：{如 pnpm、mvn、gradle}

## 目录结构
- backend/src/main/java/com/example/{module}/ — DDD 分层：adapter → application → domain → infrastructure
- apps/web/src/ — 前端应用，按模块划分
- docs/specs/ — 规范文档目录

## 重要约束
- {金额计算统一使用 utils/decimal.ts，禁止浮点数直接运算}
- {新增/修改表结构必须附带迁移脚本}
- {修改配置文件前先确认，不要直接编辑 .env}

## 项目规范参考文档
- API 设计规范：docs/specs/api-guidelines.md
- 数据库规范：docs/specs/sql-guidelines.md

四条核心行为规则

1. 编码前先思考 — 防止 AI 上来就写代码。让它先说出假设，有不确定就问你。

2. 简单优先 — 最少代码解决问题。不加没被要求的功能。

3. 外科手术式修改 — 只改必须改的。不重构、不"改进"相邻代码，匹配现有风格。这条戳中太多人使用 AI 的痛点。

4. 目标驱动 — 写测试→通过测试→提交。每个任务都有可验证的终点。

Karpathy 对 AI 编程工具的核心批评：

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

—— LLM 模型会为你做出错误的假设，并且沿着这些假设运行而不会进行检查。它们不会停下来处理困惑，不会寻求澄清，不会揭示不一致之处，不会呈现权衡取舍，也不会在应该提出质疑的时候进行反驳。

AGENTS.md 的使用

Codex 加载顺序

AGENTS.md 可以分布在多个层级。Codex 每次启动时按以下顺序合并指令：

全局级别：读取 ~/.codex/AGENTS.md。如果存在 AGENTS.override.md，则替代它。

项目级别：从 Git 根目录开始，逐层向下走到当前工作目录，每层检查是否有 AGENTS.md（或 AGENTS.override.md）。

合并顺序：从根目录到当前目录，文件依次合并，靠后的覆盖靠前的。

合并内容总大小上限为 32 KiB，超过部分被截断。可通过 project_doc_max_bytes 调大。

全局 AGENTS.md 和项目 AGENTS.md 各司其职。全局的放个人偏好（通用工作协议），项目的放项目特有约束。不要把项目特有的东西塞进全局文件，也不要把个人偏好写进项目文件——否则换个项目或换台机器就出问题。

跨工具兼容性

一份 AGENTS.md 几乎适用于所有主流 AI Agent 工具。

总结

AGENTS.md 不是一个银弹，但它是目前最实用的项目级上下文治理方案。核心原则：

• 简洁为主：包含最基本的要求，总行数不要超过 500 行
• 详细规范单独引用：在 AGENTS.md 中引用详细的规范文档
• 渐进式完善：真正需要的条目会在日常使用中自然浮现，踩过坑再补比提前堆砌更有效

一份优秀的 AGENTS.md 搭配 Codex 生态，能显著提高 AI 编程的效率和质量，非常值得好好打磨。

延伸阅读

• 研究论文：arXiv 2601.20404
• Karpathy 技能框架：github.com/multica-ai/andrej-karpathy-skills