第一次给项目添加 AGENTS.md

第一次给项目添加 AGENTS.md

这篇开始实操。

但注意：第一次添加 AGENTS.md，不要上来就让 Codex 直接写文件。

更稳的顺序是：

先只读分析项目 -> 再生成草稿 -> 你审查草稿 -> 再写入文件 -> 再让 Codex 验证

前置教程：AGENTS.md 是什么，为什么能让 Codex 更稳定
如果你还不知道哪些规则适合写进 AGENTS.md，先看前置教程。

适合谁

适合已经满足下面条件的用户：

• 已经能打开一个真实项目。
• 已经能让 Codex 做只读分析。
• 已经知道项目大概用什么技术栈。
• 想减少以后每次都重复提醒 Codex 的成本。

本篇目标

完成后，你的项目根目录会多一个：

AGENTS.md

它至少包含：

• 项目概况。
• 关键目录。
• 常用检查命令。
• 修改边界。
• 安全要求。
• 任务结束汇报要求。

第 1 步：选择一个安全项目

第一次练习不要选公司核心项目。

优先选：

• 你的练习项目。
• 静态网站项目。
• 文档项目。
• 你可以随时丢弃修改的测试仓库。

如果一定要在真实项目里做，至少先确保：

• Git 状态干净。
• 没有未提交的重要改动。
• 项目里没有明文密钥。

你可以先让 Codex 检查：

请只读检查当前项目是否适合添加 AGENTS.md。

要求：
1. 不要修改任何文件。
2. 先检查项目根目录、package.json、README、主要源码目录和现有文档。
3. 告诉我这个项目是否适合添加 AGENTS.md。
4. 如果 Git 状态噪音较多，请提醒我先处理。
5. 最后只输出判断结果和理由。

预期结果：

• Codex 不修改文件。
• Codex 会说明项目类型。
• Codex 会提示是否适合继续。

第 2 步：让 Codex 只读分析项目

确认项目适合后，继续发：

请只读分析当前项目，为编写 AGENTS.md 做准备。

要求：
1. 不要创建、修改、删除任何文件。
2. 读取项目根目录的配置文件、README、package.json 或其他构建配置。
3. 总结项目技术栈、主要目录、常用脚本、可能的检查命令。
4. 明确哪些命令是你从项目文件中确认存在的，哪些只是推测。
5. 不要把推测命令写成事实。

这里最关键的是第 4 条。

很多教程会直接写：

npm run test

但项目里可能根本没有 test 脚本。

喂饭级教程不能靠猜。

预期结果：

• Codex 会列出它看过哪些文件。
• Codex 会列出真实存在的脚本。
• Codex 会说明不确定项。

第 3 步：让 Codex 先给草稿，不要写文件

继续发：

根据刚才的只读分析，请先给我一份 AGENTS.md 草稿。

要求：
1. 只输出草稿内容，不要写入文件。
2. 不要包含 API Key、Token、密码、账号信息。
3. 不要写你没有在项目里确认过的命令。
4. 不要写“代码要优雅”这类空泛规则。
5. 草稿结构包含：项目概况、关键目录、常用检查、修改边界、安全要求、汇报要求。
6. 每条规则尽量短，能执行，能检查。

为什么不让它直接写？

因为第一版 AGENTS.md 很容易出现三类问题：

• 把推测命令写进去了。
• 规则写太宽泛。
• 把与你项目无关的通用建议塞进去了。

你先看草稿，再决定是否写入。

第 4 步：审查草稿

你要重点看 6 件事：

检查点	怎么判断
命令是否真实	能否在 package.json、pom.xml、README 等文件里找到
规则是否长期有效	是否未来每次任务都适用
是否有敏感信息	不能出现真实密钥、Token、账号
是否过于空泛	“代码优雅”“保持整洁”这种要删
是否限制过度	不要让 Codex 以后什么都不敢改
是否太长	第一版宁可短一点

如果你发现问题，直接对 Codex 说：

这份草稿先不要写入。

请按下面要求修改：
1. 删除所有没有项目文件依据的命令。
2. 删除空泛规则。
3. 保留项目概况、真实检查命令、禁止写入密钥、任务结束汇报这几类。
4. 控制在 80 行以内。

第 5 步：确认后写入 AGENTS.md

草稿确认后，再发：

这份 AGENTS.md 草稿可以写入。

请执行：
1. 在项目根目录创建或更新 AGENTS.md。
2. 只写入刚才确认过的内容。
3. 写完后检查文件内容，确认没有 API Key、Token、密码。
4. 最后告诉我文件路径和你做了哪些检查。

预期结果：

• 项目根目录出现 AGENTS.md。
• Codex 会汇报写入路径。
• Codex 会说明是否检查过敏感信息。

第 6 步：做一次只读验证

不要刚写完就让它改代码。

先让 Codex 读自己的规则：

请只读验证当前项目的 AGENTS.md 是否能被用于后续任务。

要求：
1. 不要修改任何文件。
2. 读取 AGENTS.md。
3. 用中文总结里面最重要的 5 条规则。
4. 指出是否有空泛、过时、无法执行或可能误导 Codex 的内容。
5. 如果有问题，只提出修改建议，不要直接改。

预期结果：

• Codex 能说出 AGENTS.md 的关键规则。
• Codex 能指出潜在问题。
• 没有文件被修改。

第 7 步：用一个小任务试运行

验证通过后，选一个很小的任务。

比如：

请根据 AGENTS.md 的规则，帮我检查首页文案有没有明显错别字。

要求：
1. 先说明你会遵守 AGENTS.md 里的哪些规则。
2. 只做文案检查，不要改样式。
3. 如果发现问题，先列出建议，不要直接修改。

这个任务的目的不是让 Codex 大展身手，而是确认：

• 它会主动引用项目规则。
• 它不会越权改文件。
• 它能按你的汇报格式工作。

/init 能不能用

可以。

Codex CLI 里通常可以用 /init 生成一个 AGENTS.md 脚手架。

但新手要记住：

/init 生成的是起点，不是最终答案。

你仍然要检查：

• 命令是否真实。
• 规则是否适合当前项目。
• 是否有多余模板内容。
• 是否遗漏了项目特有风险。

更稳的做法是：

请先解释 /init 生成的 AGENTS.md 每一段是什么意思，指出哪些内容适合本项目，哪些需要删除或改写。不要直接修改文件。

常见错误

错误 1：让 Codex 直接写一份万能 AGENTS.md

不要这样说：

帮我写一份 AGENTS.md。

这太宽。

应该说：

请先只读分析当前项目，再基于真实项目结构和真实脚本生成 AGENTS.md 草稿。

错误 2：把临时任务写进 AGENTS.md

比如：

本次只修改登录页。

这是当前任务限制，不是长期规则。

错误 3：把配置写进 AGENTS.md

比如：

默认模型使用 xxx。

模型和 provider 应该放在 config.toml，不是 AGENTS.md。

错误 4：让 AGENTS.md 变成超长文档

第一版尽量短。

当它超过几百行，你自己都不想读，Codex 也更难抓重点。

这一篇的验收标准

完成后你应该拿到：

• 项目根目录的 AGENTS.md。
• 一份你看过并认可的项目规则。
• 一次只读验证结果。
• 一次小任务试运行结果。

只要这四件事齐了，你就完成了第一份 AGENTS.md。

下一篇看：config.toml 是什么，和 AGENTS.md 有什么区别。