普通人 AI 实战手册

Appearance

11 · AGENTS.md 项目说明书：把规矩提前写给 Codex ​

AGENTS.md 可以理解成项目里的“开工说明书”。 你不用每次都重复告诉 Codex： 这个项目怎么启动、怎么检查、哪些文件不要乱改、你喜欢什么写法。

把这些规则写进 AGENTS.md，Codex 进入项目时就更容易按你的方式工作。

AGENTS.md 项目说明书结构

先写够用版，不要写豪华版 ​

第一次写 AGENTS.md，只写 5 块：

  1. 项目是做什么的。
  2. 常用命令是什么。
  3. 哪些文件不要乱动。
  4. 内容或代码偏好是什么。
  5. 完成后怎么汇报。

够用，比复杂更重要。

先把你的项目规矩翻译成人话 ​

写 AGENTS.md 前，先不要想“专业格式”。 先用普通话回答 5 个问题：

  1. 这个项目是给谁看的？
  2. 改文章时最重要的标准是什么？
  3. 哪些文件不能随便改？
  4. 改完必须怎么检查？
  5. 完成后希望 Codex 怎么汇报？

把这 5 个问题答清楚，再整理成 AGENTS.md。 这比从网上复制一份复杂模板更有用。

第一步：先理解它解决什么问题 ​

没有 AGENTS.md 时，你每次都要解释：

  1. 项目是什么。
  2. 怎么启动。
  3. 怎么构建。
  4. 改完怎么检查。
  5. 哪些目录不要动。
  6. 你希望它怎么汇报。

有 AGENTS.md 后，这些内容可以提前写好。 Codex 就像进门先读一张工作须知。

第二步：小白版 AGENTS.md 不要写太复杂 ​

第一次写，不要追求专业。 先写够用的 5 块：

  1. 项目简介。
  2. 常用命令。
  3. 修改边界。
  4. 写作或代码偏好。
  5. 完成后的汇报要求。

你可以在项目根目录新建一个文件：

text
AGENTS.md

注意是大写的 AGENTS.md。

第三步：直接复制这个小白模板 ​

你可以先用这个版本：

md
# AGENTS.md

## 项目简介

这是一个写给普通人的 AI 实战教程网站。
读者大多不会编程，所以内容要清楚、具体、能照着做。

## 常用命令

- 安装依赖：pnpm install
- 本地预览：pnpm dev
- 构建检查：pnpm build

## 修改边界

- 不要删除文章文件。
- 不要改和当前任务无关的页面。
- 不要把真实密钥、手机号、账号密码写进代码或文章。
- 大范围改动前，先说明计划和影响范围。

## 内容风格

- 面向小白，优先使用“第一步、第二步、第三步”。
- 少写抽象解释，多写可复制的操作和提示词。
- 每篇文章尽量包含常见错误和检查清单。
- 涉及个人经历时，不要编造故事。

## 完成后请汇报

- 改了哪些文件。
- 为什么这样改。
- 怎么预览或验证。
- 还有哪些地方需要人工确认。

这个模板不高级。 但对小白很实用。

第四步：让 Codex 帮你创建 ​

你可以这样对 Codex 说：

text
请在项目根目录创建 AGENTS.md。
内容先用小白版项目说明书：
1. 项目简介
2. 常用命令
3. 修改边界
4. 内容风格
5. 完成后汇报要求

创建前先告诉我你准备写哪些内容。
不要修改其他文件。

如果你已经有 AGENTS.md，可以让它先读：

text
请先阅读当前项目的 AGENTS.md。
用普通话告诉我里面规定了哪些工作方式。
暂时不要修改任何文件。

第五步：把命令写准确 ​

AGENTS.md 里最容易错的是命令。 不要编。 以项目真实脚本为准。

如果你不确定，可以先问：

text
请查看当前项目的 package.json。
告诉我有哪些可用脚本。
只读取，不修改。

然后再让它更新：

text
请根据 package.json 里的真实脚本，更新 AGENTS.md 的常用命令部分。
不要编造不存在的命令。
不要修改其他部分。

第六步：把“不要做什么”写清楚 ​

AGENTS.md 不只是写怎么做。 更重要的是写边界。

比如：

md
## 禁止事项

- 不要执行删除大量文件的命令。
- 不要把 .env 文件内容展示在回复里。
- 不要未经确认安装新依赖。
- 不要重写整站设计，除非任务明确要求。

这对小白很重要。 你不一定能判断每条命令的风险，所以要提前把危险动作拦住。

第七步：一个项目可以慢慢迭代 ​

AGENTS.md 不是一次写完的。 你可以每做一类任务，就补一条规则。

比如你发现文章总是写得太像说明文，就补：

md
- 教程文章优先写成步骤，不要写成散文式说明。
- 每个步骤都要告诉读者点哪里、看哪里、确认什么。

你发现它总是忘记检查页面，就补：

md
- 修改网站内容后，必须运行构建命令。
- 如果本地预览可用，需要说明预览地址和检查页面。

这就是让项目越来越懂你的方式。

常见错误 ​

错误一：AGENTS.md 写成愿望清单

“写得专业一点”“做得更好”都太空。 要写具体规则。

错误二：命令写错

命令一错，后面检查都会错。 先读真实项目脚本。

错误三：只写要求，不写禁止

边界比要求更重要。 尤其是删除、覆盖、密钥、部署这些动作。

错误四：永远不更新

项目变了，AGENTS.md 也要变。 它是工作说明书，不是纪念碑。

检查清单 ​

你的 AGENTS.md 至少应该回答：

  • 这个项目是做什么的。
  • 常用命令是什么。
  • 哪些文件或信息不能乱动。
  • 内容或代码有什么风格要求。
  • Codex 完成后应该怎么汇报。

小结 ​

AGENTS.md 是小白最应该早点学的功能之一。 它不能替你判断所有事情，但能减少重复解释，让 Codex 更稳定地按你的规矩办事。

下一阶段开始讲核心交互：快捷命令、提示词写法、日常工作流和安全边界。