用 AGENTS.md 让 Codex 更懂你（超简单入门）

这篇文章讲清一个小技巧：用 AGENTS.md 文件给 Codex 贴“便签”，让它在你的项目里更听你指挥——包括代码风格、文件组织、命名约定、如何运行/测试等。写一次，处处生效。

它能解决什么问题？

• 团队有统一规范，但 AI 老是“跑偏”？把规范放进 AGENTS.md。
• 不同子目录有特殊约定？在子目录也放一份 AGENTS.md。
• 想告诉 Codex 如何启动/测试项目？写清命令与注意事项。

Codex 在哪里读取 AGENTS.md？（由上到下合并）

1. ~/.codex/AGENTS.md（个人全局偏好）
2. 仓库根目录的 AGENTS.md（团队/项目级说明）
3. 当前工作目录的 AGENTS.md（子目录/功能模块特定规则）

越靠后的文件，会覆盖前面的同名/同类说明。这样你就能在“全局 → 项目 → 子目录”三个层级逐步细化规则。

我该写些什么？（直接抄模板）

可以把下面这些要点写入 AGENTS.md：

• 代码风格与约束：命名风格、是否允许循环依赖、是否允许 default export 等。
• 目录结构约定：产物输出到哪、临时文件放哪、哪些目录不可改动。
• 运行与测试：本地/沙箱如何启动、要执行的测试命令、测试超时时间。
• 提交规范：提交信息格式、分支命名、是否自动修复 lints 等。
• 生成内容要求：文件命名规范、注释语言、是否附带示例/文档。

示例（可复制到 AGENTS.md）：

# Project guidance for Codex

## Code style
- Use TypeScript strict mode.
- Prefer named exports; avoid default export.
- No wildcard imports.

## Structure
- Place React components under src/components.
- Keep public API in src/index.ts.

## Run & test
- Dev: npm run dev
- Test: npm test (CI: npm run test:ci)
- Use Vitest; keep tests under __tests__.

## Do not
- Do not touch /generated or /vendor.
- Do not rename public symbols without migration notes.

如何让它生效？

• 全局偏好：创建 ~/.codex/AGENTS.md，写入你的“常驻”规则。
• 项目级：在仓库根目录新建 AGENTS.md，写团队规范与运行方式。
• 子目录：在特定模块目录再放一个 AGENTS.md，覆盖/补充本模块规则。

Codex 会按“全局 → 项目 → 子目录”的顺序合并，越近的范围越优先。

小贴士

• 先从最小必要集开始写，避免信息过载。
• 当规则更新时，记得同步根目录与子目录的 AGENTS.md。
• 和团队约定：新增模块前，先在该目录加 AGENTS.md 说明约束与期望输出。

参考

• 官方文档：“Memory with AGENTS.md” 小节
• 更多细节与示例：https://agents.md/

写好 AGENTS.md，Codex 就能更像“你团队的人”。把通用规则放全局，把项目规则放根目录，把特殊规则放子目录，合并后就能稳稳地按你的方式执行。