AGENTS.md 指南 · Codex 橙皮书

10.1 一段对话引出 AGENTS.md

你：写一段函数，把用户输入的字符串转成驼峰命名。
Codex：好的，给你 Python 版本：
       def to_camel_case(s: str) -> str:
           ...

你：不是 Python，我要 TypeScript。

Codex：抱歉，给你 TypeScript：
       function toCamelCase(s: string): string {
           ...
       }

你：函数名我们项目用下划线风格，叫 to_camel_case。

Codex：明白，改成：
       function to_camel_case(s: string): string {
           ...
       }

每次都要重复说"我用什么语言、什么风格、什么规范"，烦不烦？

烦。

AGENTS.md 就是用来终结这种重复的。

10.2 什么是 AGENTS.md

AGENTS.md 是一份"AI 的岗位说明书"，放在项目根目录，Codex 启动时会自动读取。

把你每次都要重复的话写进去——技术栈、风格、规范、约定、目录结构、运行命令——之后 Codex 自动遵循，不用你再说。

它跟 README.md 的区别是：

	README.md	AGENTS.md
受众	人	AI
内容	介绍项目	指挥 AI 怎么做事
风格	美观、可读	结构化、明确、可执行
长度	看情况	越精炼越好

它跟 Memory 的区别是：

	Memory	AGENTS.md
范围	全局 + 个人	项目 + 团队
存储	`~/.codex/memory.md` 或 `.codex/memory.md`	`<project>/AGENTS.md`
是否提交 git	不提交（个人偏好）	提交（团队共享）
加载方式	自动	自动

简单记：Memory 记"我"，AGENTS.md 记"项目"。

10.3 AGENTS.md 的三层加载机制

Codex 读取 AGENTS.md 是有层次的：

┌──────────────────────────────────────────────┐
│ 第 1 层：~/.codex/AGENTS.md                  │
│ ── 全局默认（你个人在所有项目通用的）          │
└──────────────────────────────────────────────┘
                    │ 合并
                    ▼
┌──────────────────────────────────────────────┐
│ 第 2 层：<project>/AGENTS.md                 │
│ ── 项目级（团队共享的）                        │
└──────────────────────────────────────────────┘
                    │ 合并
                    ▼
┌──────────────────────────────────────────────┐
│ 第 3 层：<project>/<subdir>/AGENTS.md        │
│ ── 子目录级（针对某个模块的特殊规则）          │
└──────────────────────────────────────────────┘
                    │
                    ▼
                Codex 看到的"完整指令"
                （后面的覆盖前面的）

上限规则

上限 32KB：三层合并后总大小不能超 32KB（约 1 万字符）。超了 Codex 会提示。
加载顺序：从你当前 cwd 一层层往上找，直到 home 目录。
覆盖规则：后加载的覆盖先加载的（同字段）。

实例

假设你在 ~/codex-workspace/projects/my-blog/posts/ 启动 Codex：

~/.codex/AGENTS.md                           ← 加载
~/codex-workspace/AGENTS.md                  ← 不存在，跳过
~/codex-workspace/projects/AGENTS.md         ← 不存在，跳过
~/codex-workspace/projects/my-blog/AGENTS.md ← 加载
~/codex-workspace/projects/my-blog/posts/AGENTS.md ← 加载（如果有）

最终 Codex 看到的是三份合并后的内容。

10.4 一份合格的 AGENTS.md 长什么样

必备六大部分

OpenAI 官方推荐的结构：

# Project Name

## 1. Project Overview
（项目是什么、目的是什么、给谁用）

## 2. Tech Stack
（用了什么技术、版本号）

## 3. Project Structure
（重要目录、关键文件在哪）

## 4. Common Commands
（常用命令：装、跑、测、构建）

## 5. Conventions
（代码规范、命名规范、提交规范）

## 6. Boundaries
（必须做什么、问之前不能做什么、绝对不能做什么）

每一部分都有具体写法，下面分别讲。

1. Project Overview

简单写清楚：

## Project Overview

这是一个个人博客项目，基于 Astro 构建。
- 受众：技术读者
- 部署：Vercel，自动部署
- 域名：blog.example.com
- 运营周期：2024 年至今，每周 1-2 篇

