AGENTS.md 项目规则

返回 Codex 教学总目录

读完能做到什么

规则文件适合保存每次都要重说的专案要求，例如测试命令与资料保留方式。它不是密码保险箱，也不会替你开启网路或提高档案权限。需要调整授权时，另看权限与沙盒；不要期待一句「允许所有操作」就改变执行环境。

开始之前

下载待办网站练习材料，解压缩后复制 expected 资料夹，将副本命名为 codex-practice。这一篇使用功能完整的参考版，避免把尚未完成的筛选功能误当成规则问题。资料皆为虚构；先不要放入私人专案或更动全域规则。

副本根目录应直接看得到 index.html、style.css、app.js、core.mjs、core.test.mjs。准备可执行的 Codex 桌面版或 CLI；测试使用 Node.js，本机预览使用 Python 3。若只是建立规则档案，可以先完成前半部，再回第一个练习专案补上工具。

最少必要概念：规则从哪里来

Codex 会组合全域与专案指引。全域位置预设在使用者目录下的 .codex；设定 CODEX_HOME 时则以该位置为准。专案部分从根目录沿路走到目前工作目录，较接近工作位置的规则可以细化前面的要求。它不会因为某个子资料夹存在，就把所有子目录的规则一次读入。

同一个目录优先选择 AGENTS.override.md，再找 AGENTS.md，再考虑已设定的替代档名；不是把同层这些档案全部相加。一般 README.md 适合向人解释专案，不会只因为是 Markdown 就自动变成规则。预设专案指引合计大小上限为 32 KiB；先移走重复说明与大型范例，比直接增加上限更容易维护。

本篇只新增练习专案的 AGENTS.md。全域偏好会影响其他专案，等你确定哪些要求真的通用，再参考config.toml 设定及官方文件处理。

官方规则发现流程找不到专案根目录时，只检查目前目录；所以本例必须从 codex-practice 根目录开始，不能从它的任意子资料夹启动后假定会往上找到规则。已有储存库的根目录与子目录比较见规则层级。需要拆分长文件时看规则与参考资料分工。

第一步：确认位置与档名

Windows 在档案总管开启 codex-practice，显示副档名，使用文字编辑器新增 AGENTS.md。确认它没有变成 AGENTS.md.txt。若用 PowerShell，在资料夹空白处开启终端机后输入下方命令；结果应列出五个练习档案。看到 expected 的上一层时，先进入正确目录再继续。

Get-Location
Get-ChildItem -Name

macOS 在 Finder 选取练习资料夹后开启终端机，或在 Terminal 使用 cd 加上拖入的资料夹路径。Linux 在档案管理员使用「在终端机开启」。两者都用下面的命令确认位置，再以纯文字编辑器建立同名档案；大小写保持一致，避免 Linux 找不到规则。

pwd
ls -a

如果目录已经有 AGENTS.md，先读取并保留原文，只合并本次需要的条目。练习副本应没有该档案；不要为了照抄步骤而覆盖另一个专案的规则。

第二步：写入一份完整规则

以下是完整档案，不需要另外安装套件。范例使用英文以便五语文章共用同一份内容；你也可以用自己熟悉的语言写规则。真正重要的是命令存在、范围具体，以及读者能确认要求是否完成。

# Small Steps practice instructions

- Work only inside this practice folder.
- Keep the existing task data format and localStorage key unchanged.
- Do not add packages or external network requests for this exercise.
- Run `node --test core.test.mjs` after changing JavaScript.
- After changing HTML or CSS, check the page at 390px and 1280px widths.
- Preserve visible keyboard focus and accessible form labels.
- In the final response, list changed files, checks run, and checks not run.
- Say why a check could not be run; do not report it as passed.

不要把「品质要好」当成唯一要求。这份范例把品质转成可观察项目：测试命令、两个画面宽度、键盘焦点与明确交付纪录。也不要贴入 npm test：本材料没有 package.json，使用不存在的命令只会让后续每次任务都卡住。

