这是 Codex 系列的第 6 篇。
上一篇讲 Prompt 骨架：目标、上下文、约束、验收标准。那套写法解决的是“这一次任务怎么说清楚”。
但真实项目里，你很快会遇到另一个问题：有些话不应该每次都重复。
比如这个博客项目，我每次都不想重新说：
-
文章主要用中文。 -
分类只能从受控集合里选。 -
AI 文章涉及当前产品能力时，要核对官方资料。 -
不要照搬参考博客的句子和结构。 -
发布前要检查 frontmatter、摘要、标签、图片和链接。 -
不要覆盖未发布草稿或个人笔记。
这些不是某一次任务的临时要求，而是项目长期规则。长期规则继续写在 Prompt 里，会有三个问题：
-
容易漏。 -
容易前后不一致。 -
每次都占用注意力，真正的任务目标反而被埋掉。
AGENTS.md 解决的就是这件事：把反复出现的项目说明写成一个 Codex 启动时会自动读取的文件，让它在动手之前就知道这个项目怎么工作、怎么验证、哪些事情不要做。
整理日期：2026-07-12。本文涉及 Codex 的 AGENTS.md 发现顺序、作用域、覆盖规则、大小限制、验证方式等内容，主要参考 OpenAI Codex 官方文档，并结合这个博客项目当前的 AGENTS.md 实践整理。
Codex 实用教程
资料核对：已核对 OpenAI Codex 官方文档与本地 CLI 选项
适合读者：已经会给 Codex 下任务，但总在重复项目规则的人
可带走产物：判断表、三套模板、加载验证命令和维护清单
这篇解决什么问题
读完这篇，你应该能带走四样东西：
|
|
|
|---|---|
AGENTS.md
|
|
|
|
|
|
|
AGENTS.md 初稿 |
|
|
|
这篇不会追求把 AGENTS.md 写得很大。我的目标相反：写得短、准、能维护。
一分钟速览
-
Prompt 负责这一次任务， AGENTS.md负责每次进入项目都应遵守的长期规则。 -
适合写入的内容包括真实命令、目录地图、项目约定、安全提醒、验证方式和最终汇报要求。 AGENTS.md
是指导层，不是权限系统；真正的命令边界仍要交给 sandbox、approval、rules、hooks 或 CI。 -
Codex 会把全局文件与项目路径上的指导合并；同一目录存在 AGENTS.override.md时，该目录的普通AGENTS.md不会同时加载。 -
这篇最值得收藏的是第 2 节的判断表、第 6 节的 30 分钟流程、第 7-9 节的三套模板，以及第 16 节的写完后自检表。
怎么使用这篇
这篇更适合当作一份随用随查的手册，不需要从头背到尾。
|
|
|
|---|---|
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 是把重复反馈变成下次默认行为的地方。它不是万能配置文件，也不是权限系统，更不是把整份架构文档复制进去的地方。
重要边界：
AGENTS.md能告诉 Codex “应该怎么做”，但不能单独保证危险操作一定不会发生。涉及文件系统、网络、密钥、数据库和生产环境时，还要依赖 sandbox、approval、rules、hooks、CI 与人工 review 形成真正的约束。
2. 什么时候该写进 AGENTS.md
一个很简单的判断标准：
提示词
如果你已经对 Codex 说过两次，而且以后还会继续说，就考虑写进 AGENTS.md。比如：
“这个项目用 pnpm，不要用 npm install”
是否适合 AGENTS.md：适合
原因：项目长期命令约定
“所有 AI 文章都要核对官方文档”
是否适合 AGENTS.md：适合
原因：内容生产的长期质量规则
“这次只改登录页，不要碰后台”
是否适合 AGENTS.md：不适合
原因：本次任务临时范围
“帮我把这篇文章发布到线上”
是否适合 AGENTS.md：不适合
原因：这是任务目标，不是项目规则
“不要删除草稿和个人笔记”
是否适合 AGENTS.md：适合
原因：项目安全边界
“今天先别发布”
是否适合 AGENTS.md：不适合
原因：临时状态
我建议先把 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
适合放什么：某个模块的局部规则
一个关键原则：
提示词
Codex 从项目根目录走到当前工作目录，按顺序合并沿途的指导；发生冲突时，更靠近当前工作目录的规则优先。比如你在 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 当成一个无边界大文档。它会进入上下文，太大、太散、太旧，都会伤害效果。
规则没生效时，先查这 5 件事
|
|
|
|---|---|
|
|
CODEX_HOME 是否被改过 |
|
|
AGENTS.override.md |
|
|
codex --cd <subdir> 指定工作目录 |
|
|
|
|
|
project_doc_max_bytes，是否应该拆到更近的子目录 |
4. AGENTS.md 应该写什么
我会从 8 个模块开始写。
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
最小版本可以很短：
记录模板
# 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 不应该写什么
这个文件最容易犯的错，是把所有东西都塞进去。
不建议写进去的内容：
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
我自己的原则是：
提示词
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 就够了。
需要目录级说明，通常是因为项目内部真的有不同规则：
|
|
|
|---|---|
|
|
|
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.要特别注意：同一目录里存在非空的 AGENTS.override.md 时，Codex 只读取它，不会再把该目录的 AGENTS.md 合并进来。因此，override 里要么包含该层仍需保留的规则，要么就把稳定的模块规则继续写在普通 AGENTS.md 里。
但我不建议滥用 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（当前仍属实验能力）
适合放什么：命令在 sandbox 外运行时的允许、询问、禁止策略
不适合放什么：内容写作风格
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://learn.chatgpt.com/guides/best-practices> -
OpenAI Codex：Custom instructions with AGENTS.md，关于全局、项目、目录级说明的发现顺序、覆盖规则、大小限制和验证方式。<https://learn.chatgpt.com/docs/agent-configuration/agents-md> -
OpenAI Codex：Customization，关于 AGENTS.md、Memories、Skills、MCP、Subagents 等不同定制层的分工。<https://learn.chatgpt.com/docs/customization/overview> -
OpenAI Codex：Rules，关于命令审批、允许、禁止策略和 .rules文件的说明；官方当前将 Rules 标记为实验能力。<https://learn.chatgpt.com/docs/agent-configuration/rules>
订阅智宅客
AI / 技术 / 数字生活方式，新文章第一时间送到邮箱。
