AGENTS.md：给 Codex 的项目说明书
这是 Codex 系列的第 6 篇。
上一篇讲 Prompt 骨架：目标、上下文、约束、验收标准。那套写法解决的是“这一次任务怎么说清楚”。
但真实项目里，你很快会遇到另一个问题：有些话不应该每次都重复。
比如这个博客项目，我每次都不想重新说：
- 文章主要用中文。
- 分类只能从受控集合里选。
- AI 文章涉及当前产品能力时，要核对官方资料。
- 不要照搬参考博客的句子和结构。
- 发布前要检查 frontmatter、摘要、标签、图片和链接。
- 不要覆盖未发布草稿或个人笔记。
这些不是某一次任务的临时要求，而是项目长期规则。长期规则继续写在 Prompt 里，会有三个问题：
- 容易漏。
- 容易前后不一致。
- 每次都占用注意力，真正的任务目标反而被埋掉。
AGENTS.md 解决的就是这件事：把反复出现的项目说明写成一个 Codex 启动时会自动读取的文件，让它在动手之前就知道这个项目怎么工作、怎么验证、哪些事情不要做。
整理日期：2026-07-05。本文涉及 Codex 的 AGENTS.md 发现顺序、作用域、覆盖规则、大小限制、验证方式等内容，主要参考 OpenAI Codex 官方文档，并结合这个博客项目当前的 AGENTS.md 实践整理。
这篇解决什么问题
读完这篇，你应该能带走四样东西：
| 产物 | 用来解决什么 |
|---|---|
AGENTS.md 判断表 |
分清哪些规则该放 Prompt，哪些该放项目说明 |
| 指令层级图 | 理解全局、项目、目录级文件如何叠加 |
| 三套模板 | 个人博客、前端项目、后端服务的 AGENTS.md 初稿 |
| 自检清单 | 写完后验证 Codex 是否真的读到了正确规则 |
这篇不会追求把 AGENTS.md 写得很大。我的目标相反：写得短、准、能维护。
1. AGENTS.md 到底是什么
你可以把 AGENTS.md 理解成“给 AI Agent 看的项目 README”。
普通 README.md 通常给人看：项目做什么、怎么安装、怎么运行、怎么贡献。
AGENTS.md 更偏向给 Codex 看：打开这个仓库之后，它应该先知道哪些目录重要、哪些命令能跑、哪些约定必须遵守、怎样才算完成、哪些事情不要碰。
OpenAI Codex 官方文档里也把 AGENTS.md 放在“让指导可复用”的位置：当一个 Prompt 模式反复有效，就不应该每次手打，而应该沉淀到项目指导里。
我会把它定位成三句话：
AGENTS.md 是项目长期上下文。
AGENTS.md 是工作边界和验收标准。
AGENTS.md 是把重复反馈变成下次默认行为的地方。
它不是万能配置文件，也不是权限系统，更不是把整份架构文档复制进去的地方。
2. 什么时候该写进 AGENTS.md
一个很简单的判断标准：
如果你已经对 Codex 说过两次，而且以后还会继续说，就考虑写进 AGENTS.md。
比如：
| 你反复说的话 | 是否适合 AGENTS.md | 原因 |
|---|---|---|
| “这个项目用 pnpm，不要用 npm install” | 适合 | 项目长期命令约定 |
| “所有 AI 文章都要核对官方文档” | 适合 | 内容生产的长期质量规则 |
| “这次只改登录页，不要碰后台” | 不适合 | 本次任务临时范围 |
| “帮我把这篇文章发布到线上” | 不适合 | 这是任务目标，不是项目规则 |
| “不要删除草稿和个人笔记” | 适合 | 项目安全边界 |
| “今天先别发布” | 不适合 | 临时状态 |
我建议先把 AGENTS.md 当作“项目的长期摩擦记录”。不是预先写一堆完美规则，而是每次发现 Codex 又踩了同一个坑，就补一条。
比如这个博客项目，一开始最容易混乱的是：
- 分类和标签不是模板自带的老分类。
- 文章风格不能照搬参考博客。
- AI 工具文章需要当前资料核对。
- 发布源、草稿源、后台数据库不是同一个概念。
这些规则如果只靠 Prompt，迟早会漏。写进 AGENTS.md，后面的每次任务都会稳一点。
3. Codex 怎么发现 AGENTS.md
这一段比较重要，因为它决定了你的规则到底会不会生效。
根据当前 Codex 官方文档，Codex 会在开始工作前读取 AGENTS.md 一类的指导文件。它会形成一条指令链，大致可以理解成三层：
| 层级 | 典型位置 | 适合放什么 |
|---|---|---|
| 全局层 | ~/.codex/AGENTS.md |
个人默认偏好，比如回复风格、review 习惯 |
| 项目层 | 仓库根目录 AGENTS.md |
项目规则，比如目录、命令、验收、不要做什么 |
| 目录层 | 子目录里的 AGENTS.md 或 AGENTS.override.md |
某个模块的局部规则 |
一个关键原则：
越靠近当前工作目录的说明越具体，优先级也越高。
比如你在 services/payments/ 下面启动 Codex，项目根目录有一份 AGENTS.md，services/payments/ 下面也有一份更具体的说明，那么支付模块的规则会更靠后进入上下文，用来覆盖更通用的规则。
官方文档里还提到几个细节：
- 全局层在 Codex home 目录下，默认是
~/.codex，除非你设置了CODEX_HOME。 - 如果存在
AGENTS.override.md，它会优先于同层的AGENTS.md。 - 项目层会从项目根目录往当前工作目录一路查找。
- 每个目录最多取一个指导文件。
- 默认会有一个合并大小限制，官方文档当前写到默认
project_doc_max_bytes是 32 KiB。 - 如果改了指导文件，需要新的运行或新的会话来重新读取，不要假设当前运行中的 Codex 会自动刷新。
这些规则的实际意义是：不要把 AGENTS.md 当成一个无边界大文档。它会进入上下文，太大、太散、太旧，都会伤害效果。
4. AGENTS.md 应该写什么
我会从 8 个模块开始写。
| 模块 | 用来回答什么 |
|---|---|
| Project Overview | 这个项目是什么，主要产物是什么 |
| Repository Map | 重要目录在哪里，哪些目录不要动 |
| Commands | 怎么安装、运行、测试、构建 |
| Workflow | 做任务时按什么流程走 |
| Coding / Content Rules | 代码、文章、接口、样式的项目约定 |
| Safety Rules | 不要执行什么，不要覆盖什么，不要发布什么 |
| Verification | 怎样算完成，必须跑哪些检查 |
| Final Output | Codex 最后应该怎么汇报 |
最小版本可以很短：
# AGENTS.md
## Project Overview
This repository is for ...
## Commands
- Install: ...
- Dev: ...
- Test: ...
- Build: ...
## Rules
- ...
## Verification
- ...
## Final Output
- Summarize changed files.
- List commands run and results.
- Note remaining risks.
一开始不要写太满。真正有用的 AGENTS.md 往往是从 30 行开始，随着项目摩擦慢慢长出来的。
5. AGENTS.md 不应该写什么
这个文件最容易犯的错，是把所有东西都塞进去。
不建议写进去的内容：
| 不该写的内容 | 为什么 |
|---|---|
| 本次任务目标 | 应该放 Prompt，不是长期规则 |
| 账号、密码、Token、私钥 | 这是安全风险 |
| 大段架构文档全文 | 会挤占上下文，且很快过期 |
| 模糊价值观 | “写得专业一点”不如写具体验收标准 |
| 不稳定的临时状态 | 比如今天先别发布、这个 bug 暂时不用管 |
| 和代码不一致的旧命令 | Codex 会按它执行，错误成本很高 |
| 大量参考资料链接 | 应该放 research note 或 Skill 的 references |
我自己的原则是：
AGENTS.md 只写“每次都希望 Codex 记住”的东西。
如果某条规则只在今天有效，就放 Prompt。
如果某条规则需要脚本、案例、检查清单和资料引用，就考虑做 Skill。
如果某条规则是命令权限或审批策略，就应该看 .codex/config.toml、rules、sandbox、approval，而不是指望一句自然语言完全约束。
6. 用 30 分钟写第一版
第一次写 AGENTS.md，不要从空白文档开始憋。
可以按这个流程走。
第一步：让 Codex 只读扫描
请先只读扫描这个项目，不要改文件。
目标：
帮我准备一份 AGENTS.md 初稿。
请重点看：
- 项目是什么类型。
- 主要目录和入口。
- package.json / README / 配置文件里的命令。
- 测试、lint、build、部署方式。
- 可能需要长期写给 Codex 的项目规则。
输出：
- 项目地图。
- 建议写进 AGENTS.md 的规则。
- 不确定的问题。
第二步：把建议分三类
Codex 输出后，不要直接全收。先分三类：
| 类型 | 处理方式 |
|---|---|
| 已确认事实 | 可以写进 AGENTS.md |
| 合理推测 | 先标注，需要你确认 |
| 一次性任务 | 不写进 AGENTS.md |
比如“项目用 Next.js”如果从 package.json、路由目录和配置文件都能确认，就可以写。
“用户偏好不要深色配图”如果是你在这个博客系列里反复提出的要求，也可以写。
“这次发布第 5 篇文章”就不要写进去。
第三步：写最小初稿
先写 6 个标题就够：
# AGENTS.md
## Project Overview
## Repository Map
## Commands
## Working Rules
## Verification
## Final Response
每节只放最确定、最常用的规则。
第四步：验证是否加载
可以让 Codex 自己总结当前加载的指令：
codex --sandbox read-only --ask-for-approval never "Summarize the current instructions."
如果你在某个子目录下有局部规则，也可以指定目录：
codex --cd services/payments --sandbox read-only --ask-for-approval never "Show which instruction files are active."
这里的目标不是跑业务命令，而是确认 Codex 读到了你想让它读的说明。
第五步：用一次真实小任务校验
比如：
请只读检查当前项目，告诉我如果要新增一篇博客文章，应遵守哪些分类、标签、图片和发布规则。
不要改文件。
如果 Codex 能复述出 AGENTS.md 里的规则，说明第一版有效。
如果它漏了关键规则，不要急着骂模型，先看规则是不是写得太散、太隐晦，或者当前会话没有重新加载。
7. 个人博客项目模板
下面是适合个人博客的 AGENTS.md 模板。这个博客当前的项目说明也基本沿着这类结构走。
# Blog Agent Guide
This repository is for a personal blog: {{BLOG_URL}}.
## Blog Positioning
- Write to leave a useful trail for future self and readers.
- Main topics: technical practice, AI tools, finance/investing notes, reading notes, and personal reflections.
- Prefer concrete experience, examples, and decisions over slogans.
## Voice
- Write primarily in Chinese unless the post itself needs English.
- Tone: calm, pragmatic, candid.
- Avoid marketing copy and hollow inspiration.
- Use first-person experience when it adds signal.
- Do not copy sentences or structure from reference blogs.
## Content Taxonomy
Each post should have exactly one primary category.
Allowed categories:
- AI 与智能体
- 工程实践
- 金融投资
- 阅读笔记
- 个人随笔
- 工具与效率
- 项目记录
Use 3-7 specific tags per post.
Avoid template/imported categories unless the content truly belongs there.
## Frontmatter
Use this shape for new Markdown posts:
```yaml
---
title: ""
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
draft: true
summary: ""
category: "AI 与智能体"
tags: ["Codex", "Agent", "工作流"]
series: ""
---
```
## Writing Rules
- Start each tutorial with the problem it solves.
- For technical posts, include commands, versions, errors, and final working state when relevant.
- For AI posts, verify current product and API facts against official sources.
- For finance posts, separate facts from personal judgment and avoid personalized investment advice.
- End with a useful checklist, next step, or remaining uncertainty.
## Image Rules
- Use images only when they clarify structure or workflow.
- Prefer light, readable diagrams for tutorial posts.
- Do not use decorative dark images when the reader needs to understand a process.
## Safety
- Do not overwrite unpublished drafts or personal notes.
- Do not publish or deploy unless explicitly asked.
- Do not store passwords, tokens, or private keys in content files.
## Verification
Before saying a post is ready:
- Check title, summary, category, tags, series.
- Check links and images.
- Check whether the reader can take away a concrete template, checklist, or exercise.
- Note any facts that still need verification.
8. 前端项目模板
前端项目的 AGENTS.md 要更关注运行方式、组件约定、样式系统和视觉验证。
# Frontend Agent Guide
## Project Overview
This is a frontend application built with ...
Primary users are ...
## Repository Map
- `src/app` or `pages`: routes and page-level components.
- `src/components`: shared UI components.
- `src/lib`: data fetching, utilities, and client helpers.
- `src/styles`: global styles and theme tokens.
- `public`: static assets.
## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Build: `pnpm build`
Verify command names against `package.json` before running them.
## UI Rules
- Reuse existing components and design tokens.
- Do not add a new UI library without explaining why.
- Keep interactive states complete: loading, empty, error, disabled.
- Check responsive behavior on desktop and mobile when editing layout.
- Avoid changing unrelated pages during a focused task.
## Data And API Rules
- Preserve existing API contracts unless the task explicitly changes them.
- Keep error handling visible to users.
- Do not hardcode production URLs or secrets.
## Verification
Before finishing:
- Run the relevant lint/typecheck/build command if available.
- For visual changes, capture or inspect the affected viewport.
- Explain any command that could not be run.
## Final Response
Report:
- Changed files.
- User-visible behavior change.
- Verification commands and results.
- Remaining risks or follow-up work.
前端模板里最重要的一句是“Verify command names against package.json before running them”。很多项目不是 npm run dev，也不是 pnpm dev，不要让 Codex 凭习惯跑错。
9. 后端服务模板
后端项目更关注数据、迁移、权限、幂等性和可观测性。
# Backend Agent Guide
## Project Overview
This service handles ...
Primary runtime: ...
Database / queue / cache: ...
## Repository Map
- `src/routes` or `controllers`: API entry points.
- `src/services`: business logic.
- `src/db` or `migrations`: database schema and migrations.
- `src/lib`: shared utilities.
- `tests`: automated tests.
## Commands
- Install: ...
- Test: ...
- Lint: ...
- Typecheck: ...
- Run locally: ...
Discover exact commands from README, Makefile, package manager files, or CI config before inventing commands.
## Engineering Rules
- Keep API compatibility unless the task explicitly asks for a breaking change.
- Validate inputs at the boundary.
- Handle errors explicitly; do not swallow exceptions silently.
- Prefer small, reviewable changes.
- Add or update tests for behavior changes.
## Data Safety
- Do not run destructive database commands without explicit approval.
- Do not delete migrations or rewrite applied migrations.
- Do not touch production credentials.
- For schema changes, explain migration and rollback impact.
## Verification
- Run targeted tests first, then broader checks if the change touches shared behavior.
- If tests require services that are not available locally, explain what was not verified.
- For bug fixes, include the reproduction path and why it no longer fails.
## Final Response
Include:
- Root cause when fixing a bug.
- Changed files.
- Tests run.
- Data or migration risk.
- Any manual verification still needed.
后端模板里要少写“尽量优化性能”这种宽泛话，多写“不要改 applied migration”“输入边界必须校验”“测试依赖服务不可用时要说明”。这些才是能减少事故的规则。
10. 什么时候用目录级 AGENTS.md
大多数个人项目，一个根目录 AGENTS.md 就够了。
需要目录级说明，通常是因为项目内部真的有不同规则：
| 场景 | 是否需要目录级说明 |
|---|---|
| 前端和后端在同一个 monorepo | 可以考虑 |
content/ 是博客内容，app/ 是应用代码 |
可以考虑 |
| 支付、权限、数据迁移有特殊安全规则 | 建议考虑 |
| 只是几个普通组件目录 | 不需要 |
| 只是为了让文件看起来更完整 | 不需要 |
比如一个 monorepo：
repo/
AGENTS.md
apps/web/AGENTS.md
services/billing/AGENTS.override.md
content/blog/AGENTS.md
根目录写通用规则，apps/web 写前端规则，services/billing 写支付服务的高风险规则，content/blog 写内容生产规则。
但不要过度拆分。目录级规则越多，维护成本越高，也更容易出现互相冲突。只有当规则真的不同，才值得拆。
11. AGENTS.override.md 怎么用
AGENTS.override.md 适合临时或局部覆盖。
比如：
services/payments/AGENTS.override.md
可以写：
# Payments Override
## Safety
- Do not rotate API keys.
- Do not run payment migration commands.
- Do not change webhook signature verification without explicit approval.
## Verification
- Use `make test-payments` for payment logic changes.
- Include idempotency and retry behavior in the final risk note.
但我不建议滥用 override。如果规则是长期稳定的模块规则，普通 AGENTS.md 就可以。如果只是你今天要临时改变行为，用 Prompt 更简单。
一个经验：
AGENTS.override.md 应该少而明确。
如果整个项目到处都是 override，说明项目规则本身需要整理。
12. AGENTS.md 和其他 Codex 能力怎么分工
这张表很重要。很多混乱来自把所有东西都写进 AGENTS.md。
| 能力 | 适合放什么 | 不适合放什么 |
|---|---|---|
| Prompt | 本次目标、临时上下文、一次性约束 | 长期项目规则 |
AGENTS.md |
repo 规则、命令、验收方式、不要做什么 | 密钥、长资料、复杂脚本 |
.codex/config.toml |
sandbox、approval、模型、MCP、hook 等配置 | 文章风格、业务规则说明 |
| Rules | 命令审批、允许、禁止策略 | 内容写作风格 |
| Skill | 可复用工作流、脚本、引用资料、检查清单 | 单个项目的一句简单规则 |
| MCP | 外部工具、私有数据、GitHub/Linear/文档系统 | 本地项目目录说明 |
如果你只是想让 Codex 每次写博客时记住分类规则，放 AGENTS.md。
如果你想让它每次 review 技术文章都按一套完整清单执行，做 Skill。
如果你想让它能访问 GitHub issue、Linear 任务、文档系统，那是 MCP 或连接器。
如果你想限制某些命令必须审批，那不是 AGENTS.md 的强项，要看规则、审批和 sandbox。
13. 如何维护 AGENTS.md
AGENTS.md 不是一次写完就永远不动。
我建议用一个很朴素的维护规则：
同一个问题出现两次，就写回 AGENTS.md。
三个月没被用到的规则，就考虑删掉。
适合写回的情况：
- Codex 又用了错误的包管理器。
- Codex 又把草稿当成发布源。
- Codex 又忽略了移动端截图。
- Codex 又把分类写成旧模板分类。
- Codex 又在 review 时只给风格建议，没有看 bug 风险。
不适合写回的情况：
- 你只是这次临时不想发布。
- 某个线上事故的临时处理方案。
- 一个还没有确认的猜测。
- 一条和项目现状不一致的旧命令。
维护时要保持克制。AGENTS.md 越长，越需要分层：
- 根目录放通用规则。
- 子目录放局部规则。
- 复杂工作流放 Skill。
- 长参考资料放 docs 或 references，再在
AGENTS.md里指路。
14. 用 Codex 反过来 review AGENTS.md
写完之后，可以让 Codex review 自己的项目说明。
请 review 当前 AGENTS.md，不要改文件。
重点检查：
- 是否有过时命令。
- 是否有无法验证的空话。
- 是否有一次性任务被写成长期规则。
- 是否遗漏项目运行、测试、构建、发布边界。
- 是否有可能冲突的规则。
- 是否太长，应该拆到子目录或 Skill。
输出：
- 必须修改。
- 建议修改。
- 可以保留。
- 建议移动到 Prompt / config / rules / Skill 的内容。
这一步很有用。因为人写 AGENTS.md 时容易把自己的习惯当成项目规则。让 Codex 反过来审一遍，能发现很多“写了但不执行”的句子。
15. 30-60 分钟练习
如果你想把这篇用起来，可以今天就做一个小练习。
第一步：选一个真实项目
最好选你最近正在用的项目，不要选完全陌生的开源仓库。
第二步：让 Codex 只读扫描
用前面第 6 节的 Prompt，让它输出 AGENTS.md 初稿建议。
第三步：手动筛选
只保留这些内容：
- 已确认的目录结构。
- 已确认的命令。
- 你未来还会反复要求的规则。
- 可验证的完成标准。
- 明确的安全边界。
第四步：写第一版 AGENTS.md
控制在 80-150 行以内。越是第一版，越不要写成百科全书。
第五步：验证加载
让 Codex 总结当前指令，或从项目根目录开始一个只读任务，看它是否能复述项目规则。
第六步：做一次真实小任务
比如：
请根据当前 AGENTS.md，帮我检查新建一篇博客文章前需要遵守哪些规则。
不要改文件。
如果 Codex 能提到分类、标签、整理日期、资料核对、图片风格和发布边界，说明这份项目说明已经开始有用了。
16. 我的收藏清单
最后给一份可以直接收藏的检查表。
该写进 AGENTS.md
- 项目是什么。
- 重要目录和入口。
- 安装、运行、测试、构建命令。
- 内容、代码、接口、样式等长期约定。
- 不要做什么。
- 怎样算完成。
- 最终回复要说明什么。
不该写进 AGENTS.md
- 本次任务目标。
- 临时状态。
- 密钥、密码、Token。
- 大段资料全文。
- 和项目现状不一致的旧命令。
- 模糊口号。
- 应该由配置、rules、Skill、MCP 负责的内容。
写完后要验证
- Codex 是否能总结出当前指令。
- 子目录规则是否覆盖了根目录规则。
- 命令是否来自真实项目文件。
- 规则是否短、准、能检查。
- 有没有超过必要长度。
- 有没有把同一个规则在多个地方写出冲突版本。
17. 这篇的核心判断
AGENTS.md 的价值，不是让 Codex 变得“更听话”这么简单。
它真正的价值是：把项目里的重复摩擦变成默认上下文。
Prompt 负责本次任务，AGENTS.md 负责项目长期规则。两者分清以后，你的 Prompt 会变短，Codex 的误判会变少，review 时也更容易判断它到底有没有按项目方式工作。
下一篇会继续往工作流走：当 Prompt 和 AGENTS.md 都有了以后，怎样把一次任务拆成 Explore -> Plan -> Code -> Verify -> Review，让 Codex 不是一口气猛冲，而是按工程节奏交付。
资料来源
- OpenAI Codex：Best practices，关于把重复 Prompt 模式沉淀到
AGENTS.md、项目命令、验证和 review 规则的建议。https://developers.openai.com/codex/learn/best-practices - OpenAI Codex：Custom instructions with AGENTS.md，关于全局、项目、目录级说明的发现顺序、覆盖规则、大小限制和验证方式。https://developers.openai.com/codex/guides/agents-md
- OpenAI Codex：Customization，关于
AGENTS.md、Memories、Skills、MCP、Subagents 等不同定制层的分工。https://developers.openai.com/codex/concepts/customization - OpenAI Codex：Rules，关于命令审批、允许、禁止策略和
.rules文件的说明。https://developers.openai.com/codex/rules