不用花哨，让 Codex 知道"在做什么、为谁做、什么状态"。

2. Tech Stack

带版本号很关键，否则 Codex 可能用旧 API：

## Tech Stack

- Runtime: Node.js 22
- Framework: Astro 5.0
- Styling: Tailwind CSS 4.0
- Package Manager: pnpm 9
- Deployment: Vercel

3. Project Structure

重点目录，不用列全：

## Project Structure

my-blog/ ├── src/ │ ├── pages/ # 路由（每个 .md 自动成为一个页面） │ ├── components/ # React 组件 │ ├── layouts/ # 页面布局 │ └── content/ # 文章内容 ├── public/ # 静态资源 └── astro.config.mjs # Astro 配置


新增页面：在 src/pages/ 下放 .md 或 .astro 文件
新增组件：在 src/components/ 下放 .tsx 文件
新增文章：在 src/content/posts/ 下放 .md 文件，front-matter 必须有 title、date、tags

4. Common Commands

完整命令 + flag，Codex 不用再猜：

## Common Commands

```bash
# 安装依赖
pnpm install

# 开发模式（默认 4321 端口）
pnpm dev

# 构建生产版本
pnpm build

# 预览构建结果
pnpm preview

# 运行测试
pnpm test

# 代码格式化
pnpm format

# Lint
pnpm lint


### 5. Conventions

```markdown
## Conventions

### 代码风格
- TypeScript 严格模式
- 缩进 2 空格
- 字符串用单引号
- 不用 emoji

### 命名
- 组件文件：PascalCase（Button.tsx）
- 工具函数：camelCase（formatDate.ts）
- CSS 类：kebab-case

### Git Commit
遵循 Conventional Commits：
- feat: 新功能
- fix: 修 bug
- docs: 文档
- style: 样式
- refactor: 重构
- test: 测试
- chore: 杂项

提交信息中文，但前缀英文：
`feat: 添加文章标签筛选功能`

6. Boundaries

这一部分最关键，决定了 Codex 行为的边界：

## Boundaries

### Always（必须做）
- 改代码前看一下相关文件的当前内容
- 改完跑 `pnpm lint` 和 `pnpm test`
- commit message 用中文，遵循 Conventional Commits

### Ask First（先问我）
- 安装新依赖
- 改 package.json 的 scripts
- 删除任何文件
- 改 astro.config.mjs

### Never（绝对不做）
- 不要直接 push 到 main 分支
- 不要把 .env 文件提交到 git
- 不要在 src/content/posts/ 下生成 mock 文章
- 不要用 npm，必须用 pnpm

10.5 一个完整的 AGENTS.md 例子

下面是一个写给"个人博客项目"的完整 AGENTS.md：

# My Blog

## Project Overview

个人技术博客，基于 Astro 构建，每周更新 1-2 篇文章。
- 受众：中文技术读者
- 部署：Vercel 自动部署 main 分支
- 域名：blog.example.com

## Tech Stack

- Node.js 22
- Astro 5.0
- Tailwind CSS 4.0
- pnpm 9
- Vercel（部署）

## Project Structure

. ├── src/ │ ├── pages/ # 路由 │ ├── components/ # 组件 │ ├── layouts/ # 布局 │ └── content/posts/ # 文章 ├── public/ # 静态资源 └── astro.config.mjs


## Common Commands

```bash
pnpm install      # 安装依赖
pnpm dev          # 开发（4321 端口）
pnpm build        # 构建
pnpm preview      # 预览构建
pnpm format       # 格式化
pnpm lint         # Lint
pnpm test         # 测试

Conventions

文章 Front-matter（必须）

---
title: 文章标题
date: 2026-04-19
tags: [标签1, 标签2]
description: 一句话描述（≤ 80 字）
---

代码风格

TypeScript 严格模式
缩进 2 空格，单引号
不用 emoji
函数：camelCase；组件：PascalCase

Git Commit

Conventional Commits（feat/fix/docs/...）
Message 用中文
例：feat: 添加文章标签筛选功能

Boundaries

Always

改代码前先看相关文件
改完跑 lint + test
新文章放 src/content/posts/
文章 front-matter 必须完整

Ask First

装新依赖
改 astro.config.mjs
改 package.json scripts
删任何文件

Never

不要 push 到 main（用 PR）
不要提交 .env
不要 mock 文章内容
不要用 npm（必须 pnpm）

Verification

完成任何任务后，按这个清单自检：

pnpm lint 通过
pnpm build 成功
如果改了文章，预览页面渲染正常
Commit message 符合规范


这份 AGENTS.md 大概 1.5KB，提交到 git。任何人（你、同事、Codex）打开这个项目，都立刻"懂规矩"。

## 10.6 AGENTS.md 的几种典型场景

### 场景 1：纯写作项目（没代码）

```markdown
# 我的小红书账号内容仓库

