Codex中文教程
登录
实战

Codex AGENTS.md 实战：从零搭建可复用的 AI 项目工作区

2026/8/275 分钟阅读

为什么你需要 AGENTS.md？

很多人用 Codex 最头疼的问题：每次开新对话都要重新解释一遍背景——项目做什么、用哪些技术、命令怎么跑、哪些目录不能动……说了半天，AI 还是经常搞错。

AGENTS.md 就是解决方案。它是一份纯 Markdown 文件，放在项目根目录，Codex 每次启动会话时自动读取。写一次，永久生效，换工具也同样支持（Cursor、Claude Code、GitHub Copilot 等）。

项目文件夹结构

一个规范的项目工作区结构如下：

my-project/
├── AGENTS.md          ← 项目指令（核心）
├── PLANS.md           ← 可选：项目路线与阶段规划
├── GOALS.md           ← 可选：目标与验收标准
├── PROMPTS.md         ← 可选：常用提示词模板
├── README.md          ← 面向人类的可读文档
├── src/               ← 源代码
├── tests/             ← 测试文件
├── outputs/           ← 交付物输出目录
└── memory.md          ← 可选：项目迭代记录

💡 Tip：/init 命令可以自动生成这套结构，在 Codex 中输入 /init，它会扫描项目目录并生成初始 AGENTS.md 草稿，你按需修改即可。

最小可用模板（6 个核心模块）

不要一开始就写几百行。先写这 6 块，等项目跑起来再逐步补充：

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + Express (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT push to main branch directly

## PR expectations
- Add tests for new features
- Run pnpm test before marking done

## Done when
- pnpm test passes
- pnpm build succeeds
- No lint errors

分层合并机制

Codex 支持多层 AGENTS.md，规则从外到内逐级覆盖：

~/.codex/AGENTS.md          ← 个人全局默认（所有项目）
└─ project-root/AGENTS.md  ← 项目级规则（覆盖全局）
   └─ services/payments/AGENTS.md  ← 子目录规则（覆盖上一层）

每个文件夹只读一个 AGENTS.md，靠近当前目录的文件优先级更高。总大小上限 32 KiB，超出会被截断。

验证 Codex 是否真的读取了 AGENTS.md

写完之后，运行这条命令确认：

codex --ask-for-approval never "Summarize the instructions you have loaded for this session"

如果 Codex 回答中提到了你的测试命令、禁止目录等规则，说明加载成功；如果答非所问，按下方排错清单检查。

常见排错清单

问题 原因 解决
规则没生效 文件名大小写错误（如 agents.md） 改为全大写 AGENTS.md
规则没生效 启动目录不在 Git 仓库根 确认当前目录是项目根，或用 --cd 指定
规则被忽略 有 AGENTS.override.md 同名覆盖 检查是否有同名 override 文件
文件过大 超过 32 KiB 被截断 精简内容，把细节移到子文件或 PLANS.md
软链接/NFS 路径 路径被映射导致识别不到 切换到物理路径启动 Codex

绝对不要放进 AGENTS.md 的内容

  1. Secrets 和 API Key：Codex 会把文件读入上下文，可能泄露。用 .env 或环境变量替代
  2. 过期的大列表：依赖版本、价格表、路由清单等——写添加规则而非完整列表
  3. 空泛口号：「保持高质量代码」→ 改成「pnpm test 必须全部通过」
  4. 不可验证的要求：「提升用户体验」→ 改成「Lighthouse Performance ≥ 90」
  5. 完整的产品愿景：AGENTS.md 是操作手册，不是品牌手册

实战：给你的自媒体项目配一份 AGENTS.md

以本教程站为例，一份实用的 AGENTS.md：

# AGENTS.md

## Project overview
Codex 中文教程站，部署在 crazyowen.cn/codex，每日更新实战栏目。

## Commands
- 生成站点：python scraper/build_static.py
- 校验链接：python scraper/validate_links.py
- 部署：bash deploy.sh
- 审计 SEO：python scraper/audit_seo.py

## Project structure
- codexguide-content/03-recipes/ ← 实战教程源文件（.md）
- site/ ← 静态站输出目录（build 后生成）
- scraper/ ← 构建脚本
- theme-src/ ← 主题源文件

## Constraints
- Do NOT manually edit files in site/ (regenerated by build_static.py)
- Do NOT deploy without running validate_links.py first
- All new recipes go into codexguide-content/03-recipes/ with date prefix

## Done when
- build_static.py runs without error
- validate_links.py reports 0 dead links
- deploy.sh succeeds

进阶：AGENTS.md 之外的配套文件

当项目复杂度上升，把不同维度的信息拆分到独立文件：

  • PLANS.md：项目路线图、阶段里程碑、验收标准
  • GOALS.md：每个任务的目标描述和「完成」定义
  • PROMPTS.md：常用提示词模板，Codex 可直接引用
  • memory.md：迭代记录、踩坑日志、决策摘要

这些文件不强制，但能让长期项目越跑越顺。

来源：Easton Dev《How to Write AGENTS.md for Codex Project Rules and Team Workflows》、OpenAI Cookbook《Iterating Development Workflows with Codex》

资料最后核对日期：2026-08-27 · 内容整理自 CodexGuide 社区公开教程