免费 AI IDE
当你让 Codex 修改一个真实项目时，最容易出现的不是代码语法错误，而是它不知道项目从哪里启动、哪些命令必须先跑、哪些文件不能改。AGENTS.md 的作用就是把这些约定写成可读取的项目说明；关键是分清目录层级、指令优先级和敏感信息边界。本文从一个小型 Python 项目开始，逐步写出可维护的 AGENTS.md，并用一次故意违规的任务验证它是否真正生效。 本文适用于需要把 Codex 接入真实仓库的个人和团队，重点解决项目规范、团队协作与隐私边界；示例以 Python 小项目为载体，但目录作用域和验收思路同样适用于前端、Java 与多包仓库。
一、先写“必须知道”的项目事实
项目说明不要从口号开始，而要从可执行事实开始：入口文件在哪里、依赖如何安装、测试命令是什么、生成物放在哪里。每条规则都应该能被一次命令或一次文件检查验证。把“代码要写好”改成“提交前运行 pytest -q，失败不得继续”会更有用。
from pathlib import Path
root = Path("w3cschool-demo")
print(root / "pyproject.toml")
print("pytest -q")运行后应看到： 输出项目根目录与测试命令，确认规则可被复制。
二、目录层级决定指令作用范围
根目录的 AGENTS.md 适合放全局约定，子目录可以补充局部规则，例如 docs/ 只允许修改 Markdown，examples/ 必须保留可运行输入。子目录规则不能悄悄推翻安全边界；遇到冲突时，先把冲突写进审查记录。
如果这里的基础语法还不熟，可以先查 Codex 安装，再回到下面的完整示例。
from pathlib import Path
for p in [Path("AGENTS.md"),Path("src/AGENTS.md"),Path("docs/AGENTS.md")]:
print(p, "exists=", p.exists())运行后应看到： 三个路径分别显示存在或不存在，便于核对作用域。
三、把可共享内容和秘密分开
仓库说明里可以写命令、目录和公共环境变量名，不能写令牌、私钥、内部域名或真实用户数据。示例配置使用 .env.example，真实值由本地环境或密钥管理器提供。提交前用 git diff --cached 检查是否把敏感内容带进补丁。
from pathlib import Path
text = Path(".env.example").read_text(encoding="utf-8") if Path(".env.example").exists() else "API_KEY=replace-me"
print("API_KEY" in text, "真实密钥不应出现在仓库")运行后应看到： 只显示变量名和占位值，不出现真实密钥。
四、用任务验收验证说明是否有效
不要只检查 AGENTS.md 能否打开，要给 Codex 一个有边界的任务：修改一个函数、运行一条测试、不要触碰指定目录。记录它是否读取了正确命令、是否保留了不该改的文件、失败时是否停下来询问。
如果这里的基础语法还不熟，可以先查 agentskills 教程，再回到下面的完整示例。
checks=["入口命令","测试命令","禁止修改目录","输出位置"]
for item in checks:
print("check:", item)运行后应看到： 逐项打印四条验收要求。
五、变更说明也要版本化
项目规则会随着构建工具和部署方式变化。修改 AGENTS.md 时写清原因、影响范围和验证结果，避免把临时排障命令永久化。团队共享规则只保留长期有效部分，个人偏好放在本地配置，不要让每个成员都被迫接受。
record={"changed":"test command","reason":"pytest moved to CI","verified":"pytest -q"}
print(record)运行后应看到： 记录中包含变更原因与实际验证命令。
可直接复制的最小模板
在项目根目录创建 AGENTS.md，先写清安装、测试和禁止修改范围：
# Project instructions
- Install: python -m pip install -r requirements.txt
- Test: pytest -q
- Entry: python -m app
- Do not edit: data/ and generated/
如果 src/AGENTS.md 与根目录规则冲突，优先采用更具体的子目录规则，但不能突破根目录的安全限制。提交前运行 git diff --check，确认没有把密钥或真实数据写进说明文件。
验收一次真实变更
在临时项目中创建 AGENTS.md、src/ 和 generated/ 三个目录。先运行 python -m pip install -r requirements.txt，再执行 pytest -q；说明文件中的入口命令应能被新成员直接复制。随后给 Codex 一个只修改 src/hello.py 的任务，并明确“不要修改 generated/”。验收时用 git status --short 检查变更范围，用 git diff --check 检查空白错误。
正常结果应同时满足：测试通过、变更只落在允许目录、终端输出包含实际运行的命令。若 Codex 修改了禁止目录，先停止合并，检查是根目录规则没有被读取，还是子目录规则写得含糊。不要用一句“请遵守规范”替代目录、命令和失败处理。
当项目有多个包时，可以在包目录增加更具体的 AGENTS.md，但不要重复整份根规则；只记录该包新增的入口、测试和限制。每次升级构建工具后，连同命令输出一起更新说明，确保文件和 CI 的真实行为一致。
怎么判断该选哪条路径
把规则分成三层：全仓库规则只写所有人都要遵守的安装、测试和安全边界；子目录只补充该模块的入口和限制；个人偏好留在本地。遇到冲突时先判断文件作用域，再看更具体的目录规则是否只是补充，而不是突破根目录的禁止项。一个好规则应当能被命令验证，例如“不得修改 generated/”可由 git diff 的路径列表判断；“代码要优雅”则无法验收，应删除或改写。
用一次受限任务验证规则
新建临时分支后，要求 Codex 只修改 src/hello.py、运行 pytest -q，并禁止触碰 generated/。任务结束后依次执行 git status --short、git diff --name-only 和 git diff --check。预期只出现 src/hello.py，测试输出为通过，空白检查没有结果。若生成目录出现变更，这不是“代码写得不好”，而是项目规范没有被正确读取或作用域写错。团队协作时应把这次失败保留为回归任务，而不是只在聊天里提醒一次。事实依据来自仓库实际 diff；没有运行 Codex 任务时，应明确写成“待验证”，不能伪造执行结果。
排错速查
| 症状 | 先检查什么 | 处理建议 |
|---|---|---|
| 规则没生效 | 检查 AGENTS.md 所在目录和任务文件路径 | 把规则移到共同祖先目录，并用受限任务重测 |
| 误改生成目录 | 检查禁止项是否写成可判断的路径 | 用 git diff --name-only 验收变更范围 |
总结
AGENTS.md 不是给 AI 背诵的长文档，而是项目运行事实、边界和验收方式的集中说明。先写命令和路径，再划分目录作用域，最后用一个可控任务验证规则确实被执行。秘密信息、个人偏好和临时排障记录要分开存放。下一步可以把安装、测试和提交检查变成项目脚本，让说明与实际命令保持一致。
延伸学习
常见问题
Q：AGENTS.md 应该写多长？
A：以能让陌生开发者完成安装、测试和一次小修改为准，优先写可验证规则，不要复制整份技术文档。
Q：可以把密钥写在 AGENTS.md 里吗？
A：不可以。写变量名和获取方式即可，真实密钥应由环境或密钥管理器注入。
