Taming Codex with AGENTS.md: Project‑Level Context Governance

Why AGENTS.md Is Needed

AI coding assistants frequently make mistakes such as altering unrelated code, executing the wrong package manager command, placing files in incorrect directories, importing external dependencies that replace existing wrappers, and ignoring established project conventions. The common root cause is that the model lacks knowledge of the project's specific conventions, toolchain, and structure.

Over 60 k open‑source repositories already use AGENTS.md, and more than 20 AI coding tools support it natively. An arXiv paper (2601.20404, 2026) evaluated 124 real pull requests and found that having an AGENTS.md file reduced median runtime by 28.6 % and token usage by 16.6 %.

A practical approach: let the AI generate a basic framework first, then have a human fine‑tune the core business rules.

Practical AGENTS.md Template

The following template can be copied and filled with project‑specific information. It emphasizes concise, verifiable rules and avoids unnecessary verbosity.

# AGENTS.md

{1~2 sentences introducing the project}

## 基础规则

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

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

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

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

## 常用命令
- 安装依赖：{如 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`}
- {wx.showModal 的 confirmText 不超过 4 个字符，否则弹窗会失败}

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

Loading Order of AGENTS.md

AGENTS.md can exist at multiple levels. When Codex starts, it merges files in the following order:

Global level : reads ~/.codex/AGENTS.md. If AGENTS.override.md exists, it replaces the global file.

Project level : starting from the Git root, each directory up to the current working directory is checked for AGENTS.md (or AGENTS.override.md).

Merge order : files are merged from the root toward the current directory; later files overwrite earlier ones.

The total merged size is limited to 32 KiB ; content beyond this limit is truncated. The limit can be increased via the project_doc_max_bytes setting.

Cross‑Tool Compatibility

OpenAI Codex – supports global + project two‑layer merge.

GitHub Copilot – native support for AGENTS.md since August 2025.

Cursor – native support.

Windsurf – native support.

Kilo – native support.

OpenCode – native support.

Augment Code – native support.

Devin – native support.

A single AGENTS.md works for most mainstream AI‑Agent tools; Claude‑based tools use CLAUDE.md instead.

Final Thoughts

AGENTS.md is not a silver bullet; keep it concise (preferably under 500 lines) and include only essential requirements. Detailed specifications can be referenced from separate documents. When paired with Codex’s strong instruction‑following ability, a well‑crafted AGENTS.md can significantly boost productivity.

Real‑world items naturally emerge during daily use—addressing pain points after they appear is often more effective than pre‑emptively stuffing the file with constraints.

Karpathy’s criticism of AI coding tools highlights that models make unchecked assumptions, fail to surface inconsistencies, and do not push back when needed. Providing explicit project context via AGENTS.md helps mitigate these shortcomings.