## 项目目的
管理小红书账号的内容选题、草稿、发布记录。

## 目录结构
- topics/      # 选题库
- drafts/      # 草稿
- published/   # 已发布
- assets/      # 图片素材

## 写作规范
- 标题 ≤ 20 字，情绪锚点必须有
- 正文分段，每段 ≤ 3 行
- 第一段必须有钩子
- 结尾有 CTA（关注/收藏/评论）

## Commands
（无需命令，纯文字工作）

## Boundaries

### Always
- 新选题先在 topics/ 立项，编号格式：YYYY-MM-DD-标题
- 草稿命名：YYYY-MM-DD-标题.md
- 发布后挪到 published/ 并加发布日期标记

### Never
- 不要直接修改 published/ 里的内容（改了就成了新版本）
- 不要在文中编造数据，引用要标来源
- 不要用 emoji，本账号风格是"纯文字深度"

场景 2：数据分析项目

# 销售数据分析

## 数据源
- 主数据：data/sales_2024_2026.csv
- 客户表：data/customers.csv
- 商品表：data/products.csv

## 关联关系
- sales.customer_id → customers.id
- sales.product_id → products.id

## 数据规范
- 金额单位：人民币元
- 日期格式：YYYY-MM-DD
- 缺失值：用 NaN，不用 0

## Tech Stack
- Python 3.12
- pandas 2.x
- matplotlib + seaborn

## Common Commands
```bash
# 启动 Jupyter
jupyter notebook

# 跑分析脚本
python analysis/main.py

# 生成报告
python report/generate.py

Boundaries

Always

任何数据清洗操作都生成新文件，不覆盖原始 csv
输出图表统一放 output/ 目录
大数据集（>1GB）先抽 1% 试跑

Never

不要修改 data/ 下的原始文件
不要把客户姓名写到任何输出文件
不要 print 完整 DataFrame（数据可能很大）


### 场景 3：Web 应用项目

省略，跟前面博客的例子类似，加上前后端分工、API 规范等。

## 10.7 全局 AGENTS.md 的写法

`~/.codex/AGENTS.md`（全局，所有项目通用）适合写：

```markdown
# 我的全局偏好

## 操作系统
- macOS Sonoma
- 终端：iTerm2 + zsh
- 编辑器：VS Code

## 通用偏好
- 回复用中文
- 不用 emoji
- 解释技术问题：先结论，再细节
- 给代码示例时：先简短版，我说"详细"再展开

## 安全
- 任何 `rm -rf` 命令必须先问我
- 任何 `git push --force` 必须先问我
- 任何 `sudo` 命令必须告诉我影响范围

## Git
- Commit 前自动跑相关文件的 lint
- Commit message 中文，前缀用 Conventional Commits
- 不要替我 push，我自己 push

## 验证
- 改完代码至少能跑 build / test
- 不能跑通的提案要标"未验证"

这份只写 1KB 左右就行，太长 Codex 反而抓不到重点。

10.8 AGENTS.md 的写作技巧

技巧 1：用命令式语句

[好]  Always run pnpm lint after changes.
[差]  It would be nice to run pnpm lint after changes.

明确的命令式比委婉表达更易执行。

技巧 2：给例子，不只给规则

[差]
组件命名要规范

[好]
组件命名规范：PascalCase + 单一职责
- 好：UserProfile.tsx, NavBar.tsx
- 差：user_profile.tsx, MyComponent.tsx, App2.tsx

例子比抽象规则更有说服力。

技巧 3：Always / Ask First / Never 三档

不要写"应该"、"建议"、"最好"——这些词 Codex 会权衡。要么 Always，要么 Never，模糊地带用 Ask First。