第三步：重新开始并验证载入

储存后，从练习资料夹开启一个新的 Codex 工作阶段。桌面版选择这个专案并建立新任务；CLI 则离开旧互动阶段，在该资料夹重新执行 codex。指引在工作阶段建立时读取，不要只在原对话修改档案后猜测它已重新载入。

List the AGENTS.md or AGENTS.override.md files loaded for this task.
Summarize the rules that apply to this practice folder.
Do not modify any files. If you cannot establish a source, say so.

预期能指出练习资料夹的 AGENTS.md，摘要测试、画面与交付要求。回答只是第一个线索，还要开启档案核对实际内容。若它只复述你的提示词、没有正确路径，先处理工作目录与档名问题，再做修改。

第四步：用小修改检查行为

In index.html, change the main heading to "Small steps, clear progress."
Keep the todo behavior, stored data, and other visible text unchanged.
Follow the project instructions. Show the changed file and report the checks.

预期差异主要是 index.html 的标题文字。启动预览：Windows 执行 py -m http.server 4173 --bind 127.0.0.1；macOS／Linux 执行 python3 -m http.server 4173 --bind 127.0.0.1。浏览器开启 http://127.0.0.1:4173，确认标题、两个宽度与 Tab 焦点，再新增 Read 并完成它。浏览器未提供给 Codex 时，你可以自行检查，并让它明列未执行的检查。

正常案例是修改范围正确、既有资料仍在、交付纪录符合规则。边界案例是在无浏览器环境中要求检查：合格回应应说明限制及待手动确认项目，不能捏造截图或通过结果。这也说明规则是工作指引，仍需要人或工具核对证据。

把规则逐条对到证据

本次只改 HTML，没有触发「改 JavaScript 后测试」的条件，不能因此认定 Codex 漏做。若要确认测试命令可用，可另外送出下列唯读要求；expected 副本应是 3 个通过、0 个失败。这只验证命令与回报，不代表已实测所有规则分支。

Run node --test core.test.mjs from this practice folder without editing any files.
Report the working folder, command, exit status, and test counts.
If the command cannot run, quote the error and mark the check NOT RUN.

常见问题与还原

找不到规则时，依序检查目前专案、真正副档名、档案是否为空，以及同层是否存在 override。Windows 能读到不代表大小写不同的名称在 Linux 也会生效。修正后开新工作阶段重试。

规则彼此矛盾时，先查来源层级，尤其是较深目录或全域 override。把「全站统一」与「此资料夹例外」写清楚；不要新增更多互相否定的句子。深层规则的逐层追踪会在后续专篇展开，本篇先保持单一专案档案。

Codex 没有执行测试时，先看这次是否真的改了 JavaScript，再确认 node --version 可用及 core.test.mjs 位于工作目录。缺少执行环境与规则没载入是两种不同问题；要求它回报实际错误，不要用「应该通过」代替结果。

停止预览用 Ctrl+C。还原标题时只恢复本次文字修改；若 AGENTS.md 是本篇新建，可将它移出练习资料夹保存。若修改的是原有规则，恢复自己的条目即可。移除规则不会撤销它先前造成的档案修改，新的规则状态也要在新工作阶段验证。

小练习与来源

追加一条「最终回复先列出待手动确认事项」，再开新工作阶段做一次不同标题的小修改。完成判准是能找到来源、差异仅含指定标题，而且交付顺序符合新要求。练完移除新增条目，观察下一个新工作阶段的差异。

查证日为 2026-09-14；规则发现与大小限制依 AGENTS.md 官方文件查证。练习网站与资料操作测试已在 Windows／Edge 验证；本文未将 macOS、Linux 或 Codex 规则载入宣称为本机实测。接著可读Markdown 入门、工作交接及Skills。

返回 Codex 教学总目录

阅读完整文字说明

Global to Project to Working directory

• AI 工具
• 教程
• Codex