AGENTS.md 项目指令

10.1 AGENTS.md 是什么

官方 best practices 对 AGENTS.md 的定义:

Think of AGENTS.md as an open-format README for agents. It loads into context automatically and is the best place to encode how you and your team want Codex to work in a repository.

可以把 AGENTS.md 理解成**“给 AI Agent 看的项目 README”。它会在 Codex 启动时自动加载进上下文**,不需要你每次在 prompt 里重复说。

10.2 /init 快速生成初版

在 CLI 里运行斜杠命令:

/init

Codex 会分析当前项目结构,自动生成一份 starter AGENTS.md。这是一个很好的起点,但不要停在生成结果上——真正有价值的是根据项目实际情况持续修改。

10.3 推荐内容结构

一份好的 AGENTS.md 应该覆盖:

AGENTS.md

## 项目结构
- src/           源码目录
- tests/         测试目录
- docs/          文档目录
- scripts/       脚本目录

## 本地启动
- 安装依赖:pnpm install
- 启动开发:pnpm dev
- 构建:pnpm build

## 测试、构建、lint 命令
- 跑测试:pnpm test
- lint:pnpm lint
- type check:pnpm typecheck

## 工程约定
- 用 pnpm,不要用 npm 或 yarn
- 代码风格:2 空格缩进,单引号,无分号
- 提交前必须跑 lint 和 test

## PR 要求
- 一个 PR 只做一件事
- 必须包含测试
- 描述写清楚 why,不只是 what

## 禁止事项
- 不要修改 src/generated/ 目录(自动生成)
- 不要改数据库结构
- 不要引入新的依赖,除非必要

## 完成标准
- 相关测试通过
- lint 无报错
- git diff 无无关修改

10.4 多层级 AGENTS.md

AGENTS.md 可以创建在不同层级,就近优先(更靠近当前目录的文件优先级更高):

层级	位置	作用域
全局	~/.codex/AGENTS.md	个人默认,所有项目
仓库级	项目根目录 AGENTS.md	团队共享,可 check-in
子目录级	子目录 AGENTS.md	局部规则(如 src/legacy/AGENTS.md 标记遗留代码特殊规则)

💡 团队仓库的 AGENTS.md 应该 check-in 到 Git,让所有成员和 Codex 共享同一份规则。

10.5 维护策略

官方建议:

Keep it practical. A short, accurate AGENTS.md is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.

核心原则:短而准 > 长而空。

推荐维护节奏:

1. 先写最核心的启动、测试、约束
2. 当 Codex 犯同一个错误第二次,就把规则补进去
3. 如果文件变得太长,把 code review、发布流程、调试流程拆成独立文档(如 code_review.md、PLANS.md),再从 AGENTS.md 引用

📌 官方还有一条很实用的习惯:当 Codex 同样的错误犯两次,让它做个 retrospective(复盘),然后把复盘结论更新进 AGENTS.md。

10.6 与 code_review.md / PLANS.md 协同

当 AGENTS.md 变长时,拆分:

# AGENTS.md(主文件,保持精简)

## 代码审查
见 [code_review.md](./code_review.md)

## 执行计划
长任务参考 [PLANS.md](./PLANS.md) 模板

## 架构决策
见 [docs/architecture.md](./docs/architecture.md)

这样既保持主文件简洁,又能让 Codex 在需要时按引用加载详细规则。

10.7 完整 AGENTS.md 模板

可直接复制修改:

AGENTS.md

> 本文件是给 Codex 等 AI Agent 看的项目说明,自动加载进上下文。

## 项目概述
- 项目名:your-project
- 类型:Node.js 后端服务
- 语言:TypeScript

## 目录结构
- src/           源码
- src/modules/   业务模块
- src/shared/    共享代码
- tests/         测试
- scripts/       脚本

## 环境要求
- Node.js 22+
- pnpm 9+

## 常用命令
| 操作 | 命令 |
|------|------|
| 安装依赖 | pnpm install |
| 开发 | pnpm dev |
| 构建 | pnpm build |
| 测试 | pnpm test |
| 单文件测试 | pnpm test path/to/file |
| lint | pnpm lint |
| type check | pnpm typecheck |

## 工程约定
- 包管理器:pnpm(禁用 npm/yarn)
- 代码风格:Prettier + ESLint,2 空格,单引号,无分号
- 命名:变量 camelCase,类 PascalCase,常量 UPPER_SNAKE
- 注释:复杂逻辑必须注释,公开 API 必须 JSDoc

## 禁止事项
- ❌ 不要修改 src/generated/(自动生成代码)
- ❌ 不要直接改 dist/(构建产物)
- ❌ 不要引入新依赖,除非充分论证
- ❌ 不要跳过测试提交

## PR / 提交规范
- 提交信息遵循 Conventional Commits(feat: / fix: / docs: 等)
- 一个 PR 只解决一个问题
- 必须包含测试,且测试通过
- 描述说明 why,不只是 what

## 完成标准(Definition of Done)
- [ ] 实现完成
- [ ] 测试补充并通过
- [ ] lint 无报错
- [ ] type check 通过
- [ ] git diff 无无关修改
- [ ] 文档更新(如涉及 API 变更)

资料来源

• OpenAI 官方 Codex best practices——AGENTS.md 完整指南
• CSDN《Codex 使用最佳实践:别把它当聊天机器人》——AGENTS.md 维护策略中文解读
• 官方 AGENTS.md guide