软件技术分享

关于电子游戏的方方面面

Codex：AGENTS.md 最小可行模板：写什么、别写什么

作者

Codex 开工会读 AGENTS.md。短而准的 Map／约定／验收／边界，比长而虚的“最佳实践”管用；/init 只是脚手架，要改成团队真实命令。

要点

  • 发现顺序（官方）：全局 ~/.codex（AGENTS.override.md 优先于 AGENTS.md）→ 从项目根走到 cwd，每层最多一个文件（同样 override 优先）→ 更近的盖更远的；合并受 project_doc_max_bytes 约束，默认 32KiB（AGENTS.md）。
  • /init 可脚手架起步，但必须改成仓库真实的 build／test／lint（Best practices）。
  • 宜写入：repo layout；怎么跑项目；build／test／lint；工程约定与 do-not；完成定义与如何验证。重复犯错再加规则；太大则主文件精简并引用任务专文。
  • 别写：空泛 “best practices”；单次任务需求；整份 CI 配置复制；模糊“写干净代码”。
  • 最小可行四块可抄：Map／Working agreements／Verification／Boundaries；子目录用 AGENTS.override.md 覆盖特殊命令或禁区。
  • 证据强度：发现顺序与字节上限＝官方文档（高）；模板措辞＝本室编译可跟做（中高）；Cookbook 的 harness／PLANS 等是进阶可选，不必塞进最小文件。
  • 衔接：昨日《Codex 从零搭小脚本》提过 /init；本稿专讲写什么、别写什么。

正文

场景

你在空仓或旧仓里敲了 /init，得到一份看起来很全的 AGENTS.md。里面常有目录树感想，夹一句“写干净代码”，再塞半页像 README 摘要的段落。下次任务一开，模型仍问你怎么跑测试，或自创一套与 CI 无关的命令。

有文件不等于有约束。真正起作用的是里面装了什么。官方说法直白：短而准胜过长而虚；把能复用的工作约定写进去，把单次需求留在提示里（Best practices、AGENTS.md）。

可跟做步骤／可抄工作流

证据强度：高（ChatGPT Learn AGENTS／Best practices）；模板正文＝编译可跟做（中高）。

1. 先弄清它怎么“发现”文件

Codex 开工读 instruction chain（每次 run／TUI 会话起头重建），顺序是：

  1. 全局：CODEX_HOME（默认 ~/.codex）里，有 AGENTS.override.md 就用它，否则用 AGENTS.md；这一层只取第一个非空文件。
  2. 项目：从 Git 根（找不到根则只看 cwd）往下走到当前目录；每一层先找 AGENTS.override.md，再 AGENTS.md，再配置里的 fallback 名；每层最多收一个文件。
  3. 合并：从根拼到近处，空行连接；越靠近 cwd 的内容越靠后，相当于覆盖。
  4. 体积：合计触达 project_doc_max_bytes（默认 32KiB）就停；太大就拆到子目录或抬高上限，别把主文件写成百科。

自检命令（官方 Verify 思路）：

codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

2. /init 之后立刻改三处

/init 适合“有文件可改”，不适合“原样当规范”。脚手架生成后至少核对：

  • 测试／lint／build 命令是否与本仓 README／CI 一致（例如真实是 pnpm test，别留着示例 npm test）。
  • do-not 是否写到你真正怕的误伤：force-push、改密钥、动生产配置。抽象美德条目可删。
  • 有没有把“这次只修登录页”这类单次任务写进永久文件。

3. 最小可行模板（可抄，中英可混）

放到仓库根的 AGENTS.md。命令改成你的真实占位：

# AGENTS.md

## Map
- App entry: `src/`（业务）
- Tests: `tests/` 或 `**/*.test.ts`（按仓改）
- Scripts: `package.json` scripts；CI 真相以 `.github/workflows/` 为准，这里只摘要命令
- Docs for agents: `docs/agents/`（任务专文；主文件保持短）

## Working agreements
- Package manager: `pnpm`（安装依赖优先用它）
- After JS/TS edits: run `pnpm lint` then `pnpm test`
- Prefer smallest diff; do not reformat unrelated files
- New production dependency: ask before adding
- Public behavior change: update the nearest README／docs note in the same PR when applicable

## Verification
- “Done” means: the user-stated verification commands were actually run, and observed output is pasted（do not mark planned commands as passed）
- Default checks when user did not override:
  1. `pnpm lint`
  2. `pnpm test`
  3. `git diff --stat` summarized in the reply
- If a check cannot run（missing tool／env）: stop and say what is missing; do not invent green results

## Boundaries
- Do not: `git push --force`；rewrite history；commit secrets；edit files outside the workspace without asking
- Do not: bump timeouts／delete assertions／add unconditional retries to “make CI green” unless the task explicitly allows and evidence is shown
- Do not: treat this file as a dumping ground for one-off ticket requirements（put those in the prompt）
- Secrets: never print tokens；never copy `.env` contents into chat logs

全局默认可放 ~/.codex/AGENTS.md（个人口味：偏好的包管理器、确认后再加依赖）。临时全局覆盖用 ~/.codex/AGENTS.override.md，用完删掉即可恢复底稿。

4. 嵌套 override 何时用

适合：子树命令不同或禁区更严。例如支付服务：

# services/payments/AGENTS.override.md

## Working agreements
- Use `make test-payments` instead of root `pnpm test`
- Never rotate API keys without notifying the security channel

## Boundaries
- Do not modify shared billing feature flags without an explicit approval summary

同层若同时存在 AGENTS.override.md 与 AGENTS.md，只用 override（官方发现规则）。因此 override 应自洽，别假设“还会再读同层 AGENTS.md”。

从该子目录启动时，链一般是：全局 → 根 AGENTS.md → 子目录 override。

5. 变长了怎么办

Best practices 的补丁策略：主文件继续短；规划说明、专项 review、架构说明分别链到 docs/agents/*.md，在 Map 里点名。Cookbook 里的 PLANS.md／harness/build/ 适合长流程迭代，属于可选加厚，不是最小可行的必填项（Cookbook iterating workflows）。

同一错误犯第二次：让 Codex 做简短 retrospective，再把可执行的一条规则写进 AGENTS，而不是再贴一段口号。

真实用户诀窍／反例

  • 诀窍：命令写成可复制的一行。 “跑一下测试”不如 pnpm test --filter web。
  • 诀窍：Verification 要求“贴观察输出”。 堵住把计划命令抄成“已通过”。
  • 诀窍：Boundaries 写具体动词。 “别搞破坏”无效；写清 force-push、密钥与仓外路径。
  • 诀窍：重复摩擦才加规则。 文件越短，越容易被读完。
  • 反例：整份 CI YAML 粘进 AGENTS。 易超 32KiB，也易与 workflow 双源漂移。
  • 反例：堆 “follow best practices／write clean code”。 无法验证，占字节。
  • 反例：把当前 ticket 的验收写进仓库级文件。 下个任务会被错误约束。
  • 反例：子目录再放一份完整百科，与根文件重复。 用 override 只写差分。

适用边界

  • 本稿覆盖：仓库级最小可行 AGENTS.md 写什么、别写什么，以及全局／嵌套 override 的官方发现顺序。
  • 不覆盖：企业 SSO、云端 Codex Web 全流程、把 Cookbook 全套 harness 一次铺满（那是加厚玩法）。
  • UI 文案、套餐是否含 Codex CLI、字节上限默认值若产品变更，以现行 AGENTS.md 与客户端为准（待核）。
  • 模板里的 pnpm lint／pnpm test 是占位；照抄前必须换成仓库真相。

【来源与编译】