AGENTS.md 项目规则指南

来源：CodexGuide - AGENTS.md (https://codexguide.ai/guide/15-agents-md.html)

AGENTS.md 是给 Codex 看的项目说明文件。它可以帮助 Codex 理解项目结构、开发命令、测试要求、代码风格和协作边界。

---

为什么需要 AGENTS.md

没有项目规则时，Codex 需要从仓库里推断很多事情：

• 用哪个包管理器
• 如何运行测试
• 哪些目录是生成物
• 哪些文件不能改
• 提交前要跑哪些检查

AGENTS.md 能把这些规则显式写下来，减少重复解释。

---

放在哪里

项目级（推荐）：在项目根目录下创建 AGENTS.md，只对当前项目生效。

全局级：在 Codex 桌面 App 的设置中，找到"个性化"，填写"自定义指令"。这里设置的对所有项目生效。

两者的区别：

• 项目级：团队共享，适合写项目规范、命令、禁止事项。
• 全局级：个人偏好，适合写通用习惯和风格。

---

推荐模板

# AGENTS.md

## 项目概览

- 项目类型：
- 主要语言：
- 关键目录：

## 常用命令

- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 运行测试：pnpm test
- 类型检查：pnpm tsc
- 格式化：pnpm format

## 代码规范

- 遵循现有代码风格。
- 不做无关重构。
- 新增功能必须补充或更新测试。

## 安全边界

- 不读取或提交 .env、密钥和私有凭证。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响。

## 交付要求

- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。

---

最小可用版本

如果你不想写太多，至少写这几项：

# AGENTS.md

## 项目命令

- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 构建：pnpm build

## 改动规则

- 修改前先阅读相关文件。
- 保持现有代码风格。
- 不提交构建产物和环境变量文件。

## 验证要求

- 文档改动运行：pnpm build
- 代码改动运行相关测试。

## 安全边界

- 不读取 .env 或任何私有凭证。
- 不执行发布、部署、数据库迁移和删除数据命令。

---

写作建议

• 越具体越好。具体命令比模糊描述有用。
• 把生成目录、构建产物、锁文件策略写清楚。
• 如果是 monorepo，请说明每个包的边界。
• 如果有特殊 lint、格式化或代码生成流程，写在命令区。
• 对安全敏感项目，单独写"禁止事项"。

---

📎 📒 返回笔记索引