技巧 4：避免内部黑话

如果项目有"老王规则"、"二期方案"这种黑话，要解释一下，不然 Codex 不知道指什么。

技巧 5：定期更新

AGENTS.md 不是写完就锁死。当你发现"又要重复跟 Codex 说同一件事"时，就去更新它。

10.9 AGENTS.md 的跨工具兼容

好消息：AGENTS.md 是一个开放标准。除了 Codex，下面这些工具也支持：

Cursor（IDE）
Claude Code（CLI）
GitHub Copilot
Continue
Cody
Aider

也就是说，你写一份 AGENTS.md，所有 AI 工具都受益。

不同工具的字段优先级、扩展字段可能不同，但核心约定（Project Overview / Tech Stack / Conventions / Boundaries）是通用的。

10.10 一些常见错误

错误 1：写得像 README

太多营销语言、太多废话。Codex 不需要"激动人心的产品愿景"，它需要"具体的执行规则"。

错误 2：太长

超过 5KB 的 AGENTS.md 一般是冗余的。砍。

错误 3：自相矛盾

Always run npm install
Never use npm, use pnpm

Codex 看到这种会卡住。提交前自己读一遍。

错误 4：信息过时

去年的技术栈、半年前的目录结构、三个月前的命令——Codex 按过时信息执行就出错。

错误 5：不提交 git

新人 clone 项目，没看到 AGENTS.md，再跑一次。

10.11 实操：给你现有项目加一份 AGENTS.md

跟着做这 5 步：

第 1 步：cd 到项目根目录。

第 2 步：让 Codex 自己起草：

扫描当前项目的目录结构、package.json、主要配置文件，
帮我起草一份 AGENTS.md。包含 Tech Stack、Common Commands、
Conventions、Boundaries 四个部分。先列草稿给我审。

第 3 步：审稿调整。重点看：

Tech Stack 版本对吗？
Commands 全吗？少了 lint / test？
Conventions 是不是"应该有"但没有？
Boundaries 你接受吗？

第 4 步：保存到项目根目录：

# 让 Codex 写入
（确认权限请求后）

# 自己加到 git
git add AGENTS.md
git commit -m "docs: 添加 AGENTS.md 用于 AI 协作规范"

第 5 步：验证

开新会话：

看一下当前项目的 AGENTS.md，告诉我我们的技术栈和命名规范。

它应该能正确复述你写的内容。

10.12 本章小结

AGENTS.md = AI 的岗位说明书，放项目根目录，自动加载
三层加载：全局 → 项目 → 子目录，合并上限 32KB
六大必备部分：Overview / Tech Stack / Structure / Commands / Conventions / Boundaries
Boundaries 用 Always / Ask First / Never 三档
写得短、用命令式、给例子、定期更新
跨工具兼容（Codex / Cursor / Claude Code 都认）
5 步实操：扫描 → 起草 → 审稿 → 保存 → 验证

附录 B 提供了 4 套可直接复用的 AGENTS.md 模板，建议你 clone 一份开始改。

下一章讲一个比 AGENTS.md 更高级的概念——Skills。第十一章 · Skills 实战。

第十章 AGENTS.md 指南

10.1 一段对话引出 AGENTS.md

10.2 什么是 AGENTS.md

10.3 AGENTS.md 的三层加载机制

上限规则

实例

10.4 一份合格的 AGENTS.md 长什么样

必备六大部分

1. Project Overview

2. Tech Stack

3. Project Structure

4. Common Commands

6. Boundaries

10.5 一个完整的 AGENTS.md 例子

Conventions

文章 Front-matter（必须）

代码风格

Git Commit

Boundaries

Always

Ask First

Never

Verification

场景 2：数据分析项目

Boundaries

Always

Never

10.8 AGENTS.md 的写作技巧

技巧 1：用命令式语句

技巧 2：给例子，不只给规则

技巧 3：Always / Ask First / Never 三档

技巧 4：避免内部黑话

技巧 5：定期更新

10.9 AGENTS.md 的跨工具兼容

10.10 一些常见错误

错误 1：写得像 README

错误 2：太长

错误 3：自相矛盾

错误 4：信息过时

错误 5：不提交 git

10.11 实操：给你现有项目加一份 AGENTS.md

10.12 本章小结