AGENTS.md 起步模板

这份模板适合已有一个小项目、希望把重复说明变成项目约定的读者。它负责记录长期有效的范围和检查方式；某一次任务的业务细节仍应写在任务卡里。不要把未填写的模板直接放进项目，再期待工具替你猜出命令。

下载与来源

版本 1.0.0，复核日期 2026-10-18，作者为 CodexCase 维护者小伟。模板是本方原创项目约定，不是官方配置文件。公开下载由仓库 examples/templates/ 单一源码生成；后续修改应回到源码再生成。

文件	用途
AGENTS.template.md	可修改的空白模板
AGENTS.filled.md	本方购物车练习填写实例
完整模板包 v1.0.0	包含 README、两种模板与填写实例

下载后先另存副本。填完项目名称、环境、范围和命令，确认所有尖括号字段已经替换，再将文件命名为 AGENTS.md 放到适用目录。已有规则时先比较内容，保留团队与用户原有约定。

按三个问题适配

第一，允许改什么、必须保留什么？写具体目录或文件，比「不要乱改」更容易检查。第二，怎样证明任务完成？写命令、运行目录和预期行为，不只写「测试通过」。第三，怎样交付未知项？要求报告未运行的检查与实际边界，避免读者把缺失证据误解为成功。

一个适配前的字段是「检查：填写测试命令」。在本方购物车练习中，它变成：

- 工作范围：修改 broken.mjs；保留用户笔记，不改固定测试。
- 环境：Node 22+，无需安装包；在 cart 目录运行。
- 验收：CART_VERSION=broken node --test cart.test.mjs。
- 修复前应失败，修复后应通过；金额使用整数分。
- 交付实际输出与 diff，并说明尚未覆盖的业务政策。

这里的命令只适用于 购物车练习。你的仓库可能需要不同安装方式、工作目录与检查范围，不能只替换项目名称。若某条命令从未运行过，先验证它，再写入长期规则；不要把不存在的脚本写成团队门槛。

放入项目后怎样验证

先在预期启动目录记录版本与当前路径，检查该目录及祖先路径是否已有 override。再用当前客户端支持的指令来源检查方式，确认文件确实被加载。本站 CLI 0.163.0 的 加载练习记录 验证了文件改名与同目录 override 的选择变化，没有调用模型。

加载确认后，用一件小任务检查执行：让修改只涉及允许范围，由维护者实际运行固定测试，核对 diff 与保留文件。模板写对和模型照做是两项不同证据。若规则没有出现，进入 AGENTS.md 排障，不要继续叠加重复规则。

维护与边界

依赖版本、目录或检查命令变化时同步更新规则；删除已经失效的约定。秘密、私人完整配置和临时错误日志不适合放进长期指令。模板本身不会安装工具、授予权限或保证所有客户端行为。

文件发现与层级依据是 OpenAI 官方 AGENTS.md 文档，于 2026-10-18 复核。希望理解规则设计时读 第 6 课；希望准确记录一次故障时用 排障报告模板。